From 1f1189421f022fda4150a81eedb52534c6f57b84 Mon Sep 17 00:00:00 2001
From: hzhang <zhangh20414@gmail.com>
Date: Sat, 23 May 2026 08:39:20 +0100
Subject: [PATCH] feat(prism-facet): add 'always' router + Hangman-Lab pcexec
 convention prompt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 'always' router resolves to the constant key "always" for every
agent — pair with a rule like 'always:always → some-prompt.md' to
inject a prompt fragment unconditionally (no ego/role/position
lookup needed).

Bundle a site-specific prompt 'pcexec-convention.md' that tells every
agent: Hangman-Lab keeps site binaries at ~/.openclaw/bin (hf,
secret-mgr, ego-mgr, fabric-register, pcguard, lock-mgr, tea) — not
symlinked to /usr/local/bin — so they MUST be invoked via the pcexec
tool, not the codex built-in shell. Without this, agents would call
those CLIs directly and get 'command not found' (observed during the
2026-05-23 hf-wakeup runs on prod t2).

Register the binding in rules.json so it loads at gateway startup.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plugin/prompts/pcexec-convention.md | 31 +++++++++++++++++++++++++++++
 plugin/routers/always.ts            | 11 ++++++++++
 plugin/rules.json                   |  3 +++
 3 files changed, 45 insertions(+)
 create mode 100644 plugin/prompts/pcexec-convention.md
 create mode 100644 plugin/routers/always.ts
 create mode 100644 plugin/rules.json

diff --git a/plugin/prompts/pcexec-convention.md b/plugin/prompts/pcexec-convention.md
new file mode 100644
index 0000000..1f66186
--- /dev/null
+++ b/plugin/prompts/pcexec-convention.md
@@ -0,0 +1,31 @@
+# Hangman-Lab Site Convention — Shell Execution
+
+This claw (sim or prod) keeps Hangman-Lab site binaries at `~/.openclaw/bin/`
+and **does not** symlink them into `/usr/local/bin`. Your shell tool's PATH
+does not include them by default, so calling them with the codex built-in
+shell yields `command not found`.
+
+**Rule:** any command that invokes one of these binaries MUST be run through
+the `pcexec` tool, not the codex built-in shell:
+
+- `hf` (HarborForge CLI)
+- `secret-mgr` (per-agent secret store)
+- `ego-mgr` (per-agent identity store; reads `role`, `position`, `default-username`, etc.)
+- `fabric-register` (Fabric account provisioning)
+- `pcguard` (PaddedCell guard)
+- `lock-mgr`
+- `tea`
+
+`pcexec` injects `~/.openclaw/bin` into PATH and also wires the
+`AGENT_ID`, `AGENT_WORKSPACE`, and `AGENT_VERIFY` env vars that
+`secret-mgr` / `ego-mgr` need to authenticate as the calling agent.
+
+## Examples
+
+- ✅ Call the `pcexec` tool with `command: "hf calendar show --json"`
+- ✅ Call the `pcexec` tool with `command: "HFT=$(secret-mgr get-secret --key hf-token); hf task list --token \"$HFT\" --json"` (the whole pipeline goes in one `pcexec` call)
+- ❌ Sending `hf calendar show` to the codex built-in shell → `command not found`
+
+If a workflow's `Procedure` shows a raw shell snippet involving these CLIs,
+pass the **whole snippet** as a single `command:` argument to `pcexec` —
+don't split into multiple non-pcexec calls.
diff --git a/plugin/routers/always.ts b/plugin/routers/always.ts
new file mode 100644
index 0000000..78d7e44
--- /dev/null
+++ b/plugin/routers/always.ts
@@ -0,0 +1,11 @@
+/**
+ * `always` router — resolves to the constant key `"always"` for every
+ * agent. Pair with a rule like `always:always → <some-prompt.md>` to
+ * inject a prompt fragment into every agent's system prompt
+ * unconditionally (no ego / role / position lookup needed).
+ */
+import type { RouterContext } from "../core/router-loader.js";
+
+export function resolve(_ctx: RouterContext): string {
+  return "always";
+}
diff --git a/plugin/rules.json b/plugin/rules.json
new file mode 100644
index 0000000..46bfccb
--- /dev/null
+++ b/plugin/rules.json
@@ -0,0 +1,3 @@
+{
+  "always:always": "/root/.openclaw/plugins/prism-facet/prompts/pcexec-convention.md"
+}