gargoyle-receipts 0.11.0.dev0__tar.gz → 0.13.0.dev0__tar.gz

{gargoyle_receipts-0.11.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.13.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.11.0.dev0
+Version: 0.13.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.13.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -292,6 +292,19 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
 ## Microsoft 365 and other targets: adapters
 
 What a held call changes is the adapter's business (`gargoyle.adapters`):
@@ -355,6 +368,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ENTRA_TENANT`, `_CLIENT_ID`, `_SCOPE`, `_TOKEN_CACHE` | instead of a fixed client token: the user's own Entra ID token, written by `gargoyle login` (device code, MSAL cache, silent refresh); the principal is their UPN. No usable token refuses `REF_TARGET_LOGIN_REQUIRED` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
+| issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.13.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -254,6 +254,19 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
 ## Microsoft 365 and other targets: adapters
 
 What a held call changes is the adapter's business (`gargoyle.adapters`):
@@ -317,6 +330,8 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | `GARGOYLE_MCP_ENTRA_TENANT`, `_CLIENT_ID`, `_SCOPE`, `_TOKEN_CACHE` | instead of a fixed client token: the user's own Entra ID token, written by `gargoyle login` (device code, MSAL cache, silent refresh); the principal is their UPN. No usable token refuses `REF_TARGET_LOGIN_REQUIRED` |
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
+| issuer `GARGOYLE_HOLDS_PATH` | SQLite file for holds, grants, declines and plans, so a restart loses nothing a person is acting on (`gargoyle issuer` sets `holds.sqlite` beside the keys); `GET /health` reports it |
+| issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
 | `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/gargoyle/cli.py

@@ -26,6 +26,8 @@ policy engine, a container runtime, or any client changes.
                       approver's machine); with --approvers N also approver-2.env ...
     approver-web.json the same key and token in the form the browser approval
                       console loads (private; same machine as approver.env)
+    gargoyle-issuer.service, apache-gargoyle.conf
+                      a systemd unit and an Apache virtual host for the issuer
     mcp-config.json   the server entry to paste into the MCP client
     public-keys.json  issuer, approver and executor public keys, for audits
 
@@ -147,6 +149,33 @@ def cmd_init(args) -> int:
         "issuer": {"issuer-1": issuer_pub}, "approver": {a[0]: a[3] for a in approvers},
         "executor": {"executor-1": executor_pub}, "identity_provider": {"idp-1": idp_pub},
     }, indent=2) + "\n")
