Files
Tony0410 e033a08f17 audit(2026-11-12): the estate's last incident closed itself; a past-0.9.42 hq-push install was refused by the plugin scan (fix parked in PR #2)
- 429 row cbfe43_ed01845310d8 closed resolved 2026-11-12T00:25:36 on the next clean slot; 0 of 137 unclosed
- 11-12: 176 rows / 175 completed / 0 failed / 1 running; 11-11: 172/172/0; deliveries 9/9 and 7/7 delivered
- NEW incidents/2026-11-12-hq-push-upgrade-blocked-by-plugin-scan.md (dangerous verdict, one critical in the
  plugin's own tile skill; --force cannot override; no per-verdict override exists)
- systems/hermes-hq-push.md corrected live (0.9.27 -> 0.9.42, tree mtime 2026-11-08 02:19, config line 13226)
- current-state / scheduled-tasks / index / log updated; skills-index regenerated; freshness 2026-11-13 (0 stale)
2026-11-13 00:41:15 +08:00

152 lines
9.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: hermes-hq-push (Hermes HQ iPhone app plugin)
type: system
status: active
created: 2026-11-04
updated: 2026-11-13
verified_on: 2026-11-13
review_after: 2026-12-13
confidence: medium
tags: [push, notifications, plugins, ios, desktop, device-access]
sources: [live-hermes-plugins-list, live-plugin-manifest, live-config]
---
# hermes-hq-push (Hermes HQ iPhone app plugin)
## What it is
`hermes-hq-push` is a **standalone Hermes plugin** (`kind: standalone`, **v0.9.42**, author *Hermes HQ*)
living at `~/.hermes/plugins/hermes-hq-push/` (tree mtime **2026-11-08 02:19**, reinstalled 0.9.27 → 0.9.42). It is the host-side half
of the **Hermes HQ iPhone app**: Apple push, phone device access, the desktop-app theme, the app's Terminal
page, and Grok Live voice token minting.
Its own manifest states it **replaces `dispatch-push`**, and that *"its registered phones carry over."*
## Verified state (2026-11-13)
| Check | Result |
|---|---|
| `hermes plugins list` | `hermes-hq-push` — **enabled**, `0.9.42`, state `user` |
| `config.yaml` → `plugins.enabled` | line **13226** (block opens line 13210; the number drifts with every catalogue write): `- hermes-hq-push` |
| `~/.hermes/plugins/dispatch-push/` | **absent** — and no `dispatch-push` reference survives in `config.yaml` |
| live tree | `~/.hermes/plugins/hermes-hq-push/` (module files + `dashboard/` subdir + its own test suite) |
| README | none — the manifest `description` is the only prose |
The replacement is therefore **clean**: nothing references the retired plugin, and the new one is explicitly
enabled. Enablement and version are config-verified; individual hook firing was not separately captured.
## Surfaces (grouped from the plugin manifest)
**Push / approvals**
- Finished turns — who replied and what they said.
- Approvals with the command shown, **Approve / Deny from the lock screen**.
- A bot waiting for a password, login, code or answer — the site or the question, **never the value**.
- **Live Lock Screen cards:** every step the bot takes (e.g. *Running npm test…*, the two before it, how
many) is pushed to the card, *sealed so only the phone can read it*; the card says **Done** when the turn
ends.
- Tells the app which scheduled jobs a bot is still working on.
**Device access** (app *Settings › Device Access*) — contacts lookup, location, reminders and events, alarms
and timers, photos, Health, motion, music, and leaving an email or text for Anthony to send. This is what
backs the Conduit-style phone sharing on the Hermes HQ app.
**Desktop app** — adds the **Hermes HQ theme**; opens a shell on the host for the app's Terminal page (the
login shell, as an SSH login would; `plugin-data`'s `terminal.off` disables it); lets a Nous sign-in delete,
archive and rename the chats it created (Hermes refuses them otherwise) and lets the desktop app open chats
the app made (Hermes answers `not_found` otherwise); keeps a bot's **Sessions list fast** on a host that has
run many scheduled jobs; lets the app send into a chat the desktop app has open; page previews; and keeps
the app's performance log on this computer at **`~/.hermes/hq-logs`**.
**Voice** — mints the app's **Grok Live** voice session a short-lived xAI token (subscription sign-in or
`XAI_API_KEY`; the bearer itself never reaches the phone).
**Restart guard** — stops a bot's one-off macOS launchd restart job from looping (those jobs are KeepAlive,
so a one-time restart re-runs forever and locks the app out), and tells a restart script which in-app chats
are mid-reply so a restart can wait.
**Cross-posting** — on request, posts the bot's answer back to the Telegram or Discord chat a conversation
came from.
## Interface
- **Tools:** `device_contacts_search`, `device_request_result`.
- **Hooks:** `pre_approval_request`, `post_approval_response`, `pre_tool_call`, `on_human_input_request`,
`on_human_input_resolved`, `pre_llm_call`, `on_session_end`.
## Configuration
All environment variables are optional. `DISPATCH_*` spellings of the APNs/relay names still work.
| Variable | Purpose |
|---|---|
| `HERMES_HQ_APNS_KEY_PATH`, `HERMES_HQ_APNS_KEY_ID`, `HERMES_HQ_APNS_TEAM_ID` | **Direct APNs mode** — path to the app's `.p8` auth key, its Key ID, and the Apple Developer Team ID that owns the app. *Only the app's developer has these.* |
| `HERMES_HQ_PUSH_RELAY_URL` | Another push relay's HTTPS URL, or `off` to send nothing. **Unset = alerts go through the public Hermes HQ relay, sealed so it cannot read them.** |
| `HERMES_HQ_PUSH_RELAY_KEY` | Only for a private relay that asks for a key. |
No key material is recorded on this page and none appears in the manifest — the relay key is declared
`password: true` and is supplied by environment only.
## Relationship to the other push stacks
- [[systems/push-notifications]] documents the **Cadu/Vory** bridge (`hermes-push`, `vory-push`,
`~/.hermes/push/hermes_push.py`) — a **separate** stack, untouched by this plugin and still `degraded`.
- `dispatch-push`, the previous relay plugin for the same app, is **retired and fully removed** (see the
verification table above).
## 2026-11-07 — reinstalled to v0.9.42, routes picked up by a gateway restart
- The plugin was **reinstalled to `v0.9.42`** in this window (from `v0.9.27`) and the **gateway was
restarted at 11:11:44 → 11:11:55 AWST** so the new tool routes were registered (live process then
`pid 3109529`). A plugin's routes are only registered at gateway start, so a reinstall without a restart
changes nothing on the wire — the restart is the delivery step, not a symptom
([[systems/hermes-agent]]).
- Same night, the plugin tree's mtime moved from **2026-11-03 11:06** (the mtime this page recorded on
2026-11-04) to **2026-11-07 06:42**; `hermes plugins list` on 2026-11-07 reports `hermes-hq-push` **0.9.42**
enabled (`plugin.yaml` agrees). Installed from `mrcharlesiv/hermes-hq-plugins`, upstream **`d26850e7`**,
verified complete at **60/60 files**. Order of events that made the restart necessary:
`hermes-dashboard` started **05:43:04** and `hermes-gateway` **05:37:34** (the 0.22.5 → 0.23.0 update) —
*before* the 06:42 reinstall, so neither running process had the new routes. A verification pass at
10:00:46 confirmed the plugin files were newer than both service starts, and the single restart followed
at 11:11:44 → 11:11:55 (`pid 3109529`).
- No app-side fault was recorded on 2026-11-07. Push delivery, device access and Grok Live minting were not
re-exercised end-to-end by this audit — the version/route claim is the verified part.
## 2026-11-12 — the upgrade past 0.9.42 was refused by the security scan
An attempt to install a later build (`… --enable --force`) never wrote a file: the **pre-install plugin
security scan** returned
> `Blocked: Security scan blocked plugin install: Blocked (dangerous verdict, 1 critical of 39 findings (echo_pipe_exec)). --force does not override a dangerous verdict.`
- The **sole critical** is this plugin's own `skills/dashboard-tile/SKILL.md:41` — the
`echo '<json>' | python3 …` one-liner, flagged as *obfuscation*. The other **38 findings are
low/medium** and would have been installable as `caution`.
- **`--force` cannot help.** It lifts `caution` only; a `dangerous` verdict is an unconditional block
(`tools/plugin_guard.py:406-418`). And **no per-verdict override exists** — the only config key is
`plugins.scan_on_install` (default `true`, currently unset), which switches scanning off for **every**
future install rather than allowing this one. There is no plugin trusted-source list; the
`trust_level`/allowlist machinery lives in `tools/skills_guard.py` (the *skills* path) and is not read
by `plugin_guard.py`.
- **Installed state is unchanged and healthy:** `v0.9.42`, `enabled`, still delivering.
- **The fix is PR #2** on `mrcharlesiv/hermes-hq-plugins` (author `Tony0410`, branch
`fix/tile-skill-heredoc` → `main`, **OPEN / MERGEABLE**, `mergedAt: null`, **+7 / −2 in one file**),
pushed from a fork because this host's `gh` account has **read-only** access to that repo. The
diff rewrites the one-liner as a heredoc. A local clone with the commit lives at
`/home/hermes/workspace/hq-plugins-fix`.
Full record: [[incidents/2026-11-12-hq-push-upgrade-blocked-by-plugin-scan]].
## Open
- **Blocked upgrade (2026-11-12):** past-0.9.42 installs are refused by the security scan until PR #2
merges upstream and the plugin is reinstalled. Workaround is *not* to disable the scan.
- The plugin's own skill files must avoid shell one-liners that pipe into an interpreter (`echo … |
python3`) — that pattern alone trips the scanner's obfuscation rule.
- `~/.hermes/hq-logs` retention is not documented anywhere yet — check its growth before it becomes a disk
item.
- The plugin carries a very large surface under one name; if it misbehaves the manifest `description` is the
only capability index.
- **Operational note:** the plugin's `pre_tool_call` guard rejects any tool call whose arguments contain the
literal text of a launchd one-off-restart command — writing *about* that command into a file is blocked
too. Describe it, don't quote it.