mcpgawk 0.1.72__tar.gz → 0.1.73__tar.gz

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mcpgawk",
   "description": "Measure the MCP servers your agent calls, record the tool surface you approved, and refuse a changed tool until a person has looked. Local-first.",
-  "version": "0.1.71",
+  "version": "0.1.72",
   "author": {
     "name": "Nativerse",
     "email": "hello@nativerse-ventures.com"
@@ -27,7 +27,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "mcpgawk==0.1.71",
+        "mcpgawk==0.1.72",
         "mcpgawk",
         "mcp"
       ]

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/.github/workflows/publish-pypi.yml

@@ -37,6 +37,13 @@ jobs:
   publish:
     needs: test
     runs-on: ubuntu-latest
+    # TRUSTED PUBLISHING (2026-10-08). PyPI trusts THIS workflow in THIS repo (configured on pypi.org:
+    # gawk-dev/mcpgawk, publish-pypi.yml) instead of a long-lived API token: nothing to leak, and every
+    # upload carries a signed PEP 740 attestation naming the repo and workflow that built it, so a
+    # user can verify where their mcpgawk came from. id-token is the only extra permission it needs.
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@v4
 
@@ -44,12 +51,6 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Fail loudly if the PyPI token isn't configured
-        run: |
-          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
-            echo "::error::PYPI_API_TOKEN secret is not set — add it under repo Settings > Secrets before this can publish."
-            exit 1
-          fi
 
       - name: Skip if this version is already published (re-running main shouldn't re-publish)
         run: |
@@ -86,7 +87,7 @@ jobs:
       # gate still green — and PyPI has no unpublish, so the mistake is permanent.
       #
       # So the check runs on the BUILT artefacts, in the job that uploads them, after `build` and
-      # before `twine`. It also fails on OVER-exclusion (a wheel with no `_bundled/verify` is a
+      # before the upload. It also fails on OVER-exclusion (a wheel with no `_bundled/verify` is a
       # broken free product) and on credential-shaped strings. Exit 2 means "could not check" and
       # is treated exactly like a failure — never publish something unverified.
       #
@@ -96,31 +97,27 @@ jobs:
         if: env.SKIP != '1'
         run: python scripts/verify_public_artifact.py dist/*.whl dist/*.tar.gz
 
-      - name: Publish to PyPI
+      # skip-existing: a retry is idempotent (2026-07-23, 0.1.7: upload.pypi.org timed out AFTER both
+      # files had landed — a red run over a successful publish). One retry rides out a transient
+      # blip; the next step, not this one, is the evidence that a release actually shipped.
+      - name: Publish to PyPI (trusted publishing, signed attestations)
+        id: upload
         if: env.SKIP != '1'
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: |
-          python -m pip install twine
-          # --skip-existing + retry: on 2026-07-23 (0.1.7) upload.pypi.org connect-timeouts made
-          # twine exit 1 AFTER both artefacts had already landed — a RED run over a SUCCESSFUL
-          # publish, and a plain re-run would then fail with "file already exists". --skip-existing
-          # makes a retry idempotent (already-uploaded files are skipped, not errored); the loop
-          # rides out a transient network blip instead of failing the whole release on it.
-          for attempt in 1 2 3; do
-            if twine upload --non-interactive --skip-existing dist/*; then
-              echo "upload ok (attempt $attempt)"; exit 0
-            fi
-            echo "::warning::twine upload attempt $attempt failed (likely a transient upload.pypi.org timeout) — retrying"
-            sleep 20
-          done
-          echo "::error::twine upload failed after 3 attempts"; exit 1
+        continue-on-error: true
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Retry the upload once after a transient failure
+        if: env.SKIP != '1' && steps.upload.outcome == 'failure'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
 
       - name: PyPI must actually serve the version we just built
         if: env.SKIP != '1'
         run: |
-          # `twine --skip-existing` exits 0 when it uploaded NOTHING, so "upload ok" is not
+          # An upload with skip-existing exits 0 when it uploaded NOTHING, so "upload ok" is not
           # evidence of a release. This step is the evidence: PyPI itself must name our
           # version as the current one. Without it a publish can ship nothing and still go
           # green — which is exactly what happened on 2026-08-19.

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/.mcp.json

@@ -4,7 +4,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "mcpgawk==0.1.71",
+        "mcpgawk==0.1.72",
         "mcpgawk",
         "mcp"
       ]

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcpgawk
-Version: 0.1.72
+Version: 0.1.73
 Summary: One gateway in front of every MCP server your agents can reach — every call checked against a baseline you approved. Local-first: nothing leaves your machine.
 Project-URL: Homepage, https://mcp.gawk.dev
 Project-URL: Documentation, https://mcp.gawk.dev/docs
@@ -42,6 +42,7 @@ Description-Content-Type: text/markdown
   </picture>
 </p>
 <p align="center"><em>One gateway in the path. On your machine.</em></p>
+<p align="center"><a href="https://www.producthunt.com/products/mcpgawk?launch=mcpgawk"><img alt="mcpgawk on Product Hunt" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1259498&theme=light" width="250" height="54"></a><br>Featured on Product Hunt.</p>
 
 # mcpgawk
 <!-- mcp-name: io.github.gawk-dev/mcpgawk -->
@@ -63,12 +64,12 @@ The same engine powers **mcpgawk Platform**: `mcpgawk enforce` puts one endpoint
 whole fleet with a key per caller, policy on every call and a hash-chained audit log, and
 `mcpgawk monitor` watches the servers you approved around the clock and tells you when one drifts.
 This free layer is the seeing and the blocking underneath it. mcpgawk Platform is one subscription
-per person for up to 3 machines: start a free 7-day trial at https://mcp.gawk.dev/trial.html
+per person for up to 3 machines: start a free 7-day trial at https://mcp.gawk.dev/trial.html?utm_source=github&utm_medium=readme
 (no card) or subscribe at https://mcp.gawk.dev/subscribe. Then `mcpgawk login <key>` on this same
 install fetches the paid engine and turns those on — one more command, nothing else to set up.
 
 <p align="center">
-  <a href="https://mcp.gawk.dev/#watch"><img src="https://mcp.gawk.dev/assets/video/mcpgawk-launch-poster.jpg" width="720"
+  <a href="https://mcp.gawk.dev/?utm_source=github&utm_medium=readme#watch"><img src="https://mcp.gawk.dev/assets/video/mcpgawk-launch-poster.jpg" width="720"
        alt="mcpgawk in 64 seconds: a tool you approved changes in an update, and mcpgawk refuses the call until you decide. Watch the video."></a>
 </p>
 <p align="center"><sub><b>Watch: mcpgawk in 64 seconds.</b> A tool you approved changes in an update; mcpgawk refuses the call until you decide.</sub></p>
@@ -129,6 +130,8 @@ request, used or not.
 
 ## Get it — three ways
 
+[![Install mcpgawk from PyPI, the VS Code Marketplace or Open VSX (13-second film)](https://mcp.gawk.dev/assets/video/mcpgawk-registries-poster.jpg)](https://youtu.be/Gu-6oriEBio)
+
 **CLI** (any terminal):
 ```bash
 uv tool install --force mcpgawk      # or: pipx install --force mcpgawk
@@ -137,7 +140,7 @@ mcpgawk                              # finds every agent config on the machine i
 
 Run it as an MCP server: `mcpgawk mcp` (stdio), or `uvx mcpgawk mcp`.
 
-**Editor** (VS Code / Cursor): install **mcpgawk** from the marketplace ([Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk)). It scans your workspace `mcp.json` and shows cost + capability flags inline. The extension drives this engine as a subprocess — it is built and released separately, so its source is not in this repository.
+**Editor** (VS Code / Cursor): install **mcpgawk** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gawk-dev.mcpgawk) or [Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk). It scans your workspace `mcp.json` and shows cost + capability flags inline. The extension drives this engine as a subprocess — it is built and released separately, so its source is not in this repository.
 
 **CI** (GitHub Action): gate every PR on token budget / drift ([Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)):
 ```yaml
@@ -243,7 +246,7 @@ boundaries in [THREAT-MODEL.md](THREAT-MODEL.md). Security reports go through [S
 
 ## License
 
-**Apache-2.0** — see [LICENSE](LICENSE). Part of the [**nativerse**](https://nativerse-ventures.com/) · [gawk.dev](https://gawk.dev/) family. Site and docs: [mcp.gawk.dev](https://mcp.gawk.dev/). The value is in the
+**Apache-2.0** — see [LICENSE](LICENSE). Part of the [**nativerse**](https://nativerse-ventures.com/) · [gawk.dev](https://gawk.dev/) family. Site and docs: [mcp.gawk.dev](https://mcp.gawk.dev/?utm_source=github&utm_medium=readme). The value is in the
 repo, not a cloud.
 
 ## Use it from your agent (skill)

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/README.md

@@ -5,6 +5,7 @@
   </picture>
 </p>
 <p align="center"><em>One gateway in the path. On your machine.</em></p>
+<p align="center"><a href="https://www.producthunt.com/products/mcpgawk?launch=mcpgawk"><img alt="mcpgawk on Product Hunt" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1259498&theme=light" width="250" height="54"></a><br>Featured on Product Hunt.</p>
 
 # mcpgawk
 <!-- mcp-name: io.github.gawk-dev/mcpgawk -->
@@ -26,12 +27,12 @@ The same engine powers **mcpgawk Platform**: `mcpgawk enforce` puts one endpoint
 whole fleet with a key per caller, policy on every call and a hash-chained audit log, and
 `mcpgawk monitor` watches the servers you approved around the clock and tells you when one drifts.
 This free layer is the seeing and the blocking underneath it. mcpgawk Platform is one subscription
-per person for up to 3 machines: start a free 7-day trial at https://mcp.gawk.dev/trial.html
+per person for up to 3 machines: start a free 7-day trial at https://mcp.gawk.dev/trial.html?utm_source=github&utm_medium=readme
 (no card) or subscribe at https://mcp.gawk.dev/subscribe. Then `mcpgawk login <key>` on this same
 install fetches the paid engine and turns those on — one more command, nothing else to set up.
 
 <p align="center">
-  <a href="https://mcp.gawk.dev/#watch"><img src="https://mcp.gawk.dev/assets/video/mcpgawk-launch-poster.jpg" width="720"
+  <a href="https://mcp.gawk.dev/?utm_source=github&utm_medium=readme#watch"><img src="https://mcp.gawk.dev/assets/video/mcpgawk-launch-poster.jpg" width="720"
        alt="mcpgawk in 64 seconds: a tool you approved changes in an update, and mcpgawk refuses the call until you decide. Watch the video."></a>
 </p>
 <p align="center"><sub><b>Watch: mcpgawk in 64 seconds.</b> A tool you approved changes in an update; mcpgawk refuses the call until you decide.</sub></p>
@@ -92,6 +93,8 @@ request, used or not.
 
 ## Get it — three ways
 
+[![Install mcpgawk from PyPI, the VS Code Marketplace or Open VSX (13-second film)](https://mcp.gawk.dev/assets/video/mcpgawk-registries-poster.jpg)](https://youtu.be/Gu-6oriEBio)
+
 **CLI** (any terminal):
 ```bash
 uv tool install --force mcpgawk      # or: pipx install --force mcpgawk
@@ -100,7 +103,7 @@ mcpgawk                              # finds every agent config on the machine i
 
 Run it as an MCP server: `mcpgawk mcp` (stdio), or `uvx mcpgawk mcp`.
 
-**Editor** (VS Code / Cursor): install **mcpgawk** from the marketplace ([Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk)). It scans your workspace `mcp.json` and shows cost + capability flags inline. The extension drives this engine as a subprocess — it is built and released separately, so its source is not in this repository.
+**Editor** (VS Code / Cursor): install **mcpgawk** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gawk-dev.mcpgawk) or [Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk). It scans your workspace `mcp.json` and shows cost + capability flags inline. The extension drives this engine as a subprocess — it is built and released separately, so its source is not in this repository.
 
 **CI** (GitHub Action): gate every PR on token budget / drift ([Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)):
 ```yaml
@@ -206,7 +209,7 @@ boundaries in [THREAT-MODEL.md](THREAT-MODEL.md). Security reports go through [S
 
 ## License
 
-**Apache-2.0** — see [LICENSE](LICENSE). Part of the [**nativerse**](https://nativerse-ventures.com/) · [gawk.dev](https://gawk.dev/) family. Site and docs: [mcp.gawk.dev](https://mcp.gawk.dev/). The value is in the
+**Apache-2.0** — see [LICENSE](LICENSE). Part of the [**nativerse**](https://nativerse-ventures.com/) · [gawk.dev](https://gawk.dev/) family. Site and docs: [mcp.gawk.dev](https://mcp.gawk.dev/?utm_source=github&utm_medium=readme). The value is in the
 repo, not a cloud.
 
 ## Use it from your agent (skill)

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcpgawk"
-version = "0.1.72"
+version = "0.1.73"
 description = "One gateway in front of every MCP server your agents can reach — every call checked against a baseline you approved. Local-first: nothing leaves your machine."
 readme = "README.md"
 requires-python = ">=3.10"

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/gawk-dev/mcpgawk",
     "source": "github"
   },
-  "version": "0.1.72",
+  "version": "0.1.73",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "mcpgawk",
-      "version": "0.1.72",
+      "version": "0.1.73",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/src/mcpgawk/baseline.py

@@ -155,6 +155,11 @@ def export(path: str | None = None) -> dict[str, Any]:
             "approved_by": entry.get("approved_by"),
             # "approve" / "first-sighting" / None (older than the field). Additive.
             "baseline_origin": history.baseline_origin(store, key),
+            # Why an "unattended" baseline had no person behind it (`history.unattended_reason`), or None.
+            "unattended_reason": history.unattended_reason(store, key),
+            # What the approval accepted against the previous one, and why if the person said.
+            "approved_change": entry.get("approved_change"),
+            "approved_reason": entry.get("approved_reason"),
             "measured_at": rec.get("measured_at"),        # the sighting's time — a different fact
             "aliases": list(entry.get("aliases") or []),
             "annotations": {
@@ -219,6 +224,7 @@ def publish(key: str, *, pin: str, tools: dict[str, str], approved_at: str,
     decision, the same file — correctly refused at exit 4.
     """
     history.require_human_approval()
+    evidence = history.approval_evidence("pillar")
     p = path or history.default_path()
     with history.locked(p):
         store = history.load(p)
@@ -273,6 +279,7 @@ def publish(key: str, *, pin: str, tools: dict[str, str], approved_at: str,
             record.pop("annotations", None)
         entry["approved"] = record
         entry["approved_via"] = "approve"     # gated by require_human_approval above
+        entry["approved_evidence"] = evidence
         if alias:
             entry["aliases"] = sorted(set(entry.get("aliases", [])) | {alias})
         # The same approval, so the same fleet admission: a monitor approve of an appeared server

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/src/mcpgawk/cli.py

@@ -686,6 +686,8 @@ def build_parser() -> argparse.ArgumentParser:
     a.add_argument("--fleet", action="store_true",
                    help="accept every server now in your agent configs as your fleet; a server "
                         "that appears later is named instead of trusted")
+    a.add_argument("--reason", metavar="TEXT",
+                   help="why you are accepting this change; kept on the approval record")
 
     w = sub.add_parser(
         "wrong",
@@ -1070,7 +1072,12 @@ def _baseline(args) -> int:
         print(f"  {key}{alias}")
         print(f"    pin        {rec.get('pin') or '—'}")
         print(f"    tools      {len(rec.get('tools') or {})}")
-        if rec.get("approved_at"):
+        if rec.get("baseline_origin") == "unattended":
+            # An approval nobody was present for (slice 1, FOUNDER 2026-10-05 "Block + name it"): never
+            # "by <user>", which reads as that person's decision.
+            print(f"    approved   {rec.get('approved_at') or '—'} · "
+                  f"{rec.get('unattended_reason') or 'approved without a person present'}")
+        elif rec.get("approved_at"):
             print(f"    approved   {rec['approved_at']}"
                   f"{' by ' + rec['approved_by'] if rec.get('approved_by') else ''}")
         elif rec.get("baseline_origin") == "fleet":
@@ -1086,6 +1093,12 @@ def _baseline(args) -> int:
             # Before 2026-09-03 the sighting's time was printed under "approved": a borrowed date.
             print(f"    approved   time and actor not recorded · baseline measured "
                   f"{rec.get('measured_at') or '—'}")
+        # WHAT that approval accepted and WHY (absent on approvals older than the field).
+        change = history.change_words(rec.get("approved_change"))
+        if change:
+            print(f"    change     {change}")
+        if rec.get("approved_reason"):
+            print(f"    reason     {rec['approved_reason']}")
     return 0
 
 
@@ -1327,7 +1340,7 @@ def _approve(args) -> int:
         return 2
 
     for key in targets:
-        rec = history.approve(key, path=path)
+        rec = history.approve(key, path=path, reason=getattr(args, "reason", None))
         if rec is None:
             print(f"Nothing recorded for {key} yet — scan it first.", file=sys.stderr)
             return 2

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/src/mcpgawk/drift.py

@@ -464,13 +464,16 @@ class DriftReport:
         return out
 
     def permission_changes(self, key: str) -> list[str]:
-        """What this item can now do that the person never approved: an annotation escalation, or
-        a new parameter that names a destination. The guard REFUSES on these (FOUNDER 2026-10-06,
-        "Block permission growth"); every other schema change waits for sign-off without blocking
-        (FOUNDER 2026-08-15). One rule, read by scan and by the guard projection."""
+        """What this item can now do that the person never approved: an annotation escalation, a
+        new parameter that names a destination, or a new parameter that names code to execute.
+        The guard REFUSES on these (FOUNDER 2026-10-06, "Block permission growth"); every other
+        schema change waits for sign-off without blocking (FOUNDER 2026-08-15). One rule, read by
+        scan and by the guard projection."""
         return (self.escalations(key)
                 + [f"new destination parameter {p}" for p in self.gained_params(key)
-                   if destination_param(p)])
+                   if destination_param(p)]
+                + [f"new execution parameter {p}" for p in self.gained_params(key)
+                   if execution_param(p)])
 
     def of_kind(self, kind: str) -> dict[str, list[str]]:
         """Split the typed `{kind}.{name}` keys back out for rendering."""
@@ -499,6 +502,28 @@ def destination_param(name: str) -> bool:
     return bool({t for t in re.split(r"[^a-z0-9]+", snake) if t} & DESTINATION_TOKENS)
 
 
+#: Name tokens that make a NEW parameter an execution surface: the call can now run a command,
+#: script or query the caller supplies. Borrowed as a pattern from Yashigani's EXEC class
+#: (docs/research-yashigani-2026-10-08.md), minus `query` and `code`, which would fire on every
+#: search and docs tool. Measured 2026-10-08 on all 184 real updates (107 + Nueravi's 77): zero
+#: of the 99 parameters added to existing tools match, so it adds no false refusals.
+EXECUTION_TOKENS = frozenset({
+    "command", "commands", "cmd", "script", "scripts", "shell", "sql", "exec", "eval"})
+_REFERENCE_SUFFIXES = frozenset({"id", "ids", "name", "names", "type", "types", "index"})
+
+
+def execution_param(name: str) -> bool:
+    """True when a parameter's NAME says the call executes something the caller supplies."""
+    if not isinstance(name, str):
+        return False
+    snake = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+    tokens = [t for t in re.split(r"[^a-z0-9]+", snake) if t]
+    # `commandId`, `scriptName`, `sqlType` refer to a command; they do not carry one to run.
+    if tokens and tokens[-1] in _REFERENCE_SUFFIXES:
+        return False
+    return bool(set(tokens) & EXECUTION_TOKENS)
+
+
 def _pin_basis_of(rec: dict[str, Any]) -> int | None:
     """Which rule minted this record's pin. None = cannot tell, which is NOT the same as current.
 
@@ -955,6 +980,11 @@ def render(name: str, r: DriftReport, head: str | None = None) -> str:
         # never ran `approve` that they had (new-developer walk, 2026-09-26).
         head = (f"    ⟳ DRIFT on {name} — changed since first seen"
                 f"{' ' + when if when else ''}; you have not approved this server yet:")
+    elif r.baseline_origin == "unattended":
+        # Approved, but with no person present (an agent session, an agent process, no terminal or
+        # the panel unconfirmed): "since you approved it" would claim a decision nobody made.
+        head = (f"    ⟳ DRIFT on {name} — changed since its baseline, approved"
+                f"{' ' + when if when else ''} without a person present:")
     elif r.baseline_origin == "fleet":
         # First seen, then accepted by `approve --fleet`: an approval, but of the fleet, given
         # after this baseline was recorded — so the date is the sighting's, said as such.

{mcpgawk-0.1.72 → mcpgawk-0.1.73}/src/mcpgawk/history.py

@@ -152,7 +152,7 @@ def approval_blocked_reason() -> str | None:
                 f"past one. Run this yourself in your own terminal.")
     if os.environ.get(APPROVE_OVERRIDE_ENV) == "1":
         return None
-    if not sys.stdin.isatty():
+    if not _stdin_is_tty():
         return ("no interactive terminal. Approving a changed server is a trust decision and needs "
                 "a human present; refusing rather than assuming consent.")
     return None
@@ -170,6 +170,93 @@ def require_human_approval() -> None:
         raise ApprovalBlocked(reason)
 
 
+#: Agents whose children are the agent's own tool calls. MEASURED: `claude` (Claude Code 2.1.289,
+#: 2026-10-05 — `ps` ancestry of a Bash tool call reads zsh → claude → -zsh → login → Terminal). The
+#: rest are those agents' own CLI names, not yet measured. A detached child (`nohup … &` in a
+#: subshell) is reparented to init and escapes this walk — measured the same day — so this is
+#: evidence, never proof.
+AGENT_PROCESS_NAMES = frozenset({"claude", "codex", "gemini", "kimi", "opencode", "goose", "aider",
+                                 "cursor-agent"})
+
+
+def _stdin_is_tty() -> bool:
+    try:
+        return sys.stdin is not None and sys.stdin.isatty()
+    except (ValueError, OSError):
+        return False
+
+
+def _process_ancestry() -> list[str]:
+    """Names of this process's ancestors, nearest first; [] where they cannot be read."""
+    if os.name != "posix":
+        return []
+    import subprocess
+    try:
+        out = subprocess.run(["ps", "-axo", "pid=,ppid=,comm="], capture_output=True, text=True,
+                             timeout=5).stdout
+    except (OSError, subprocess.SubprocessError):
+        return []
+    parent: dict[int, int] = {}
+    name: dict[int, str] = {}
+    for line in out.splitlines():
+        parts = line.split(None, 2)
+        if len(parts) == 3 and parts[0].isdigit() and parts[1].isdigit():
+            parent[int(parts[0])] = int(parts[1])
+            name[int(parts[0])] = os.path.basename(parts[2].strip())
+    chain: list[str] = []
+    pid, seen = os.getppid(), set()
+    while pid > 1 and pid in name and pid not in seen:
+        seen.add(pid)
+        chain.append(name[pid])
+        pid = parent.get(pid, 0)
+    return chain
+
+
+def agent_process() -> str | None:
+    """The first ancestor that is an agent (`AGENT_PROCESS_NAMES`), or None."""
+    for n in _process_ancestry():
+        if n.lstrip("-").lower() in AGENT_PROCESS_NAMES:
+            return n
+    return None
+
+
+def approval_evidence(source: str = "cli") -> dict[str, Any]:
+    """What this process can show about WHO is approving, recorded beside every approval.
+
+    A person is present only with a terminal, no agent-session marker and no agent process above
+    us. A same-user agent can forge or evade every one of these, so this is never proof: it is what
+    lets every surface NAME an approval that came without a person, instead of showing it as "you
+    approved it" (FOUNDER 2026-10-05, "Block + name it"). A panel approval is never a person's on
+    this evidence alone: the panel's process is the person's, the POST may not be.
+    """
+    markers = [m for m in AGENT_ENV_MARKERS if os.environ.get(m)]
+    proc = agent_process()
+    terminal = _stdin_is_tty()
+    return {"source": source, "terminal": terminal, "agent_markers": markers,
+            "agent_process": proc, "hatch": os.environ.get(APPROVE_OVERRIDE_ENV) == "1",
+            "person_present": source != "panel" and terminal and not markers and proc is None}
+
+
+def evidence_words(ev: Any) -> str | None:
+    """"approved without a person present — <why>", or None when a person was present or the
+    approval predates the evidence (unknown is not re-judged). Never names the hatch's variable: an
+    agent reads these surfaces, and the name is the bypass."""
+    if not isinstance(ev, dict) or ev.get("person_present", True) is not False:
+        return None
+    why: list[str] = []
+    if ev.get("agent_process"):
+        why.append(f"an agent ({ev['agent_process']}) was running it")
+    if ev.get("agent_markers"):
+        why.append("an agent session was marked")
+    if ev.get("source") == "panel":
+        why.append("it came from the panel and was not confirmed at a terminal")
+    elif not ev.get("terminal"):
+        why.append("no terminal")
+    if ev.get("hatch"):
+        why.append("an automation setting allowed it")
+    return "approved without a person present — " + "; ".join(why or ["no sign of a person"])
+
+
 def load(path: str | None = None) -> dict[str, Any]:
     return load_checked_hardened(path)[0]
 
@@ -859,8 +946,74 @@ def record(key: str, rec: dict[str, Any], path: str | None = None,
     return base
 
 
+#: Longest `--reason` kept on an approval record. A reason is a sentence, not a document.
+APPROVAL_REASON_MAX = 500
+
+
+def approval_change(prev: Any, latest: Any) -> dict[str, Any]:
+    """What an approval of `latest` accepts, measured against the previous approval `prev`.
+
+    Names, not content: tools added and removed, descriptions rewritten, inputs reshaped,
+    annotations changed, and permission growth by scan's own rule. `{"first_approval": True}` when
+    nothing was approved before; `{"compared": False}` when the two records cannot be compared
+    (different hashing rules), so the record never claims a diff it did not make."""
+    from . import drift
+    tools = latest.get("tools") if isinstance(latest, dict) else None
+    if not isinstance(prev, dict):
+        return {"first_approval": True, "tools": len(tools) if isinstance(tools, dict) else 0}
+    try:
+        report = drift.compare(prev, latest)
+    except Exception:                                   # noqa: BLE001 — a record must still write
+        report = None
+    if report is None or getattr(report, "unreadable", None):
+        return {"compared": False}
+    split = report.of_kind("tool")
+    growth: dict[str, list[str]] = {}
+    for k in dict.fromkeys(list(report.annotation_changed) + list(report.schema_changed)):
+        if isinstance(k, str) and k.startswith("tool."):
+            grown = report.permission_changes(k)
+            if grown:
+                growth[k[len("tool."):]] = grown
+    return {"tools_added": split["added"], "tools_removed": split["removed"],
+            "descriptions_changed": split["changed"],
+            "schemas_changed": [k[5:] for k in report.schema_changed if k.startswith("tool.")],
+            "annotations_changed": [k[5:] for k in report.annotation_changed
+                                    if k.startswith("tool.")],
+            "permission_growth": growth}
+
+
+def change_words(change: Any) -> str | None:
+    """One line for a person: "+1 tool (forward_note), 2 descriptions rewritten", or None."""
+    if not isinstance(change, dict):
+        return None
+    if change.get("first_approval"):
+        n = change.get("tools") or 0
+        return f"first approval, {n} tool{'s' if n != 1 else ''}"
+    if change.get("compared") is False:
+        return "not comparable with the previous approval"
+
+    def _names(xs: list[str]) -> str:
+        return ", ".join(xs[:3]) + (f" and {len(xs) - 3} more" if len(xs) > 3 else "")
+
+    parts: list[str] = []
+    for field, sign in (("tools_added", "+"), ("tools_removed", "−")):
+        xs = list(change.get(field) or [])
+        if xs:
+            parts.append(f"{sign}{len(xs)} tool{'s' if len(xs) != 1 else ''} ({_names(xs)})")
+    for field, words in (("descriptions_changed", "description{} rewritten"),
+                         ("schemas_changed", "input schema{} reshaped")):
+        n = len(change.get(field) or [])
+        if n:
+            parts.append(f"{n} " + words.format("s" if n != 1 else ""))
+    growth = change.get("permission_growth") or {}
+    if growth:
+        parts.append(f"permission growth on {_names(sorted(growth))}")
+    return ", ".join(parts) or "no change to its tools since the previous approval"
+
+
 def approve(key: str, path: str | None = None, *,
-            expect_pin: str | None = None) -> dict[str, Any] | None:
+            expect_pin: str | None = None, source: str = "cli",
+            reason: str | None = None) -> dict[str, Any] | None:
     """Adopt the most recent sighting of `key` as the approved baseline. Returns it.
 
     The explicit acknowledgement ADR-0012 requires. Until this runs, drift keeps reporting — and
@@ -871,6 +1024,7 @@ def approve(key: str, path: str | None = None, *,
     checks" is a property that decays the moment someone adds a caller, and it did.
     """
     require_human_approval()
+    evidence = approval_evidence(source)
     path = path or default_path()
     with locked(path):
         store = load(path)
@@ -884,6 +1038,14 @@ def approve(key: str, path: str | None = None, *,
         if expect_pin is not None and str(latest.get("pin") or "") != str(expect_pin):
             return None
         entry = server_entry(store, key)
+        # WHAT was accepted, against the previous approval, and WHY if the person said (Yashigani
+        # read, candidate 3): "approved by me at 10:02" never answered "approved what?".
+        entry["approved_change"] = approval_change(entry.get("approved"), latest)
+        _why = (reason or "").strip()
+        if _why:
+            entry["approved_reason"] = _why[:APPROVAL_REASON_MAX]
+        else:
+            entry.pop("approved_reason", None)
         entry["approved"] = latest
         entry.pop(AWAITING_APPROVAL, None)
         # PROVENANCE. `cli status` has printed `approved —` since the field it reads was never
@@ -893,6 +1055,7 @@ def approve(key: str, path: str | None = None, *,
         entry["approved_at"] = _now_iso()
         entry["approved_by"] = _operator()
         entry["approved_via"] = "approve"
+        entry["approved_evidence"] = evidence
         admit_to_fleet(store, key)
         save(store, path)
     return latest
@@ -937,10 +1100,23 @@ def baseline_origin(store: dict[str, Any], key: str) -> str | None:
     keeps the scan, protect, the panel and `baseline` from disagreeing (e2e, 2026-10-05)."""
     e = (store.get("servers") or {}).get(key) or {}
     if e.get("approved_at") or e.get("approved_via") == "approve":
-        return "approve"
+        return "unattended" if evidence_words(e.get("approved_evidence")) else "approve"
     if e.get("approved_via") != "first-sighting":
         return None
-    return "fleet" if fleet_covers(store, key) else "first-sighting"
+    if not fleet_covers(store, key):
+        return "first-sighting"
+    return "unattended" if evidence_words((fleet_baseline(store) or {}).get("evidence")) else "fleet"
+
+
+def unattended_reason(store: dict[str, Any], key: str) -> str | None:
+    """Why this server's baseline was approved without a person present, or None. The one sentence
+    every surface prints for an "unattended" origin (`baseline_origin`)."""
+    e = (store.get("servers") or {}).get(key) or {}
+    if e.get("approved_at") or e.get("approved_via") == "approve":
+        return evidence_words(e.get("approved_evidence"))
+    if e.get("approved_via") == "first-sighting" and fleet_covers(store, key):
+        return evidence_words((fleet_baseline(store) or {}).get("evidence"))
+    return None
 
 
 def fleet_covers(store: dict[str, Any], key: str) -> bool:
@@ -1715,13 +1891,15 @@ def approve_fleet(discovered: dict[str, Any],
     """Record `discovered` as the approved fleet, and adopt every held sighting. Returns (number of
     fleet entries, keys adopted). Gated exactly like `approve`: this moves trust."""
     require_human_approval()
+    evidence = approval_evidence()
     path = path or default_path()
     entries = fleet_targets(discovered)
     adopted: list[str] = []
     with locked(path):
         store = load(path)
         now = _now_iso()
-        store[FLEET_KEY] = {"approved_at": now, "approved_by": _operator(), "entries": entries}
+        store[FLEET_KEY] = {"approved_at": now, "approved_by": _operator(), "entries": entries,
+                            "evidence": evidence}
         for key in held(store):
             latest = last(store, key)
             if latest is None:
@@ -1732,6 +1910,7 @@ def approve_fleet(discovered: dict[str, Any],
             entry["approved_at"] = now
             entry["approved_by"] = _operator()
             entry["approved_via"] = "approve"
+            entry["approved_evidence"] = evidence
             adopted.append(key)
         save(store, path)
     return len(entries), adopted