+    _write(out / "gargoyle-issuer.service", """[Unit]
+Description=Gargoyle issuing service
+After=network-online.target
+
+[Service]
+User=gargoyle
+WorkingDirectory=%(out)s
+ExecStart=%(python)s -m gargoyle.cli issuer --out %(out)s --host 127.0.0.1 --port %(port)d
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+""" % {"out": str(out), "python": sys.executable, "port": args.port})
+    _write(out / "apache-gargoyle.conf", """# Apache in front of the issuer: TLS from a trusted CA, one virtual host.
+<VirtualHost *:443>
+    ServerName %(host)s
+    SSLEngine on
+    SSLCertificateFile    /etc/ssl/certs/gargoyle.crt
+    SSLCertificateKeyFile /etc/ssl/private/gargoyle.key
+    ProxyPreserveHost On
+    ProxyPass        / http://127.0.0.1:%(port)d/
+    ProxyPassReverse / http://127.0.0.1:%(port)d/
+    ErrorLog  ${APACHE_LOG_DIR}/gargoyle-error.log
+    CustomLog ${APACHE_LOG_DIR}/gargoyle-access.log combined
+</VirtualHost>
+""" % {"host": (args.issuer_url or "gargoyle.example").replace("https://", "").replace("http://", "").split("/")[0].split(":")[0], "port": args.port})
     upstream = (["npx", "-y", "@modelcontextprotocol/server-filesystem", allowed] if args.upstream == "npx-filesystem"
                 else [client_python, "-m", "gargoyle.fs_server", allowed])
     _write(out / "mcp-config.json", json.dumps({"mcpServers": {"filesystem-gargoyle": {
@@ -260,6 +289,8 @@ def cmd_issuer(args) -> int:
     out = Path(args.out).resolve()
     os.environ.update(_read_env(out / "issuer.env"))
     os.environ.setdefault("GARGOYLE_APPROVERS_PATH", str(out / "approvers.json"))   # enrolled approvers live beside the keys
+    os.environ.setdefault("GARGOYLE_HOLDS_PATH", str(out / "holds.sqlite"))          # holds, grants, declines, plans survive restarts
+    os.environ.setdefault("GARGOYLE_LOG_JSON", "1")
     app = app_from_env()
     # The middleware reads the policy pin from a file; write it next to the
     # config so the client-side entry finds it at the configured path.
@@ -311,6 +342,8 @@ def cmd_audit(args) -> int:
             why = (" (%s)" % r["verdict"]) if r["kind"] == "refused" and r["verdict"] else ""
             if r.get("released_by"):
                 why += " released by " + ", ".join(r["released_by"])
+            if r.get("plan"):
+                why += " (plan %s step %d)" % (str(r["plan"].get("plan_id") or "?")[:8], r["plan"].get("step", -1) + 1)
             if r.get("state"):
                 # A state-bound call: the target as it was approved, and as the run left it.
                 pre, post = (r["state"].get("pre") or "")[:8], (r["state"].get("post") or "")[:8]

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/gargoyle/consumer.py

@@ -273,6 +273,7 @@ class Consumer:
         *,
         grant: Any = None,
         now: Optional[datetime] = None,
+        plan_release: Any = None,
     ) -> Verdict:
         """Decide whether to honor `envelope` for `call` ({"tool", "args",
         "principal"}, the principal being the one this consumer
@@ -321,7 +322,26 @@ class Consumer:
         # inside the signed region, so they are the issuer's word, not the
         # caller's. The grant is checked and claimed before the receipt is
         # claimed, so a refused grant leaves the receipt unspent.
-        if envelope["requires_approval"]:
+        if envelope["requires_approval"] and plan_release is not None:
+            # A scoped grant (gargoyle.plans): the plan's step is claimed once
+            # in place of a per-call grant id.
+            from gargoyle.plans import verify_plan_release
+            approver_keys = self._approver_keys(key_record_view, envelope.get("issuer_key_id"), now)
+            if not approver_keys:
+                return Verdict(False, REF_TARGET_NO_APPROVER_TRUST)
+            r = verify_plan_release(plan_release, envelope, call, issuer_public_keys=pinned_public_keys,
+                                    approver_public_keys=approver_keys, now=now, clock_skew=self.clock_skew)
+            if not r["accepted"]:
+                return Verdict(False, r["reason"])
+            plan = plan_release["plan"]
+            try:
+                plan_exp = datetime.fromisoformat(plan["not_after"]) + self.clock_skew
+            except (ValueError, TypeError, KeyError):
+                plan_exp = None
+            if not self.replay_cache.check_and_claim("plan:%s:%d" % (plan["plan_id"], r["step"]), plan_exp, now=now):
+                from gargoyle.plans import REF_PLAN_STEP_CONSUMED
+                return Verdict(False, REF_PLAN_STEP_CONSUMED)
+        elif envelope["requires_approval"]:
             grants = as_grant_list(grant)
             if not grants:
                 return Verdict(False, REF_TARGET_APPROVAL_REQUIRED)

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/gargoyle/evidence.py

@@ -192,7 +192,7 @@ def verify_log(
             rc = rc if isinstance(rc, dict) else {}
             report.append({"seq": None, "kind": None, "tool": rc.get("tool"), "principal": rc.get("principal"),
                            "accepted": False, "reason": REF_EVIDENCE_UNCHAINED if legacy else REF_EVIDENCE_MALFORMED,
-                           "verdict": None, "released_by": [], "state": None, "client": None})
+                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None})
             all_ok = False
             continue
         e = raw
@@ -218,14 +218,19 @@ def verify_log(
                                       now=_parse_at(e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         counts[e["kind"]] += 1
-        released_by = [g.get("approver_key_id") for g in (e["grant"] if isinstance(e["grant"], list) else [e["grant"]])
-                       if isinstance(g, dict)] if e["grant"] is not None else []
+        plan_ref = None
+        grant_set = e["grant"]
+        if isinstance(grant_set, dict) and "plan" in grant_set and "step" in grant_set:
+            plan_ref = {"plan_id": (grant_set["plan"] or {}).get("plan_id"), "step": grant_set["step"]}
+            grant_set = grant_set.get("grants")
+        released_by = [g.get("approver_key_id") for g in (grant_set if isinstance(grant_set, list) else [grant_set])
+                       if isinstance(g, dict)] if grant_set is not None else []
         ex = e["execution"] if isinstance(e["execution"], dict) else {}
         state = ({"pre": ex.get("pre_state_sha256"), "post": ex.get("post_state_sha256")}
                  if ex.get("pre_state_sha256") or ex.get("post_state_sha256") else None)
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],
                        "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
-                       "state": state, "client": e.get("client")})
+                       "state": state, "client": e.get("client"), "plan": plan_ref})
         all_ok = all_ok and ok
         # The chain continues from what the file says, so one bad entry is
         # reported once rather than cascading into every later one.

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/gargoyle/execution.py

@@ -218,10 +218,17 @@ def verify_chain(
         return {"accepted": False, "reason": provenance["reason"], "steps": steps}
 
     if envelope["requires_approval"]:
-        if not as_grant_list(grant):
+        from gargoyle.plans import is_plan_release, verify_plan_release
+        if is_plan_release(grant):
+            # Released by a scoped grant: the plan, its grants and the step,
+            # re-matched against the arguments the release recorded.
+            g = verify_plan_release(grant, envelope, {}, issuer_public_keys=issuer_public_keys,
+                                    approver_public_keys=approver_public_keys or {}, now=executed_at)
+        elif not as_grant_list(grant):
             steps.append(("approval", REF_EXEC_GRANT_MISSING))
             return {"accepted": False, "reason": REF_EXEC_GRANT_MISSING, "steps": steps}
-        g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
+        else:
+            g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
         steps.append(("approval", g["reason"]))
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"], "steps": steps}

gargoyle_receipts-0.13.0.dev0/gargoyle/holdstore.py

@@ -0,0 +1,116 @@
+"""Persistent issuer state: holds, grants, declines and plans survive a restart.
+
+The issuing service keeps little state, but what it keeps is what a human
+is in the middle of acting on. In a lab the service was restarted a dozen
+times in two days and each restart dropped the holds in flight; the
+middleware then reported a timeout and the assistant retried. A client's
+approver would see a card that did nothing. This module backs each of the
+service's maps with a SQLite table (standard library, one file, one
+process), so a restart changes nothing a person can see. With no path the
+store is in memory, which is what the tests use.
+
+Dict semantics are kept on purpose: the service code reads as before,
+and a value is written back on assignment, never by mutating what a read
+returned.
+"""
+
+import json
+import sqlite3
+import threading
+from collections.abc import MutableMapping, MutableSet
+from typing import Any, Iterator, Optional
+
+ENV_HOLDS_PATH = "GARGOYLE_HOLDS_PATH"
+
+
+class HoldStore:
+    def __init__(self, path: Optional[str] = None) -> None:
+        self.path = path or ":memory:"
+        self._db = sqlite3.connect(self.path, check_same_thread=False, isolation_level=None)
+        self._lock = threading.RLock()
+        with self._lock:
+            self._db.execute("PRAGMA journal_mode=WAL") if self.path != ":memory:" else None
+            self._db.execute("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, k TEXT NOT NULL, v TEXT NOT NULL, PRIMARY KEY (ns, k))")
+
+    def dict(self, ns: str) -> "PersistentDict":
+        return PersistentDict(self, ns)
+
+    def set(self, ns: str) -> "PersistentSet":
+        return PersistentSet(self, ns)
+
+    # ---- primitives ----
+    def _get(self, ns: str, k: str) -> Any:
+        with self._lock:
+            row = self._db.execute("SELECT v FROM kv WHERE ns=? AND k=?", (ns, k)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def _has(self, ns: str, k: str) -> bool:
+        with self._lock:
+            return self._db.execute("SELECT 1 FROM kv WHERE ns=? AND k=?", (ns, k)).fetchone() is not None
+
+    def _put(self, ns: str, k: str, v: Any) -> None:
+        with self._lock:
+            self._db.execute("INSERT OR REPLACE INTO kv (ns, k, v) VALUES (?, ?, ?)", (ns, k, json.dumps(v, sort_keys=True)))
+
+    def _delete(self, ns: str, k: str) -> bool:
+        with self._lock:
+            cur = self._db.execute("DELETE FROM kv WHERE ns=? AND k=?", (ns, k))
+            return cur.rowcount > 0
+
+    def _keys(self, ns: str) -> list:
+        with self._lock:
+            return [r[0] for r in self._db.execute("SELECT k FROM kv WHERE ns=? ORDER BY rowid", (ns,)).fetchall()]
+
+    def _count(self, ns: str) -> int:
+        with self._lock:
+            return self._db.execute("SELECT COUNT(*) FROM kv WHERE ns=?", (ns,)).fetchone()[0]
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+
+class PersistentDict(MutableMapping):
+    def __init__(self, store: HoldStore, ns: str) -> None:
+        self._s, self._ns = store, ns
+
+    def __getitem__(self, k: str) -> Any:
+        if not self._s._has(self._ns, k):
+            raise KeyError(k)
+        return self._s._get(self._ns, k)
+
+    def __setitem__(self, k: str, v: Any) -> None:
+        self._s._put(self._ns, k, v)
+
+    def __delitem__(self, k: str) -> None:
+        if not self._s._delete(self._ns, k):
+            raise KeyError(k)
+
+    def __contains__(self, k: object) -> bool:
+        return isinstance(k, str) and self._s._has(self._ns, k)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._s._keys(self._ns))
+
+    def __len__(self) -> int:
+        return self._s._count(self._ns)
+
+
+class PersistentSet(MutableSet):
+    def __init__(self, store: HoldStore, ns: str) -> None:
+        self._s, self._ns = store, ns
+
+    def __contains__(self, k: object) -> bool:
+        return isinstance(k, str) and self._s._has(self._ns, k)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._s._keys(self._ns))
+
+    def __len__(self) -> int:
+        return self._s._count(self._ns)
+
+    def add(self, k: str) -> None:
+        self._s._put(self._ns, k, True)
+
+    def discard(self, k: str) -> None:
+        self._s._delete(self._ns, k)

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.13.0.dev0}/gargoyle/issuer_service.py

@@ -40,7 +40,8 @@ it again when the call runs. The pending set is in memory: one instance.
 
 import json
 import os
-from datetime import datetime, timezone
+import sys
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 
@@ -53,6 +54,9 @@ from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_
                                verify_grant)
 from gargoyle.envelope import approval_terms
 from gargoyle.state import state_sha256, valid_description
+from gargoyle.holdstore import ENV_HOLDS_PATH, HoldStore
+from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF_PLAN_STEP_REFUSED, build_plan,
+                            sign_plan, valid_step)
 from gargoyle.notify import notifier_from_env
 from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_APPROVER_ROLE, ENV_APPROVERS_PATH,
                                 ApproverRegistry, may_enroll, valid_public_key_hex)
@@ -98,16 +102,33 @@ def build_issuer_app(
     approver_role: str = DEFAULT_APPROVER_ROLE,
     approver_groups: Optional[list] = None,
     console_entra: Optional[Dict[str, str]] = None,
+    hold_store: Optional[HoldStore] = None,
+    log_events: Optional[Callable[[Dict[str, Any]], None]] = None,
 ) -> FastAPI:
     """`on_hold(envelope, args)` is called once for every new hold (gargoyle.notify
     posts it to a webhook); it is notice, not admission, and its failure
     never affects the hold."""
     app = FastAPI(title="Gargoyle issuing service")
-    app.state.pending: Dict[str, Dict[str, Any]] = {}     # approval_request_id -> envelope
-    app.state.pending_args: Dict[str, Any] = {}           # approval_request_id -> the call's arguments
-    app.state.pending_state: Dict[str, Any] = {}          # approval_request_id -> the target's state when held
-    app.state.grants: Dict[str, Dict[str, Any]] = {}      # approval_request_id -> grant
-    app.state.declined: set = set()                       # approval_request_ids a human refused
+    # Everything a human may be in the middle of acting on lives in the hold
+    # store (gargoyle.holdstore): SQLite on disk in a deployment, memory in tests.
+    store = hold_store if hold_store is not None else HoldStore(None)
+    app.state.store = store
+    app.state.pending = store.dict("pending")             # approval_request_id -> envelope
+    app.state.pending_args = store.dict("pending_args")   # approval_request_id -> the call's arguments
+    app.state.pending_state = store.dict("pending_state") # approval_request_id -> the target's state when held
+    app.state.grants = store.dict("grants")               # approval_request_id -> [grant, ...]
+    app.state.declined = store.set("declined")            # approval_request_ids a human refused
+    app.state.pending_plans = store.dict("pending_plans") # approval_request_id -> signed plan (gargoyle.plans)
+    app.state.started_at = now().isoformat()
+
+    def event(kind: str, **fields: Any) -> None:
+        """One structured line per decision the service makes, for the
+        operator's log; never the admission path."""
+        if log_events is not None:
+            try:
+                log_events({"event": kind, "at": now().isoformat(), **fields})
+            except Exception:
+                pass
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
     static_approvers = dict(approver_public_keys or {})
 
@@ -163,8 +184,24 @@ def build_issuer_app(
         result = issue(policy, body["target_url"], interaction, signing_key=signing_key, key_id=key_id,
                        ttl_seconds=ttl_seconds, now=now())
         if result.envelope is None:
+            event("refused", principal=who["principal"], tool=body["tool"], reason=result.decision.reason)
             return {"issued": False, "reason": result.decision.reason}
-        if result.envelope["requires_approval"]:
+        covered = False
+        plan_id = body.get("plan_id")
+        if result.envelope["requires_approval"] and isinstance(plan_id, str):
+            # The executor says an approved plan covers this call. No card then:
+            # the executor enforces the plan (step single use, grants, expiry)
+            # and the console should not show a hold nobody needs to act on.
+            # A false claim costs nothing here: without a valid release the
+            # executor refuses the call.
+            from gargoyle.plans import match_step
+            for arid_p, plan in app.state.pending_plans.items():
+                if plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None:
+                    covered = True
+                    break
+        event("issued", principal=who["principal"], tool=body["tool"], held=bool(result.envelope["requires_approval"]),
+              covered=covered, decision_id=result.envelope.get("decision_id"))
+        if result.envelope["requires_approval"] and not covered:
             arid = result.envelope["approval_request_id"]
             app.state.pending[arid] = result.envelope
             app.state.pending_args[arid] = body["args"]
@@ -178,11 +215,76 @@ def build_issuer_app(
                     sys.stderr.write("gargoyle: on_hold failed: %s\n" % exc)
         return {"issued": True, "envelope": result.envelope}
 
+    @app.post("/plans")
+    async def post_plan(request: Request, authorization: Optional[str] = Header(default=None)):
+        """A scoped grant request: every step judged by the policy; the plan
+        signed and held when any step would be. Steps with exact arguments
+        are judged on them; a pattern step is judged with its patterns as the
+        argument values, so a broad pattern fails a narrow rule."""
+        who = authenticate(authorization)
+        try:
+            body = await request.json()
+        except Exception:
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        steps = body.get("steps") if isinstance(body, dict) else None
+        if (not isinstance(body, dict) or not isinstance(body.get("target_url"), str) or not isinstance(steps, list)
+                or not steps or len(steps) > 200 or not all(valid_step(s) or ("args" in s and isinstance(s.get("tool"), str)) for s in steps)
+                or not isinstance(body.get("note", ""), str)):
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        from gargoyle.envelope import args_sha256
+        norm, held, required, approvers = [], False, 1, set()
+        for s in steps:
+            if "args" in s:
+                judged_args, step = s["args"], {"tool": s["tool"], "args_sha256": args_sha256(s["args"])}
+            elif "args_sha256" in s:
+                return {"issued": False, "reason": REF_PLAN_MALFORMED}        # a hash alone cannot be judged
+            else:
+                judged_args, step = dict(s["match"]), {"tool": s["tool"], "match": dict(s["match"])}
+            interaction = {"tool": s["tool"], "args": judged_args, "principal": who["principal"],
+                           "groups": who.get("groups", []), "roles": who.get("roles", [])}
+            try:
+                d = policy.decide(body["target_url"], interaction)
+            except Exception:
+                return {"issued": False, "reason": REF_PLAN_STEP_REFUSED}
+            if not d.eligible:
+                return {"issued": False, "reason": REF_PLAN_STEP_REFUSED, "step": len(norm)}
+            if d.requires_approval:
+                if not d.plannable:
+                    return {"issued": False, "reason": REF_PLAN_STEP_NOT_PLANNABLE, "step": len(norm)}
+                held = True
+                required = max(required, d.approvals_required)
+                if d.approvers:
+                    approvers.update(d.approvers)
+            norm.append(step)
+        import uuid
+        approval = None
+        if required > 1 or approvers:
+            approval = {"required": required, **({"approvers": sorted(approvers)} if approvers else {})}
+        plan = sign_plan(build_plan(plan_id=str(uuid.uuid4()), approval_request_id=str(uuid.uuid4()), target_url=body["target_url"],
+                                    principal=who["principal"], policy_pin=policy.pin(), steps=norm,
+                                    not_after=now() + timedelta(seconds=min(ttl_seconds * 6, 3600)), note=body.get("note", ""),
+                                    approval=approval), signing_key, key_id)
+        if held:
+            app.state.pending_plans[plan["approval_request_id"]] = plan
+        event("plan", principal=who["principal"], steps=len(norm), held=held, plan_id=plan["plan_id"])
+        return {"issued": True, "plan": plan, "held": held}
+
+    def _plan_terms(plan):
+        return approval_terms({"approval": plan["approval"]} if "approval" in plan else {})
+
     @app.get("/pending")
     async def pending(authorization: Optional[str] = Header(default=None)):
         authenticate(authorization)
         current = now()
         live = {}
+        for arid, plan in list(app.state.pending_plans.items()):
+            if datetime.fromisoformat(plan["not_after"]) <= current:
+                del app.state.pending_plans[arid]
+                app.state.grants.pop(arid, None)
+            elif len(app.state.grants.get(arid, [])) < _plan_terms(plan)["required"]:
+                have = app.state.grants.get(arid, [])
+                live[arid] = {"plan": plan, "collected": len(have), "required": _plan_terms(plan)["required"],
+                              "approvers": [g["approver_key_id"] for g in have]}
         for arid, env in list(app.state.pending.items()):
             if datetime.fromisoformat(env["not_after"]) <= current:
                 del app.state.pending[arid]           # an expired hold can never be released
@@ -199,7 +301,10 @@ def build_issuer_app(
 
     def _complete(arid: str) -> bool:
         env = app.state.pending.get(arid)
-        return env is not None and len(app.state.grants.get(arid, [])) >= approval_terms(env)["required"]
+        if env is None:
+            plan = app.state.pending_plans.get(arid)
+            return plan is not None and len(app.state.grants.get(arid, [])) >= _plan_terms(plan)["required"]
+        return len(app.state.grants.get(arid, [])) >= approval_terms(env)["required"]
 
     @app.post("/grants")
     async def post_grant(request: Request, authorization: Optional[str] = Header(default=None)):
@@ -210,24 +315,28 @@ def build_issuer_app(
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         arid = grant.get("approval_request_id") if isinstance(grant, dict) else None
         env = app.state.pending.get(arid) if isinstance(arid, str) else None
-        if env is None:
+        plan = app.state.pending_plans.get(arid) if isinstance(arid, str) else None
+        if env is None and plan is None:
             return {"accepted": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
         trusted = approver_keys()
         if not trusted:
             return {"accepted": False, "reason": REF_ISSUER_NO_APPROVER_TRUST}
-        g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"],
+        g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"] if env else plan["plan_sha256"],
                          expected_approval_request_id=arid, approver_public_keys=trusted,
                          gate_key_id=key_id, now=now())
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"]}
-        # The receipt's own terms: distinct approvers, from the named set if any.
-        terms = approval_terms(env)
-        have = app.state.grants.setdefault(arid, [])
+        # The receipt's (or plan's) own terms: distinct approvers, from the named set if any.
+        terms = approval_terms(env) if env else _plan_terms(plan)
+        have = list(app.state.grants.get(arid, []))
         if any(h["approver_key_id"] == grant["approver_key_id"] for h in have):
             return {"accepted": False, "reason": REF_APPROVAL_DUPLICATE_APPROVER}
         if terms["approvers"] is not None and grant["approver_key_id"] not in terms["approvers"]:
             return {"accepted": False, "reason": REF_APPROVAL_APPROVER_NOT_ELIGIBLE}
         have.append(grant)
+        app.state.grants[arid] = have                      # written back: the store persists on assignment
+        event("granted", approval_request_id=arid, approver=grant["approver_key_id"], collected=len(have), required=terms["required"],
+              hold_kind="plan" if plan else "receipt")
         return {"accepted": True, "reason": g["reason"], "collected": len(have), "required": terms["required"],
                 "complete": len(have) >= terms["required"]}
 
@@ -235,31 +344,33 @@ def build_issuer_app(
     async def decline(request: Request, authorization: Optional[str] = Header(default=None)):
         """A human's refusal: the hold is dropped, a waiting middleware learns
         at once. No signature is needed to say no; nothing can run on it."""
-        authenticate(authorization)
+        who = authenticate(authorization)
         try:
             body = await request.json()
         except Exception:
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         arid = body.get("approval_request_id") if isinstance(body, dict) else None
-        if not isinstance(arid, str) or arid not in app.state.pending:
+        if not isinstance(arid, str) or (arid not in app.state.pending and arid not in app.state.pending_plans):
             return {"declined": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
-        del app.state.pending[arid]
+        app.state.pending_plans.pop(arid, None)
+        app.state.pending.pop(arid, None)
         app.state.pending_args.pop(arid, None)
         app.state.pending_state.pop(arid, None)
         app.state.grants.pop(arid, None)
         app.state.declined.add(arid)
+        event("declined", approval_request_id=arid, by=who["principal"])
         return {"declined": True, "reason": None}
 
     @app.get("/grants/{approval_request_id}")
     async def get_grant(approval_request_id: str, authorization: Optional[str] = Header(default=None)):
         authenticate(authorization)
-        env = app.state.pending.get(approval_request_id)
+        env = app.state.pending.get(approval_request_id) or app.state.pending_plans.get(approval_request_id)
         have = app.state.grants.get(approval_request_id, [])
         complete = _complete(approval_request_id)
         return {"pending": env is not None,
                 "grant": have[0] if complete and len(have) == 1 else None,
                 "grants": list(have) if complete else [],
-                "collected": len(have), "required": approval_terms(env)["required"] if env else None,
+                "collected": len(have), "required": (_plan_terms(env) if env and "plan_version" in env else approval_terms(env))["required"] if env else None,
                 "declined": approval_request_id in app.state.declined}
 
     @app.get("/approvers")
@@ -284,6 +395,7 @@ def build_issuer_app(
         if not isinstance(body, dict) or not valid_public_key_hex(body.get("public_key_hex")):
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         result = registry.enroll(who["principal"], body["public_key_hex"], now=now())
+        event("enrolled", approver=who["principal"], replaced=result["replaced"])
         return {"enrolled": True, "key_id": who["principal"], "replaced": result["replaced"]}
 
     @app.get("/me")
@@ -296,6 +408,15 @@ def build_issuer_app(
         return {"principal": upn, "may_approve": may_enroll(who, role=approver_role, groups=approver_groups) or upn in static_approvers,
                 "enrolled_public_key_hex": registry.public_hex().get(upn)}
 
+    @app.get("/health")
+    async def health():
+        """Public, for a monitor: the service is up, which policy it runs,
+        how much is waiting, and since when. No secrets."""
+        return {"ok": True, "policy": policy.pin(), "issuer_key_id": key_id,
+                "pending_receipts": len(app.state.pending), "pending_plans": len(app.state.pending_plans),
+                "enrolled_approvers": len(registry.public_hex()), "static_approvers": len(static_approvers),
+                "entra": bool(console_entra), "persistent": store.path != ":memory:", "started_at": app.state.started_at}
+
     @app.get("/approve-config")
     async def approve_config():
         """Public: how the console signs in. `entra` is null when the site
@@ -370,6 +491,8 @@ def app_from_env() -> FastAPI:
         audience=os.environ.get(ENV_AUDIENCE) or None,
         ttl_seconds=int(os.environ.get(ENV_RECEIPT_TTL, DEFAULT_TTL_SECONDS)),
         on_hold=notifier_from_env(os.environ),
+        hold_store=HoldStore(os.environ.get(ENV_HOLDS_PATH) or None),
+        log_events=(lambda e: sys.stderr.write(json.dumps(e, sort_keys=True) + "\n")) if os.environ.get("GARGOYLE_LOG_JSON") else None,
         approver_registry=ApproverRegistry(os.environ.get(ENV_APPROVERS_PATH)),
         approver_role=os.environ.get(ENV_APPROVER_ROLE, DEFAULT_APPROVER_ROLE),
         approver_groups=[g.strip() for g in os.environ.get(ENV_APPROVER_GROUPS, "").split(",") if g.strip()] or None,