[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M757S502T3Z4ECGK432C1DVC":3,"skill-same:01M757S502T3Z4ECGK432C1DVC":64},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M757S502T3Z4ECGK432C1DVC","pi-coding-agent",null,"Operate the Pi coding agent CLI — install, extensions, Jev.","lukemcqueen\u002Fsteadfaste-fleet","lukemcqueen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F405240?v=4","01M757MHPAGRXTJAT46SKZP98R","Luke McQueen","01M757MHPZ573KP8DT9GB8SBQ7",4,"MIT","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fautonomous-ai-agents\u002Fpi-coding-agent\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nversion: 1.0.0\nname: pi-coding-agent\ndescription: \"Operate the Pi coding agent CLI — install, extensions, Jev.\"\n---\n\n# Pi Coding Agent\n\nThe coding-agent harness the fleet owner wants for steadfaste (replacing hermes).\n`@earendil-works\u002Fpi-coding-agent` — a MANAGED install, not an npm global (see\nInstall below). The reference for pi + Jev\nintegration is `github.com\u002Fdisler\u002Ften-levels-of-jev` (30 tested Jev use cases in\n10 levels; levels 6–10 put Jev inside pi).\n\n## Install — a MANAGED install, NOT an npm global (corrected 2026-10-02)\n\nPi installs itself into its own agent directory and pins each release; there is no\n`npm install -g`. Measured on a live host:\n\n    ~\u002F.pi\u002Fagent\u002Fbin\u002Fpi                        launcher (sh): reads the version, execs the release\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version       the authoritative version string (1.0.0 here)\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Fmanaged-install.json  {kind: pi-managed-install, layout: releases-v1,\n                                               entrypoint: symlink -> \u003Cuser bin dir>\u002Fpi}\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F\u003Cv>\u002Fnode_modules\u002F.bin\u002Fpi    the real executable\n    ~\u002F.local\u002Fshare\u002Fpi-node\u002Fcurrent\u002Fbin        Node.js that PI installs and manages\n\nConsequences that cost time and must not be re-learned:\n\n- **`command -v pi` is NOT a reliable probe.** The entrypoint is a symlink into the\n  user's bin dir (a linuxbrew `bin\u002F` on one measured host). When that\n  dir is not on PATH, `pi` looks *missing* to every caller while being installed and\n  working. Invoke the launcher directly — `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` — or read\n  `~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version` without executing anything.\n- **Pi's Node is deliberately NOT on shell profiles.** The launcher puts\n  `~\u002F.local\u002Fshare\u002Fpi-node\u002Fcurrent\u002Fbin` on PATH for itself and its children, so `node`\n  and `npm` resolve correctly inside pi and nowhere else. Do not \"fix\" that by\n  exporting it globally.\n- **Extension type defs live in the release, not an npm root:**\n  `V=$(cat ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version)` then\n  `$HOME\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\u002Fdist\u002F...`\n- **Never infer the version from a doc or a package name** — read `current-version`\n  (or the launcher's `--version`). A harness registry claiming a shipped version can\n  be stale on any given host — MEASURE it: one host read 1.2.0 (with both 1.1.0 and\n  1.2.0 present under `releases\u002F`) while the registry's own `why:` prose still\n  described 1.0.0. Read the type defs from the release you just measured, never from\n  the prose about it.\n- Verify: `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi --version` and `--help` (read\u002Fbash\u002Fedit\u002Fwrite tools, plus\n  the `pi install\u002Fremove\u002Flist\u002Fconfig\u002Fauth` extension commands).\n\n## Core\n- Built-in tools: read, bash, edit, write.\n- `pi install \u003Csource>` \u002F `pi remove \u003Csource>` manage extension sources;\n  `pi list` shows installed extensions.\n- An extension is loaded as `pi -e extensions\u002F\u003Cname>.ts --tools read,bash,edit,write[,\u003Cjev tools>]`\n  — the `--tools` allowlist is explicit; only listed tools are available.\n\n## stdout shape non-interactive — MEASURED, do not guess\n\nA non-interactive pi turn writes EXACTLY the assistant's final answer to stdout and\nnothing else — verified with a plain prompt and with a prompt that used the bash tool:\n\n    $ ~\u002F.pi\u002Fagent\u002Fbin\u002Fpi --model \u003Cm> \"List three fruits, one per line, numbered 1. 2. 3.\"\n     1. Apple\n     2. Banana\n     3. Cherry\n\n- **Chatter goes to stderr and pi's own log, never to stdout.** So a wrapper that uses\n  stdout verbatim is CORRECT, and one that takes \"the last line\" only TRUNCATES every\n  multi-line answer down to its final line — a reply that arrives but is not complete.\n  Verify stdout and stderr separately before choosing any output-shaping mode.\n- **A fresh `--session-id` prints a benign stderr warning** — `Warning: No project session\n  found with id '\u003Cid>'; creating a new session with that id.` — and still exits 0. That is\n  how a per-chat session gets created, not a failure to report.\n- **Call the launcher by absolute path from a service or wrapper.** `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` is\n  the launcher; the `pi` symlink in a user bin dir is not on a service PATH. Wrappers pass\n  an ARGV LIST rather than a shell line, so nothing expands `~`\u002F`$HOME` — a relative or\n  guessed path becomes a silent per-message no-op. Pin the session identity too (e.g. a\n  `FLEET_SESSION_KEY`): a harness started outside a git repo cannot derive repo\u002Fbranch and\n  every chat otherwise collapses onto ONE session.\n\n## Driving pi from another process — control calls go over RPC, never a prompt\n\nA wrapper that only sends prompts is missing half the interface, and the missing half\nfails in ways that read as pi being broken (working adapter to copy:\n`ops\u002Fscripts\u002Ffleet_gateway\u002Fpi_control.py` in steadfaste-fleet).\n\n- **A built-in slash command sent as a prompt is a NO-OP.** `\u002Fcompact`, `\u002Fmodel`,\n  `\u002Fnew`, `\u002Frestart`, `\u002Fsettings` are handled only in the interactive\u002FRPC surfaces; as a\n  prompt they become conversation (a forwarded `\u002Fnew` is answered as prose while every\n  bit of context stays). Session and state operations go over **RPC mode**:\n  `pi --mode rpc` takes one JSON record per line on stdin (`{\"type\":\"get_state\"}`,\n  `{\"type\":\"compact\"}`, `{\"type\":\"set_model\", …}`) and answers with a `response`\n  record on stdout — correlate by the `id` you sent, never by response order.\n- **Pass `--no-mcp` for a control call.** pi connects its MCP servers at RPC startup,\n  and with them enabled the control call sat ALIVE and SILENT (no stdout, no stderr)\n  for the whole deadline on ~40% of runs; the same call answered 8\u002F8 in ~1.2 s with\n  `--no-mcp`. A control call uses no MCP tool, so those servers are pure risk there.\n- **Watch the process EXIT as well as EOF.** EOF is not the only end of an answer:\n  pi's MCP children inherit its stdio, so a lingering grandchild holds the write end of\n  the pipe open — no data, no EOF — and a reader waiting only for EOF blocks for its\n  full deadline. Start pi in its own process group (`start_new_session=True`) and kill\n  the GROUP on timeout, so a wedged control call does not also leak children.\n- **`compact` never answers for a session whose transcript does not exist yet**\n  (45 s+, repeated), while `get_state` on the same id answers in ~1.2 s and creates it.\n  Ask for the state first and answer \"no conversation yet\" — a chat that has just\n  started a fresh session is exactly this case, and it is the common one.\n- **Give a check three outcomes, not two**: `0` ok · `1` a NEGATIVE answer · `3` could\n  not verify. `--offline --list-models \u003Cpattern>` prints `No models matching \"x\"` and\n  still **exits 0**, so a verdict read off the exit code is wrong in both directions —\n  decide from the OUTPUT, and make \"pi cannot be run at all\" its own outcome rather\n  than a failed check. The same split lets a caller refuse a bad model name instead of\n  breaking every later turn with it.\n\n## Extension API (the Jev-hook surface)\n\n**Read the installed type defs before writing a hook — never infer the signature.**\n```bash\nV=$(cat ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version)\nP=\"$HOME\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\"\nsed -n '1,60p' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts   # + grep the event interfaces\ngrep -n -A20 'registerTool' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts        # the tool registration contract\ngrep -n -A8  'interface ToolDefinition' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts\n# AgentToolResult is NOT in this package — it comes from the agent core:\ngrep -rn -A12 'interface AgentToolResult' \"$P\"\u002F..\u002Fpi-agent-core\u002Fdist\u002Ftypes.d.ts\n```\n\nRead `ToolDefinition` FIRST. It is the contract the extension must satisfy, and a\ndoc or an older example that disagrees with it is what breaks the harness silently.\n\n- **Hooks** — `pi.on(\"tool_call\" | \"tool_result\" | \"turn_end\" | \"before_agent_start\" | \"session_before_compact\", fn)`. A `tool_call` hook can `return { block: true, reason }` to stop a tool call before it runs; the agent sees only the reason + a notice that the block is final.\n- **The handler's FIRST parameter is the EVENT, not a ctx**: `ExtensionHandler\u003CE> = (event: E, ctx: ExtensionContext) => R`. Reading `ctx.\u003Cthing>` off that first parameter yields `undefined`.\n- **Injection is the RETURN VALUE.** `before_agent_start` returns `BeforeAgentStartEventResult` (`{ message?, systemPrompt? }`); there is **no `ctx.addSystemPrompt()`**. To add context, return an augmented `systemPrompt` (or a `message`).\n- **Event payloads carry the data**: `turn_end` → `{ turnIndex, message, toolResults, entries, outcome }`; `before_agent_start` → `{ prompt, images, systemPrompt, systemPromptOptions }`. Derive what you need from the event.\n- **Tools** — `pi.registerTool({ name, label, description, parameters, execute })`.\n  `execute(toolCallId, params, signal?, onUpdate?)` returns an `AgentToolResult`:\n  `{ content: [{ type: \"text\", text }], details }`. **`run` is the pi 0.87.1 shape and\n  is silently ignored on 1.0.0** — every call then fails with\n  `definition.execute is not a function`, which an agent reads as \"memory is broken\"\n  when the store is fine and the tool WIRING is not. `parameters` must be an object\n  schema (`{ type: \"object\", properties, required }`); a bare param→schema map\n  (`{peer:{type:\"string\"}}`) is not validatable, so a correct `execute` still fails.\n  Build the schema AND the argument extraction from ONE properties map so the two\n  cannot drift apart. Tool descriptions carry the question schema.\n- **Verify a hook fires AND does its job** — a stderr marker in the handler proves the hook ran, not that the effect landed. Assert the effect (did the injected text appear? did the row have content?).\n- **Compaction** — `.pi\u002Fsettings.json` sets `compaction.keepRecentTokens` low so compaction has material; `ctx.compact()` wraps pi's compaction; `ctx.getContextUsage()` feeds the numbers.\n\nExact type shapes, the probe commands, and the executable-guard recipe:\n`references\u002Fextension-tool-api.md`.\n- **Side channel** — report every decision on stderr as `JEV_EVENT` lines (and as session entries) so a run is auditable line-by-line (tool call, hook decision, Jev call, model, cost, context).\n\n## Fleet context (memory + session)\n\n**Pi >= 0.99 \u002F 1.0 has an MCP client** (pi 1.0.0, reproduced: `pi mcp list` reports\n`fleet-context: connected, N tools`): it reads\n`mcpServers` from `~\u002F.pi\u002Fagent\u002Fmcp.json` (user scope) and `.pi\u002Fmcp.json` (trusted\nprojects only), the same shape as Claude Code. Governance is therefore an MCP\nregistration — never hand-write a lock:\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-mcp.sh   # loop-governance, tasks, executor, agent-bus, fleet-context\npi mcp list                                                 # expect 5 servers, state \"connected\"\n```\n\n**Verify a host VERSION-AWARE — never by assuming the route.**\n`bash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh` reports PASS\u002FFAIL\nper layer (MCP servers, skills, extension, governance gate, `agent.env`),\nreads the installed version from the Pi install itself, and checks the REGISTERED\nskills path and its count instead of a hardcoded list. Auditing\nwith the MCP checklist on a Pi that has no MCP client reports FAIL for something\nthat route cannot deliver — the failure is in the checklist, not the host. A server\nmissing from `mcp.json` on a non-orchestrator host is usually a DEPLOY-SCOPE bug\n(a server registered `register_orch` ships only to orchestrators), not a broken\ninstaller: `install-pi-mcp.sh` warns and registers the rest, so 3-of-4 looks normal.\n\n### The SKILLS half — the adapter must be RUN, not merely deployed\n\nPi advertises each skill's NAME + DESCRIPTION at startup and loads the body on demand.\n\n**Exposure is ALL skills, from the fleet-owned published tree — NOT a curated subset.**\nThe manifest no longer governs what a coding agent can read; it stays the record of the\nritual skills Hermes must load before a write. Do not \"restore\" a curated set from\n`skills.yaml#always` — a subset here is exactly what was removed, and the operator asked for\nevery harness to see every skill.\n\n**How Pi enumerates — read from its own loader (`dist\u002Fcore\u002Fskills.js`), never assumed.\nRe-read it when the version moves:**\n\n**Resolve the loader from the INSTALLED release, never a hardcoded version path.** Pi\nupdates itself — a `current-version` observed moving 1.3.0 → 1.4.0 mid-session — so a\nprobe that imports `releases\u002F\u003Cold>\u002F…\u002Fdist\u002Fcore\u002Fskills.js` silently measures the OLD\nloader and reports rules that no longer apply. Read\n`~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version` and import\n`releases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\u002Fdist\u002Fcore\u002Fskills.js`. Before\nblaming a version move for changed behaviour, `diff` the two releases' `skills.js`:\nbyte-identical files mean the enumeration rules did not move and the difference is\nsomewhere else.\n\n**Reading the loader tells you the RULES; running it tells you what an agent actually\ngets.** `scripts\u002Fpi-skills-diagnostics.mjs` imports `loadSkills` from the installed\nrelease and prints, for a tree you name: the skill count, every diagnostic grouped by\nmessage, and each name collision with its winner and loser. Point it at\n`~\u002F.agents\u002Fskills` to reproduce a host's report verbatim (`node \u003Cskill>\u002Fscripts\u002Fpi-skills-diagnostics.mjs`),\nor at an extracted older revision to prove a fix changed the outcome — same tool, two\ntrees. It exits 1 when diagnostics exist, so it is usable as a gate.\n\nDiagnostics are WARNINGS, not refusals: a refused skill shows up as `description is\nrequired` (or a YAML parse message) and is simply absent from the loaded set, so count\nthe loaded skills too — a tree whose file count dropped is how a silent refusal\nbecomes visible.\n\n- **It FOLLOWS symlinks.** A symlinked ROOT is read, and a symlinked skill directory is\n  recursed into (`entry.isSymbolicLink()` → `statSync()` → recurse into it). Pointing `skills`\n  at a symlinked published tree works; a per-skill link farm is unnecessary.\n- **A directory containing `SKILL.md` IS one skill and recursion STOPS there.** Never put a\n  `SKILL.md` at the root of a tree you want enumerated — the rest of the tree becomes invisible.\n- **It honours `.gitignore` \u002F `.ignore` \u002F `.fdignore` AT THE SKILLS ROOT**\n  (`ig.ignores(relPath)`). A stray ignore file silently hides skills while the registration\n  looks perfect, which is why a `--check` must assert the COUNT the agent can see, never merely\n  that the path is written into `settings.json`.\n- **Direct `*.md` children load ONLY at the ROOT.** `includeRootFiles` is true only for the\n  top-level call, so a `DESCRIPTION.md` sitting beside a category's skill directories is NOT a\n  skill — a false lead when chasing a name collision. Only a `*.md` directly in the registered\n  tree is read as a skill.\n- **Dot-entries are SKIPPED** (`entry.name.startsWith(\".\")`), so a `.archive\u002F` of retired\n  skills inside the tree is never enumerated and a `SKILL.md` sitting there is NOT the\n  collision it looks like. Before \"cleaning up\" a dot-directory to silence a loader\n  diagnostic, check whether the loader can see it at all — for Pi it cannot.\n- **A `description` is REQUIRED, or the file is not a skill at all.** `loadSkillFromFile`\n  returns `skill: null` when the description is absent or blank, so the name never enters the\n  index and the body is unreachable — the file is REFUSED, not merely unindexed. This is why\n  a deprecated redirect stub with no description is dead weight: its \"load X instead\" text\n  reaches nobody. And `name` falls back to the PARENT DIRECTORY name when frontmatter omits\n  it, which is how a directory-derived name silently collides with a declared one.\n- **Symlink visibility is PER-READER — never generalise it from one probe.** Measured on a single\n  tree: a symlinked ROOT is visible to `pathlib.rglob`\u002F`os.walk` but INVISIBLE to plain `find`\n  (no `-L`), which reports zero; a per-skill symlink FARM is invisible to plain `rglob`\u002F`os.walk`\n  (only `followlinks=True` sees it). Pi happens to follow both, so its loader is the authority for\n  Pi — read it, and assert the COUNT the agent can see rather than trusting a mode that worked\n  for a different reader.\n- The cross-client standard path is `~\u002F.agents\u002Fskills`, read natively by Codex, Cursor,\n  Copilot CLI, OpenCode and Antigravity. A harness that reads only a private path\n  (`~\u002F.pi\u002Fagent\u002Fsettings.json`, `~\u002F.claude\u002Fskills`) needs a pointer to it.\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh           # wire it\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh --check   # rc 0 ONLY if Pi can see EVERY skill\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh             # per-layer audit\n```\n\nIt writes `~\u002F.pi\u002Fagent\u002Fsettings.json` — `\"extensions\": [\u003Cfleet-context.ts>, \u003Cfleet-governance.ts>]`\nand `\"skills\": [\"~\u002F.agents\u002Fskills\"]` — and RETIRES a pre-existing `~\u002F.pi\u002Fagent\u002Fcortex-skills`\nlink farm when one is found: a stale farm keeps Pi loading a curated subset beside the whole\ntree. Idempotent, and it preserves the user's other keys. It no longer reads `skills.yaml` at\nall — the manifest is fleet-owned at the REPO ROOT (`skills.yaml`, synced to\n`~\u002F.steadfaste-fleet\u002Fskills.yaml` by `fleet-update.sh`) and is the record of Hermes's ritual set,\nnot the source of a coding agent's exposure.\n\n**Drive it with `fleet pi` instead of remembering script names** (a thin driver over the same\nscripts — repo-then-deployed resolution, the owner's rc passed through unchanged):\n\n```bash\nfleet pi install   # user scope: MCP servers + both extensions + the published skills tree\nfleet pi check     # installer --check (registration AND visible count) + the per-layer audit\nfleet pi skills    # what Pi is pointed at, then the delegated visibility verdict\n```\n\n`fleet harness install pi --dir \u003Cproject>` is the PROJECT-scope command; `fleet pi` is the\nHOST-scope one (every Pi project on the machine).\n\n- **Registering is not executing.** A deploy that COPIES an installer into\n  `~\u002F.steadfaste-fleet\u002Fscripts\u002F` has wired nothing, so a host with Pi installed can sit unwired with\n  no signal at all. Gate the run on PRESENCE (`~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` or the `~\u002F.pi\u002Fagent` dir), run\n  BOTH halves (`install-pi-mcp.sh`, `install-pi-integration.sh`), and report the outcome: a host\n  without Pi is not a fault; a host with Pi that comes out of a deploy unwired is. The doctor's\n  `Pi integration` line is the drift guard that keeps it from going quiet again.\n- **Point it at the PUBLISHED tree; never hand-build a bridge.** A bespoke loader (a `\u002Ftmp`\n  builder script, a JSON index, a shell script that fixes up links) has no owner: not deployed,\n  not verified, gone with the machine. The supported route is the published tree\n  (`~\u002F.agents\u002Fskills`, produced by `ops\u002Fscripts\u002Fmanage\u002Fpublish-agent-skills.py` from the\n  fleet-owned defaults) registered once at user scope. Wire the WHOLE library deliberately,\n  and expect its cost at startup: every installed skill's name + description is preloaded, so\n  the size of that tree IS the session's context cost.\n- **The skills half needs PyYAML and must not pick its interpreter by PATH.** `command -v python3`\n  is the interpreter most likely to LACK it, so the installer reports `PyYAML required` and skips\n  the skills half on a host that has everything — resolve through\n  `ops\u002Fscripts\u002Flib\u002Fpython-with-module.sh --print yaml` first and keep a bare PATH pick as the last\n  resort only.\n\nThe **memory\u002Fsession TOOLS** also come from that MCP server — the SAME\n`fleet-context-mcp.py` Claude Code and Codex use, so the schemas are DERIVED\nfrom the store contract and there is no per-harness tool list left to drift.\nThe extension keeps ONLY the lifecycle triggers, which MCP cannot provide:\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-mcp.sh   # + fleet-context\ncp ~\u002Fsteadfaste-fleet\u002Fops\u002Finstall\u002Fharnesses\u002Fpi\u002Fextensions\u002Ffleet-context.ts extensions\u002F\npi -e extensions\u002Ffleet-context.ts --tools read,bash,edit,write\n```\n\nAn older Pi (\u003C= 0.87, no MCP client) reaches the same governance through the\n`loop-gov` CLI instead.\n\nThe extension registers **NO tools** and wires only the lifecycle:\n\n- `before_agent_start` → restore + inject the checkpoint (a fresh session resumes)\n  AND inject any standing rule you want in EVERY session (see \"Standing rules are\n  INJECTED\" below); cover BOTH branches — fresh and resume-with-no-snapshot — or a\n  restored session silently misses the rule.\n- **`turn_end` → write a checkpoint** — the harness owns WHEN, never the model\n- `session_before_compact` → checkpoint before continuity is lost\n- **`tool_result` → record the tool event** for tools a gate asks about. The git hook\n  is GLOBAL, so a Pi commit is gated by the same reflexion gate as a Hermes one, and\n  that gate reads HC's store — not the harness's own DB. With no `tool_result` hook a\n  Pi session has no recorded evidence and **every commit is refused** no matter how\n  well the agent behaved.\n\n### Standing rules are INJECTED, not loaded — the third binding surface\n\nPi's standing context = skill NAMES+descriptions + what the harness injects; a rule\ninside a skill body binds only if the agent happens to load it, and SOUL\u002FMEMORY\u002FUSER.md\nare never read by Pi. Three surfaces reach EVERY Pi session, cheapest-effective first:\n\n1. **`before_agent_start` systemPrompt injection** (fleet-context extension) — the\n   ONLY surface that is truly always-on; it is PAID as context on every turn, so keep\n   it to a compact checklist (~7 lines; the pre-ship checklist is the exemplar:\n   right-first-time, survey-before-build, test-edge-cases, evidence-before-done,\n   doctor-clean, plan-review-first, escalate-review-first). Inject in BOTH branches —\n   fresh AND resume-with-no-snapshot: the verifier sets `FLEET_STUB_EMPTY_RESTORE=1`\n   to force the no-snapshot branch and asserts the checklist appears in each output,\n   or a restore silently misses the rule.\n2. **AGENTS.md \u002F CLAUDE.md** — zero persistent token cost; the place for durable prose.\n3. **The commit-time ritual gate** — a discipline listed in the ritual loop\n   (`reflexion-check survey-before-action prove-before-create agent-contract`) is\n   REFUSED-until-loaded; the only surface with teeth.\n\nBehaviour rules for the agent: insurance at (1), durable prose at (2), the hard\nrule at (3) — never only in a skill body it may never load.\n\n### The WRITE GATE — a SECOND extension, because pi's tools are not Hermes' tools\n\n`extensions\u002Ffleet-governance.ts` (added 2026-10-14, titus). Its `tool_call` handler\nblocks a write-capable NATIVE tool call when no governance lock covers the session's\nrepo. Load it with the harness: `bash install-pi-integration.sh` registers both files.\n\n**Why the existing layers did not cover this — verify before believing either way.**\n\n- The Hermes enforcer plugin (`~\u002F.hermes\u002Fplugins\u002Fgovernance-enforcer\u002F`) is a *Hermes\n  plugin*. It runs in the Hermes agent loop, so pi's native `read`\u002F`bash`\u002F`edit`\u002F`write`\n  never cross it. Registering loop-governance over MCP gives pi the *ritual*, not a\n  gate: an MCP server is a tool surface and cannot see the host's own tools.\n- The commit-time hook DOES carry a lock check (`pre-commit-score`, \"Level 3\"), so a claim that it has none is wrong — but its refusal is scoped\n  `IS_FLEET_REPO && !LOCK_FOUND`, i.e. `~\u002Fsteadfaste-fleet` only, deliberately, so manual\n  human commits in client repos are not blocked. The RITUAL gate is NOT so scoped:\n  the reflexion\u002Fsurvey loop demands the ritual skills in EVERY repo since 2026-10-29,\n  skipping only no-session (human) commits — so a Pi session IS disciplined in its\n  project repos, by a gate placed where the agent actually works.\n\n**It adds no semantics.** The verdict comes from the shared implementation —\n`loop-gov.py check_repo_lock '{\"repo_path\":\"\u003Crepo>\"}'`, which is `loop-gov-mcp.py`'s\nown `_check_repo_lock` + `_live_locks` (staleness rule included). rc 0 = covered,\n1 = refusal, 3 = unreachable. Never re-implement \"does a lock cover this repo\" in a\nharness: the git hook already carries one copy and two copies drift.\n\n- **Classify bash by COMMAND, never by shell syntax.** A metachar rule (`;` `|` `>` …)\n  is a bypass: `cp`, `mv`, `rm`, `tee`, `dd`, `mkdir`, `touch` contain none of them.\n  The gate uses a read-only ALLOWLIST with deny-by-default, so anything not on it —\n  needs a lock. Investigation tools (docker ps\u002Flogs\u002Finspect\u002Fstats, journalctl,\n  ss\u002Fnetstat, curl GET, systemctl status, pip\u002Fnpm list) ARE on it — the gate\n  protects against CHANGES, not against investigation. Read-only COMPOUNDS\n  (`ls | grep foo`, `docker logs c | tail -20`) are lock-free too: every\n  `|`\u002F`&&`\u002F`;` segment must independently match (the enforcer's model). A\n  redirect, a substitution, a second write-class segment, or a mutating flag\n  inside a read primitive (find -exec, sort -o, date -s, journalctl --vacuum-*,\n  docker run\u002Fexec, systemctl start, curl -d\u002F-o) makes the whole thing a write.\n- **Fail CLOSED on every cannot-verify path** (CLI missing, governance unreachable, no\n  repo resolvable), with the cost stated in the block message and NO agent-side\n  override. A gate that reads \"could not check\" as \"carry on\" fails open exactly when\n  the host is broken.\n- **Resolve the governed repo from the CALL's own arguments first**, then\n  `FLEET_SESSION_REPO`, then the process cwd. A `tool_call` hook is handed the tool input\n  and no session cwd, so path-args-only resolution leaves every path-less command\n  (`git commit -m …`, a bare compound) with no repo — and a session launched outside the\n  checkout can never name the tree its call touches, including the `cd \u003Crepo> && git\n  rev-parse --show-toplevel` an agent would use to PROVE it. The measured failure is a\n  total deadlock: every write refused with \"cannot determine the repo\" while the agent was\n  standing in the repo, and the one command that would have settled it was itself the\n  blocked write. Take the repo from file-shaped inputs (`path`, `file_path`, `filePath`,\n  `filename`, `target`) and from absolute paths named inside a shell command, trying the\n  path and then its directory — a FILE is not a git cwd.\n- **Find the repo root by WALKING UP for a `.git` entry; never require the `git` binary to\n  find it.** A macOS launcher (app, service, GUI) commonly runs with a PATH that lacks\n  `\u002Fopt\u002Fhomebrew\u002Fbin`, so `execFileSync(\"git\", …)` raises ENOENT while git works fine in\n  the operator's own shell — and the gate then reports \"not in a git repo\" about a folder\n  that is one. Walk with `fs.statSync(path.join(dir, \".git\"))` (a `.git` FILE counts:\n  worktree or submodule) and hand git only what a walk cannot see (bare repo, `GIT_DIR`).\n  Finding where a repo STARTS needs no git; only reading it does.\n- **A fail-closed refusal must CARRY the reason it could not verify.** Keep stderr, the\n  exit code and the path tried, and print them in the block. That is the difference\n  between \"git is not on this process's PATH (ENOENT)\" and \"this folder is not a repo\" —\n  without it the operator is told the wrong thing and cannot fix it, and the next\n  diagnostic re-derives what the code already knew.\n- **Prove it by EXECUTING the extension**: `node ops\u002Finstall\u002Fharnesses\u002Fpi\u002Fverify-governance-extension.mjs`\n  loads it through pi's own jiti loader, hands it a stub `pi`, fires synthetic\n  `tool_call` events and asserts both directions — plus the no-metacharacter write\n  commands above. `tests\u002Ftest_pi_governance_gate.py` additionally requires the guard to\n  FAIL when pointed at a gate that blocks nothing (`PI_GOV_EXT=\u003Cbroken>`), and at the\n  REAL extension with only the named-lock rendering removed; a guard that\n  has never failed is a happy path.\n- **A refusal names the live locks it did NOT match.** `check_repo_lock` returns\n  `other_locks` (task_id, agent, session_id, repo_path, status, heartbeat_at) beside\n  `live_lock_count`, and the block message renders the first three as\n  \"Live locks on this host — none covers this repo:\" with a `… and N more` remainder.\n  A lock that records no `repo_path` is named as covering nothing rather than dropped.\n  The harness only RENDERS what the predicate reported — it must never parse lock\n  files to work out whose lock is blocking.\n- **A stub proves the HANDLER; only a real session proves the WIRING.** The guard above\n  hands the extension a synthetic `pi`, so it passes green even on a gate pi never\n  calls — those are two separate claims, and the second is the one that matters. Run one\n  real turn in a scratch project repo and read the gate's OWN log\n  (`~\u002F.steadfaste-fleet\u002Flogs\u002Fpi-governance.log`, one `GOV_VERDICT` line per decision) rather\n  than the agent's prose summary. Expect `refused` on the first write and then `allowed`,\n  because the block names `begin_change` as the remedy and the agent simply complies —\n  self-remediation is the gate working, not the gate failing. A gate that only ever\n  blocked would be a deadlock. Watch the log, not the file listing: the turn's stdout is\n  the agent's SELF-REPORT, and the write it claims may have been refused and retried.\n\n- **A Pi session's governance lock is tagged from the SESSION's repo, never from the\n  host's `~\u002Fsteadfaste-fleet` (2026-10-09, titus).** Pi injects no repo identity, so\n  `_derive_slug()` resolves it as `FLEET_SESSION_REPO`, else the MCP child's working\n  directory — the project you launched Pi in. Before that fix a Pi session working in a\n  project repo was locked as `steadfaste-fleet`, and the close gate refused forever with\n  \"the lock's repo cannot contain this session's work\": the lock stays HELD on a refusal,\n  and its prescribed remedy (an enforcer injection) does not exist on Pi, so only the\n  operator could delete `~\u002F.steadfaste-fleet\u002Fstate\u002F.governance-sess_*.json`. Launch Pi from\n  the project (`cd repo && pi`), or pin `FLEET_SESSION_REPO` in the MCP `env` block when\n  the cwd is not the project. It needs a DEPLOY, not a pull: the harness runs the\n  deployed copy (`~\u002F.steadfaste-fleet\u002Ftools\u002Floop-governance\u002Floop-gov-mcp.py`). Verify with\n  `python3 tests\u002Frun_non_hermes_lock_release_repro.py` (pre-fix \u002F working-tree \u002F DEPLOYED\n  in one run; it exits non-zero unless the lock is released). Full write-up:\n  `docs\u002Ftroubleshooting.md`.\n\n**Do NOT register the shared tools in the extension.** They used to live there as a\nhand-written `tool()` list with hand-written parameter maps — a SECOND definition of\ntools that already existed in the contract, and the copy that broke silently when pi\nmoved 0.87.1 → 1.0.0. Two definitions of one capability means the runtime resolves one\nand the other becomes a phantom. Tools stay in the shared MCP server; only the\ntriggers stay in the extension.\n\n### The COMMIT-time ritual gate — where DISCIPLINE binds (all repos)\n\nBeyond the write lock, a Pi commit is judged by the same pre-commit ritual gate as\nHermes — in EVERY repo. `reflexion-check.py --skill \u003Cname>` is generic, and the\ngate's loop demands `task-orient execute-right\nverify-and-ship` for a governed session. The session split is what makes \"all repos\"\nsafe: a Pi session holds a begin_change lock, so it is JUDGED anywhere; a human\ncommit has no session and is skipped (`--skip-no-session`). A discipline meant to\nchange Pi's behaviour belongs HERE — a skill in the loop that the gate refuses until\nthe agent loads (loading = reading the SKILL.md, recorded by the `tool_result`\nhook) — never only in a skill body it may never load.\n\n**Consequence for guidance placement:** the only files a non-Hermes agent always has\nin context are AGENTS.md (and CLAUDE.md for Claude). SOUL.md \u002F MEMORY.md \u002F USER.md\nare never read by Pi, and skills are name-only until the agent chooses to load one —\nso a rule living only in a SOUL trait or a skill's body reaches NO coding agent. Put\nbehaviour rules for Pi in AGENTS.md\u002FCLAUDE.md (a short \"Core Operating Rules\" block is\nthe pattern), and make them bind by putting the discipline into the ritual-gate loop.\n\nHarness index: `ops\u002Finstall\u002Fharnesses\u002FINDEX.md` · Adding another harness:\n`registry.yaml` + `generate-harnesses.py` · Runbook:\n`docs\u002Frunbooks\u002Fcontext-integration.md`.\n\n## Cortex-gateway — answer a Telegram bot with pi (the `command` backend)\n\nThe standalone `fleet-gateway` (a systemd\u002Flaunchd unit, decoupled from\n`hermes-gateway.service`) serves a Telegram bot with pi as a `kind: command`\nbackend. `pi` itself needs no new adapter — it is DECLARED, not coded:\n\n- **Config\u002Fexample:** `ops\u002Fscripts\u002Fgateway-pi.example.yaml` → copy to\n  `~\u002F.steadfaste-fleet\u002Fgateway.yaml` (OUTSIDE the repo). `command` is an ARGV LIST,\n  so use the ABSOLUTE pi launcher path (`\u002Fhome\u002F\u003Cuser>\u002F.local\u002Fbin\u002Fpi` etc.) — a\n  relative or `~`-containing path is a per-message silent no-op. Use\n  `output: raw` (pi's stdout is exactly the answer), `session: per_chat` with\n  `FLEET_SESSION_KEY={session_id}`, and a `timeout_s` that covers a real coding\n  turn (300s+), not a chat reply. Slash commands (`\u002Fcompact,` `\u002Fmodel` …) are the\n  GATEWAY's to handle via pi RPC (`fleet_gateway\u002Fpi_control.py`), never forwarded\n  as prompts.\n- **A second Telegram bot must use a DISTINCT token var — never\n  `TELEGRAM_BOT_TOKEN`.** `fleet-gateway.service` runs\n  `guard_distinct_token.py` as `ExecStartPre`, which REFUSES to start when\n  `gateway.yaml`'s `bots[].token_ref` is the live bot's var\u002Fname — two pollers on\n  one bot token get a Telegram **409 Conflict** and the casualty is the LIVE\n  channel. Give the pi bot its own env token (e.g. `MOSESPI_BOT_TOKEN`=\n  `PI_BOT_TOKEN`) and reference that; `guard_distinct_token.py` confirms it is\n  distinct (prints the value's hash, never the value) before the unit starts.\n- **The sender allowlist IS the security perimeter** — a bot answered by pi can\n  execute bash, so set `TELEGRAM_ALLOWED_USERS` (and `TELEGRAM_HOME_CHANNEL`) to\n  the operator's chat id ONLY; likewise `GATEWAY_SECRET` (HMAC signing key) is\n  mandatory — the daemon refuses to start without it, because an empty key makes\n  every bus signature forgeable. The bot+config are assembled per host: env vars\n  into the canonical fleet env (`~\u002Fsteadfaste-fleet\u002F.env`), `gateway.yaml` from the\n  example, then `enable --now` the unit. Full reference: `docs\u002Ftemplates\u002F\n  fleet-gateway.service` + `docs\u002Fdesign\u002Ffleet-gateway.md` (CR5 pi = the record,\n  live on the second-bot `@Esther0001Bot`).\n- **`TELEGRAM_API_BASE` is required and fails CLOSED — an `active` unit is not a\n  WORKING gateway.** The transport resolves the API base at call time and refuses\n  to build a URL without it (`TELEGRAM_API_BASE is not set — refusing to build a\n  Telegram API URL`), so the unit starts, reports `active`, and then backs off on\n  every poll. Set it in the fleet env (`TELEGRAM_API_BASE=https:\u002F\u002Fapi.telegram.org`\n  for the standard API) — Hermes's own gateway supplies this internally, so a\n  migration surfaces it as a NEW requirement. Verify a working gateway from the\n  JOURNAL, not `systemctl is-active`: `journalctl --user -u fleet-gateway.service`\n  must show a real dispatched turn and no recurring `poll error … backing off`.\n  Likewise a pi turn that exits non-zero with `No API key found for openrouter` is\n  the provider key missing, not the gateway — wire `auth.json` via the\n  `env-value.sh` `!command` pattern (see \"Configure a provider\" below) and prove it\n  with `pi auth check --provider openrouter` + one real turn before blaming the unit.\n- **The unit must run the FLEET VENV python, not `\u002Fusr\u002Fbin\u002Fpython3`.** The template's\n  default `ExecStart=\u002Fusr\u002Fbin\u002Fpython3 …\u002Fdaemon.py` crash-loops (`Restart=always`\n  spins it) on `ImportError: psycopg package required` the moment the bot-lock layer\n  tries to reach the PGMQ Postgres — the system python has neither psycopg nor the\n  fleet deps. Repoint both `ExecStartPre`\u002F`ExecStart` at\n  `\u003Chost>\u002F.steadfaste-fleet\u002Fvenv\u002Fbin\u002Fpython3`, and make sure `psycopg[binary]` is\n  installed in that venv (the fleet venv historically lacks it — the same gap that\n  keeps `fleet-update.sh` from exiting clean). `pg_isready -h 127.0.0.1 -p \u003Cpg-port>`\n  confirms the bus Postgres is reachable before blaming psycopg. The venv's dashes\n  `mcp`\u002F`jsonschema`\u002F`idna` are present; psycopg is the usual missing one.\n\n## Configure a provider (OpenRouter + a model)\n\nVerified against the installed package docs — `docs\u002Fproviders.md`,\n`docs\u002Fsettings.md`, `docs\u002Fconfiguration.md` — not inferred:\n\n```bash\n# \u003Cagent-dir>\u002Fauth.json   — {\"\u003Cprovider>\": {\"type\": \"api_key\", \"key\": \"... | !command\"}}\n# \u003Cagent-dir>\u002Fsettings.json — {\"defaultProvider\": ..., \"defaultModel\": ...}\n# \u003Cagent-dir>\u002Fmodels.json — custom\u002Fcompatible models and overrides\n```\n\nSet the model defaults (preserve existing keys — `extensions`, `skills`):\n\n```json\n{\"defaultProvider\": \"openrouter\", \"defaultModel\": \"deepseek\u002Fdeepseek-flash-latest\"}\n```\n\n**Mode-specific models (fleet policy):** the coding default is the fast\n`deepseek-flash-latest`; the **adversarial reviewer** uses the strongest tier,\n`deepseek-v4-pro` (`ops\u002Fscripts\u002Fmanage\u002Freviewer-agent-pi.sh`, overridable with\n`REVIEWER_PI_MODEL`). Every coding agent can override per agent in its own\n`gateway.yaml` backend `model:` field, and per chat via `\u002Fmodel`. A reviewer\nshould never silently drop to the cheap\u002Ffast default.\n\n**Do NOT source an env file to supply the key.** Pi's docs support a `!command`\nprecisely so the resolved key is never written to disk, but the obvious command —\n`bash -lc 'set -a; . ~\u002F.hermes\u002F.env; printf %s $OPENROUTER_API_KEY'` — hands the\ncoding agent EVERY secret in that file, and this skill's own pitfall says the agent\ncan print its own environment. Supply exactly one variable:\n\n```json\n{\"openrouter\": {\"type\": \"api_key\",\n                \"key\": \"!bash ~\u002F.steadfaste-fleet\u002Fscripts\u002Fenv-value.sh OPENROUTER_API_KEY\"}}\n```\n\n`env-value.sh` prints one named value (fleet env first, then the Hermes env, first\nmatch wins), fails closed when absent, and refuses a name that isn't\n`^[A-Z][A-Z0-9_]*$` so it can't become a pattern. Point it at a Hermes-only key and\ncopy that key into the fleet env: no harness should reach into a Hermes-owned file\nfor a provider key.\n\nVerify all three, in this order — the last one is the only real proof:\n\n```bash\npi auth check --provider openrouter          # ready\npi --list-models kimi                        # the model, with context\u002Fthinking capabilities\npi --model \"openrouter\u002F\u003Cvendor>\u002F\u003Cmodel>\" \"Reply with exactly: ready\"   # a real turn\n```\n\n`pi auth check --model \u003Cid>` without the provider qualifier reports `not_ready` even\nwhen the model is fine — check the provider-qualified form.\n\n## Jev integration (the cost-routing hooks)\nThe five high-value Jev hooks in the pi loop, from ten-levels-of-jev and mapped in\nsteadfaste `docs\u002Fdesign\u002Fcoding-cost-routing.md`:\n1. task-routing classifier (before any model is chosen — the biggest saving)\n2. destructive-command gate (before tool execution)\n3. compaction scoring (when context fills — prune lowest-scored instead of a summariser LLM)\n4. cheap file reads (judge a file without reading it into context — $0.00049 vs $0.091)\n5. output-type screening (after an LLM response)\n\n## Web search — pi has NO online tool until a package supplies one\n\nMeasured 2026-10-15 (pi 1.2.0): the built-ins are `read`, `bash`, `powershell`,\n`edit`, `write`, `grep`, `find`, `ls`, plus `codemode`\u002F`tool_search` — and\n`tool_search` ranks the LOCAL tool registry (deferred\u002FMCP tools), never the\nnetwork. The five fleet MCP servers expose no search either. So \"research\nthis\" and \"review this repo\" had no online path at all, and the gateway-served\nagent is no exception: the gateway only spawns this same pi.\n\n- **Install (pinned + age-gated):** `pi install npm:pi-web-access@\u003Cversion>`.\n  It registers `web_search`, `source_check`, `fetch_content` and\n  `get_search_content` — search, URL\u002FPDF\u002FYouTube fetching, and GitHub URLs are\n  CLONED locally so the agent reads real files instead of rendered HTML.\n  **Free is the requirement, not a nicety** — build the keyless chain first and\n  treat a keyed provider as an opt-in upgrade; never introduce a paid dependency\n  for a capability the fleet already gets for nothing.\n- **Pick the pin by MEASUREMENT, never from the README.** The latest release is\n  usually days old and fails the 14-day package age gate, and the gate is not\n  bypassed for convenience: enumerate the versions, sort them as SEMVER (a\n  lexical sort puts `0.5.1` after `0.41.0` and hands you a six-month-old build),\n  and take the newest one that passes.\n  ```bash\n  python3 -c \"import json,urllib.request,datetime,sys;\\\n  d=json.load(urllib.request.urlopen('https:\u002F\u002Fregistry.npmjs.org\u002Fpi-web-access'));\\\n  now=datetime.datetime.now(datetime.timezone.utc);\\\n  k=lambda v: tuple(int(x) for x in v.split('.') if x.isdigit());\\\n  rows=[(k(v),v,ts,(now-datetime.datetime.fromisoformat(ts.replace('Z','+00:00'))).days) \\\n        for v,ts in d['time'].items() if v not in ('created','modified')];\\\n  rows.sort();\\\n  print([(v,a) for _,v,_,a in rows if a>=14][-3:])\"\n  python3 ops\u002Fscripts\u002Fhealth\u002Fcheck-package-age.py npm pi-web-access==\u003Cchosen>   # rc 0 = allowed\n  ```\n  Then bump later through the same gate — the pinned spec is a variable in\n  `install-pi-integration.sh` (`PI_WEB_SEARCH_PACKAGE=...`), so a bump is one\n  env-overridable value, not an edit scattered through the script.\n- **Prove it with a REAL turn, not `pi list`.** A registered extension and a\n  working search are two different claims: run one turn in a scratch repo and\n  read which PROVIDER answered and the URLs it returned\n  (`04-search-exa.txt` \u002F `05-search-ddg.txt` under `docs\u002Fevidence\u002F` are the\n  captured shape). Run it from the contract's own cwd too when the consumer is a\n  service — the gateway spawns pi from its deploy dir, so a probe that only works\n  in a project directory proves nothing about the gateway-served agent.\n- **Free path, no API key:** Exa's keyless MCP free tier plus DuckDuckGo's\n  keyless HTML endpoint. `~\u002F.pi\u002Fagent\u002Fweb-search.json`:\n  ```json\n  {\"searchRouting\": {\"providers\": [\"exa\", \"duckduckgo\"],\n                     \"fallbackOn\": [\"unsupported\", \"transient\", \"quota\", \"network\", \"invalid-response\"]}}\n  ```\n- **`auto` is NOT the free path.** With no config the tool answers\n  `No search provider available …` and lists only KEYED providers — an agent\n  reads that as a broken tool rather than a missing config. Keyless DuckDuckGo\n  is explicit-only (never chosen by `auto`, never in `provider: \"all\"`), so\n  name it in `searchRouting` instead of relying on the default chain.\n- **`pi install` writes a package declaration, not a working tool.** Pi manages\n  its own npm root (`~\u002F.pi\u002Fagent\u002Fnpm\u002Fnode_modules\u002F\u003Cpkg>`); a declaration with\n  nothing on disk loads no extension. Check both halves — the declaration in\n  `settings.json` AND the directory.\n- **A web tool needs NO governance lock.** `fleet-governance.ts` gates only\n  `write`\u002F`edit` and non-read-only `bash`; every non-native tool (extension or\n  MCP) passes by design, so search\u002Ffetch work in an unlocked session.\n- **Wiring:** `ops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh` declares the\n  package, installs it when the directory is absent, and writes\n  `web-search.json` only when no config exists (an operator's keyed file is\n  never clobbered). `ops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh` Layer 6\n  FAILs when either half is missing or the chain has no keyless provider;\n  `tests\u002Ftest_pi_registration_installer.sh` covers it.\n\n## Several pi agents in ONE repo — project-scoped state, and the commit sweep\n\npi keeps USER scope in `~\u002F.pi\u002Fagent`, but for a TRUSTED PROJECT it also writes\n`.pi\u002Fsettings.json` and `.pi\u002Fmcp.json` **inside the checkout**, and the fleet extensions add\nto that (the context extension checkpoints at `turn_end`, so those writes happen every turn).\nHermes keeps all of it in `~\u002F.hermes`, so this hazard does not exist for Hermes agents and\nnobody who has only run Hermes will expect it.\n\nWith more than one pi session in the same repo:\n\n- each session's `.pi\u002F` files appear as untracked files under the other's feet;\n- the first agent to run a broad add (`git add -A`, `git add .`) or `git commit -a` sweeps up\n  files it never wrote — which the operator reports as \"a sweep of the peer's files when the\n  first one tries to commit\", and reasonably blames on governance.\n\nRules:\n\n- **Ignore `.pi\u002F` in every repo pi runs in**, and prove it: `git check-ignore -v\n  .pi\u002Fsettings.json` must name the rule, and `git ls-files .pi` must be empty — a `.pi` path\n  already committed defeats a new ignore and needs `git rm -r --cached .pi`.\n- **Never `git commit -a` on a tree another session may be editing.** Commit by pathspec and\n  assert the staged set first (`git diff --cached --name-only`). No `.gitignore` prevents\n  sweeping a peer's SOURCE edits; only the pathspec does.\n- **When commits on a host keep carrying files nobody wrote, measure what the HARNESS writes\n  into the tree before suspecting the git hooks.** The Hermes hooks stage nothing (no\n  `git add`, `stash`, `checkout --`, `reset`, and no `commit -a` in the commit path), so a\n  sweep on a pi host points at pi's own project state, not at the gate.\n\n## Pitfalls\n- **A presence probe can be wrong about a managed install.** `command -v pi` reports\n  \"missing\" on a host where Pi is installed and working, because the entrypoint is a\n  symlink into a bin dir that need not be on PATH. When a probe says a tool is absent,\n  check the install LAYOUT (launcher, `current-version`, `releases\u002F`) before reporting\n  it missing to anyone — a false \"not installed\" sends the user chasing a non-problem,\n  and the correction costs more than the check did.\n- **Local small models (qwen2.5:3b) are weak at tool-calling** — use offline\u002Flocal\n  for *generation* and let pi do the *loop*; a ROUTINE task that needs tool-chaining\n  routes to a hosted workhorse rather than forcing the local model to tool-call.\n- **A block notice is an instruction, not a control** — an agent was observed\n  routing around a write gate by writing the same file via a bash heredoc. The\n  deterministic gate remains the authority; Jev gates add scrutiny, never remove it.\n- **The agent can read its own environment** — its bash tool can print every env\n  var it was given. Hand pi only shell basics + the Jev\u002Fprovider keys + Jev settings;\n  treat `.sessions\u002F` as sensitive.\n- **Never let the agent author its own Jev question blocks at runtime** (steadfaste\n  MN-3: the question is the policy). The questions are Steward-ratified Decision\n  Class config; the agent reaches for Jev, it does not write the questions.\n- **Fail closed on routing** — an undecidable\u002Funknown\u002Fmissing classification routes\n  pessimistically to the most capable (most expensive) tier, never a silent cheap\n  default.\n- **An optional chain over a guessed API hides the defect** — `event.completed?.()`\n  returned `undefined` against a non-existent method, so every checkpoint was\n  written EMPTY while the code looked defensive. When a hook must produce output,\n  assert the output is non-empty (warn loudly with the observed keys) rather than\n  letting `?.` be the difference between working and silent.\n- **Verify a hook's or tool's EFFECT without an LLM run.** A host with no provider\n  ready cannot run a turn, so don't wait on one to test wiring: load the extension\n  with **pi's OWN TypeScript loader** (it ships jiti in its release `node_modules`),\n  call its default export with a fake `pi` (`{ on, registerTool }`) that captures the\n  handlers\u002Ftools, fire a synthetic event in Pi's real shape, and assert the effect\n  landed (a store row exists) — a stderr marker alone proves only that the handler ran.\n- **A guard that greps cannot see a signature or a schema shape — EXECUTE the wiring.**\n  Guards asserting that tool NAMES exist and that the shared CLI is called all passed\n  while every tool was dead, because the defect was the tool definition's SHAPE. Load\n  the real extension, hand it a stub `pi`, and CALL `execute(id, params)` against a\n  throwaway CLI — never the real store. Then prove the guard discriminates: run it\n  against the PRE-FIX extension and require it to FAIL\n  (`TypeError: \u003Ctool>.execute is not a function`). A guard that has never failed on the\n  broken artifact is a happy path, not a guard. Recipe and exact shapes:\n  `references\u002Fextension-tool-api.md`.\n- **`ToolResultEventBase` carries `input`\u002F`content`\u002F`isError` but NOT `toolName`** —\n  only the concrete variants (`BashToolResultEvent`, …) declare it. Read `toolName`\n  defensively in a generic `tool_result` handler.\n- **Never put `*\u002F` inside a block comment — a GLOB will close it early.** Writing an\n  identifier like `mem_*\u002Fsession_*` (or any `foo_*\u002Fbar`) in a `\u002F** … *\u002F` header ends\n  the comment at the `*\u002F`, so the rest parses as code and the extension fails to LOAD\n  (`ParseError: Missing semicolon`, or `SyntaxError: Unexpected token '*'`). Pi then\n  reports the tools as missing, which reads like a wiring problem rather than a typo.\n  Write `memory\u002Fsession`, or space it (`mem_* \u002F session_*`). The same trap applies to\n  any glob you paste into a JSDoc\u002FTSDoc comment.\n- **`python3` may not be on pi's PATH on macOS** — Homebrew is `\u002Fopt\u002Fhomebrew\u002Fbin`\n  (Apple Silicon) or `\u002Fusr\u002Flocal\u002Fbin` (Intel), and a GUI-launched pi sees a narrower\n  PATH than your shell. Make the interpreter overridable (e.g.\n  `FLEET_CONTEXT_PYTHON`) instead of hardcoding `python3`.\n- **An MCP entry's interpreter needs its TLS dependencies, not just the module you probed.**\n  `python-with-module.sh --print mcp` proves `mcp` imports and says nothing about the CA bundle the\n  server's HTTP client needs, so an entry can resolve clean and still start DEAD on TLS. The\n  `Could not find a suitable TLS CA certificate bundle` message is raised byte-identically by both\n  `requests` and `httpx`, so it names no library — and never justify KEEPING a package with \"pip\n  would break\": pip vendors its own certifi\u002Frequests\u002Furllib3\u002Ftruststore and is unaffected. An\n  interpreter resolution, the import-chain rule for deciding a dependency is load-bearing, and the\n  old-venv-path failure after a home-dir migration: `references\u002Fmcp-server-interpreter-tls.md`.\n","# Pi Coding Agent\n\nThe coding-agent harness the fleet owner wants for steadfaste (replacing hermes).\n`@earendil-works\u002Fpi-coding-agent` — a MANAGED install, not an npm global (see\nInstall below). The reference for pi + Jev\nintegration is `github.com\u002Fdisler\u002Ften-levels-of-jev` (30 tested Jev use cases in\n10 levels; levels 6–10 put Jev inside pi).\n\n## Install — a MANAGED install, NOT an npm global (corrected 2026-10-02)\n\nPi installs itself into its own agent directory and pins each release; there is no\n`npm install -g`. Measured on a live host:\n\n    ~\u002F.pi\u002Fagent\u002Fbin\u002Fpi                        launcher (sh): reads the version, execs the release\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version       the authoritative version string (1.0.0 here)\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Fmanaged-install.json  {kind: pi-managed-install, layout: releases-v1,\n                                               entrypoint: symlink -> \u003Cuser bin dir>\u002Fpi}\n    ~\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F\u003Cv>\u002Fnode_modules\u002F.bin\u002Fpi    the real executable\n    ~\u002F.local\u002Fshare\u002Fpi-node\u002Fcurrent\u002Fbin        Node.js that PI installs and manages\n\nConsequences that cost time and must not be re-learned:\n\n- **`command -v pi` is NOT a reliable probe.** The entrypoint is a symlink into the\n  user's bin dir (a linuxbrew `bin\u002F` on one measured host). When that\n  dir is not on PATH, `pi` looks *missing* to every caller while being installed and\n  working. Invoke the launcher directly — `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` — or read\n  `~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version` without executing anything.\n- **Pi's Node is deliberately NOT on shell profiles.** The launcher puts\n  `~\u002F.local\u002Fshare\u002Fpi-node\u002Fcurrent\u002Fbin` on PATH for itself and its children, so `node`\n  and `npm` resolve correctly inside pi and nowhere else. Do not \"fix\" that by\n  exporting it globally.\n- **Extension type defs live in the release, not an npm root:**\n  `V=$(cat ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version)` then\n  `$HOME\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\u002Fdist\u002F...`\n- **Never infer the version from a doc or a package name** — read `current-version`\n  (or the launcher's `--version`). A harness registry claiming a shipped version can\n  be stale on any given host — MEASURE it: one host read 1.2.0 (with both 1.1.0 and\n  1.2.0 present under `releases\u002F`) while the registry's own `why:` prose still\n  described 1.0.0. Read the type defs from the release you just measured, never from\n  the prose about it.\n- Verify: `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi --version` and `--help` (read\u002Fbash\u002Fedit\u002Fwrite tools, plus\n  the `pi install\u002Fremove\u002Flist\u002Fconfig\u002Fauth` extension commands).\n\n## Core\n- Built-in tools: read, bash, edit, write.\n- `pi install \u003Csource>` \u002F `pi remove \u003Csource>` manage extension sources;\n  `pi list` shows installed extensions.\n- An extension is loaded as `pi -e extensions\u002F\u003Cname>.ts --tools read,bash,edit,write[,\u003Cjev tools>]`\n  — the `--tools` allowlist is explicit; only listed tools are available.\n\n## stdout shape non-interactive — MEASURED, do not guess\n\nA non-interactive pi turn writes EXACTLY the assistant's final answer to stdout and\nnothing else — verified with a plain prompt and with a prompt that used the bash tool:\n\n    $ ~\u002F.pi\u002Fagent\u002Fbin\u002Fpi --model \u003Cm> \"List three fruits, one per line, numbered 1. 2. 3.\"\n     1. Apple\n     2. Banana\n     3. Cherry\n\n- **Chatter goes to stderr and pi's own log, never to stdout.** So a wrapper that uses\n  stdout verbatim is CORRECT, and one that takes \"the last line\" only TRUNCATES every\n  multi-line answer down to its final line — a reply that arrives but is not complete.\n  Verify stdout and stderr separately before choosing any output-shaping mode.\n- **A fresh `--session-id` prints a benign stderr warning** — `Warning: No project session\n  found with id '\u003Cid>'; creating a new session with that id.` — and still exits 0. That is\n  how a per-chat session gets created, not a failure to report.\n- **Call the launcher by absolute path from a service or wrapper.** `~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` is\n  the launcher; the `pi` symlink in a user bin dir is not on a service PATH. Wrappers pass\n  an ARGV LIST rather than a shell line, so nothing expands `~`\u002F`$HOME` — a relative or\n  guessed path becomes a silent per-message no-op. Pin the session identity too (e.g. a\n  `FLEET_SESSION_KEY`): a harness started outside a git repo cannot derive repo\u002Fbranch and\n  every chat otherwise collapses onto ONE session.\n\n## Driving pi from another process — control calls go over RPC, never a prompt\n\nA wrapper that only sends prompts is missing half the interface, and the missing half\nfails in ways that read as pi being broken (working adapter to copy:\n`ops\u002Fscripts\u002Ffleet_gateway\u002Fpi_control.py` in steadfaste-fleet).\n\n- **A built-in slash command sent as a prompt is a NO-OP.** `\u002Fcompact`, `\u002Fmodel`,\n  `\u002Fnew`, `\u002Frestart`, `\u002Fsettings` are handled only in the interactive\u002FRPC surfaces; as a\n  prompt they become conversation (a forwarded `\u002Fnew` is answered as prose while every\n  bit of context stays). Session and state operations go over **RPC mode**:\n  `pi --mode rpc` takes one JSON record per line on stdin (`{\"type\":\"get_state\"}`,\n  `{\"type\":\"compact\"}`, `{\"type\":\"set_model\", …}`) and answers with a `response`\n  record on stdout — correlate by the `id` you sent, never by response order.\n- **Pass `--no-mcp` for a control call.** pi connects its MCP servers at RPC startup,\n  and with them enabled the control call sat ALIVE and SILENT (no stdout, no stderr)\n  for the whole deadline on ~40% of runs; the same call answered 8\u002F8 in ~1.2 s with\n  `--no-mcp`. A control call uses no MCP tool, so those servers are pure risk there.\n- **Watch the process EXIT as well as EOF.** EOF is not the only end of an answer:\n  pi's MCP children inherit its stdio, so a lingering grandchild holds the write end of\n  the pipe open — no data, no EOF — and a reader waiting only for EOF blocks for its\n  full deadline. Start pi in its own process group (`start_new_session=True`) and kill\n  the GROUP on timeout, so a wedged control call does not also leak children.\n- **`compact` never answers for a session whose transcript does not exist yet**\n  (45 s+, repeated), while `get_state` on the same id answers in ~1.2 s and creates it.\n  Ask for the state first and answer \"no conversation yet\" — a chat that has just\n  started a fresh session is exactly this case, and it is the common one.\n- **Give a check three outcomes, not two**: `0` ok · `1` a NEGATIVE answer · `3` could\n  not verify. `--offline --list-models \u003Cpattern>` prints `No models matching \"x\"` and\n  still **exits 0**, so a verdict read off the exit code is wrong in both directions —\n  decide from the OUTPUT, and make \"pi cannot be run at all\" its own outcome rather\n  than a failed check. The same split lets a caller refuse a bad model name instead of\n  breaking every later turn with it.\n\n## Extension API (the Jev-hook surface)\n\n**Read the installed type defs before writing a hook — never infer the signature.**\n```bash\nV=$(cat ~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version)\nP=\"$HOME\u002F.pi\u002Fagent\u002Finstall\u002Freleases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\"\nsed -n '1,60p' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts   # + grep the event interfaces\ngrep -n -A20 'registerTool' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts        # the tool registration contract\ngrep -n -A8  'interface ToolDefinition' \"$P\"\u002Fdist\u002Fcore\u002Fextensions\u002Ftypes.d.ts\n# AgentToolResult is NOT in this package — it comes from the agent core:\ngrep -rn -A12 'interface AgentToolResult' \"$P\"\u002F..\u002Fpi-agent-core\u002Fdist\u002Ftypes.d.ts\n```\n\nRead `ToolDefinition` FIRST. It is the contract the extension must satisfy, and a\ndoc or an older example that disagrees with it is what breaks the harness silently.\n\n- **Hooks** — `pi.on(\"tool_call\" | \"tool_result\" | \"turn_end\" | \"before_agent_start\" | \"session_before_compact\", fn)`. A `tool_call` hook can `return { block: true, reason }` to stop a tool call before it runs; the agent sees only the reason + a notice that the block is final.\n- **The handler's FIRST parameter is the EVENT, not a ctx**: `ExtensionHandler\u003CE> = (event: E, ctx: ExtensionContext) => R`. Reading `ctx.\u003Cthing>` off that first parameter yields `undefined`.\n- **Injection is the RETURN VALUE.** `before_agent_start` returns `BeforeAgentStartEventResult` (`{ message?, systemPrompt? }`); there is **no `ctx.addSystemPrompt()`**. To add context, return an augmented `systemPrompt` (or a `message`).\n- **Event payloads carry the data**: `turn_end` → `{ turnIndex, message, toolResults, entries, outcome }`; `before_agent_start` → `{ prompt, images, systemPrompt, systemPromptOptions }`. Derive what you need from the event.\n- **Tools** — `pi.registerTool({ name, label, description, parameters, execute })`.\n  `execute(toolCallId, params, signal?, onUpdate?)` returns an `AgentToolResult`:\n  `{ content: [{ type: \"text\", text }], details }`. **`run` is the pi 0.87.1 shape and\n  is silently ignored on 1.0.0** — every call then fails with\n  `definition.execute is not a function`, which an agent reads as \"memory is broken\"\n  when the store is fine and the tool WIRING is not. `parameters` must be an object\n  schema (`{ type: \"object\", properties, required }`); a bare param→schema map\n  (`{peer:{type:\"string\"}}`) is not validatable, so a correct `execute` still fails.\n  Build the schema AND the argument extraction from ONE properties map so the two\n  cannot drift apart. Tool descriptions carry the question schema.\n- **Verify a hook fires AND does its job** — a stderr marker in the handler proves the hook ran, not that the effect landed. Assert the effect (did the injected text appear? did the row have content?).\n- **Compaction** — `.pi\u002Fsettings.json` sets `compaction.keepRecentTokens` low so compaction has material; `ctx.compact()` wraps pi's compaction; `ctx.getContextUsage()` feeds the numbers.\n\nExact type shapes, the probe commands, and the executable-guard recipe:\n`references\u002Fextension-tool-api.md`.\n- **Side channel** — report every decision on stderr as `JEV_EVENT` lines (and as session entries) so a run is auditable line-by-line (tool call, hook decision, Jev call, model, cost, context).\n\n## Fleet context (memory + session)\n\n**Pi >= 0.99 \u002F 1.0 has an MCP client** (pi 1.0.0, reproduced: `pi mcp list` reports\n`fleet-context: connected, N tools`): it reads\n`mcpServers` from `~\u002F.pi\u002Fagent\u002Fmcp.json` (user scope) and `.pi\u002Fmcp.json` (trusted\nprojects only), the same shape as Claude Code. Governance is therefore an MCP\nregistration — never hand-write a lock:\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-mcp.sh   # loop-governance, tasks, executor, agent-bus, fleet-context\npi mcp list                                                 # expect 5 servers, state \"connected\"\n```\n\n**Verify a host VERSION-AWARE — never by assuming the route.**\n`bash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh` reports PASS\u002FFAIL\nper layer (MCP servers, skills, extension, governance gate, `agent.env`),\nreads the installed version from the Pi install itself, and checks the REGISTERED\nskills path and its count instead of a hardcoded list. Auditing\nwith the MCP checklist on a Pi that has no MCP client reports FAIL for something\nthat route cannot deliver — the failure is in the checklist, not the host. A server\nmissing from `mcp.json` on a non-orchestrator host is usually a DEPLOY-SCOPE bug\n(a server registered `register_orch` ships only to orchestrators), not a broken\ninstaller: `install-pi-mcp.sh` warns and registers the rest, so 3-of-4 looks normal.\n\n### The SKILLS half — the adapter must be RUN, not merely deployed\n\nPi advertises each skill's NAME + DESCRIPTION at startup and loads the body on demand.\n\n**Exposure is ALL skills, from the fleet-owned published tree — NOT a curated subset.**\nThe manifest no longer governs what a coding agent can read; it stays the record of the\nritual skills Hermes must load before a write. Do not \"restore\" a curated set from\n`skills.yaml#always` — a subset here is exactly what was removed, and the operator asked for\nevery harness to see every skill.\n\n**How Pi enumerates — read from its own loader (`dist\u002Fcore\u002Fskills.js`), never assumed.\nRe-read it when the version moves:**\n\n**Resolve the loader from the INSTALLED release, never a hardcoded version path.** Pi\nupdates itself — a `current-version` observed moving 1.3.0 → 1.4.0 mid-session — so a\nprobe that imports `releases\u002F\u003Cold>\u002F…\u002Fdist\u002Fcore\u002Fskills.js` silently measures the OLD\nloader and reports rules that no longer apply. Read\n`~\u002F.pi\u002Fagent\u002Finstall\u002Fcurrent-version` and import\n`releases\u002F$V\u002Fnode_modules\u002F@earendil-works\u002Fpi-coding-agent\u002Fdist\u002Fcore\u002Fskills.js`. Before\nblaming a version move for changed behaviour, `diff` the two releases' `skills.js`:\nbyte-identical files mean the enumeration rules did not move and the difference is\nsomewhere else.\n\n**Reading the loader tells you the RULES; running it tells you what an agent actually\ngets.** `scripts\u002Fpi-skills-diagnostics.mjs` imports `loadSkills` from the installed\nrelease and prints, for a tree you name: the skill count, every diagnostic grouped by\nmessage, and each name collision with its winner and loser. Point it at\n`~\u002F.agents\u002Fskills` to reproduce a host's report verbatim (`node \u003Cskill>\u002Fscripts\u002Fpi-skills-diagnostics.mjs`),\nor at an extracted older revision to prove a fix changed the outcome — same tool, two\ntrees. It exits 1 when diagnostics exist, so it is usable as a gate.\n\nDiagnostics are WARNINGS, not refusals: a refused skill shows up as `description is\nrequired` (or a YAML parse message) and is simply absent from the loaded set, so count\nthe loaded skills too — a tree whose file count dropped is how a silent refusal\nbecomes visible.\n\n- **It FOLLOWS symlinks.** A symlinked ROOT is read, and a symlinked skill directory is\n  recursed into (`entry.isSymbolicLink()` → `statSync()` → recurse into it). Pointing `skills`\n  at a symlinked published tree works; a per-skill link farm is unnecessary.\n- **A directory containing `SKILL.md` IS one skill and recursion STOPS there.** Never put a\n  `SKILL.md` at the root of a tree you want enumerated — the rest of the tree becomes invisible.\n- **It honours `.gitignore` \u002F `.ignore` \u002F `.fdignore` AT THE SKILLS ROOT**\n  (`ig.ignores(relPath)`). A stray ignore file silently hides skills while the registration\n  looks perfect, which is why a `--check` must assert the COUNT the agent can see, never merely\n  that the path is written into `settings.json`.\n- **Direct `*.md` children load ONLY at the ROOT.** `includeRootFiles` is true only for the\n  top-level call, so a `DESCRIPTION.md` sitting beside a category's skill directories is NOT a\n  skill — a false lead when chasing a name collision. Only a `*.md` directly in the registered\n  tree is read as a skill.\n- **Dot-entries are SKIPPED** (`entry.name.startsWith(\".\")`), so a `.archive\u002F` of retired\n  skills inside the tree is never enumerated and a `SKILL.md` sitting there is NOT the\n  collision it looks like. Before \"cleaning up\" a dot-directory to silence a loader\n  diagnostic, check whether the loader can see it at all — for Pi it cannot.\n- **A `description` is REQUIRED, or the file is not a skill at all.** `loadSkillFromFile`\n  returns `skill: null` when the description is absent or blank, so the name never enters the\n  index and the body is unreachable — the file is REFUSED, not merely unindexed. This is why\n  a deprecated redirect stub with no description is dead weight: its \"load X instead\" text\n  reaches nobody. And `name` falls back to the PARENT DIRECTORY name when frontmatter omits\n  it, which is how a directory-derived name silently collides with a declared one.\n- **Symlink visibility is PER-READER — never generalise it from one probe.** Measured on a single\n  tree: a symlinked ROOT is visible to `pathlib.rglob`\u002F`os.walk` but INVISIBLE to plain `find`\n  (no `-L`), which reports zero; a per-skill symlink FARM is invisible to plain `rglob`\u002F`os.walk`\n  (only `followlinks=True` sees it). Pi happens to follow both, so its loader is the authority for\n  Pi — read it, and assert the COUNT the agent can see rather than trusting a mode that worked\n  for a different reader.\n- The cross-client standard path is `~\u002F.agents\u002Fskills`, read natively by Codex, Cursor,\n  Copilot CLI, OpenCode and Antigravity. A harness that reads only a private path\n  (`~\u002F.pi\u002Fagent\u002Fsettings.json`, `~\u002F.claude\u002Fskills`) needs a pointer to it.\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh           # wire it\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh --check   # rc 0 ONLY if Pi can see EVERY skill\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh             # per-layer audit\n```\n\nIt writes `~\u002F.pi\u002Fagent\u002Fsettings.json` — `\"extensions\": [\u003Cfleet-context.ts>, \u003Cfleet-governance.ts>]`\nand `\"skills\": [\"~\u002F.agents\u002Fskills\"]` — and RETIRES a pre-existing `~\u002F.pi\u002Fagent\u002Fcortex-skills`\nlink farm when one is found: a stale farm keeps Pi loading a curated subset beside the whole\ntree. Idempotent, and it preserves the user's other keys. It no longer reads `skills.yaml` at\nall — the manifest is fleet-owned at the REPO ROOT (`skills.yaml`, synced to\n`~\u002F.steadfaste-fleet\u002Fskills.yaml` by `fleet-update.sh`) and is the record of Hermes's ritual set,\nnot the source of a coding agent's exposure.\n\n**Drive it with `fleet pi` instead of remembering script names** (a thin driver over the same\nscripts — repo-then-deployed resolution, the owner's rc passed through unchanged):\n\n```bash\nfleet pi install   # user scope: MCP servers + both extensions + the published skills tree\nfleet pi check     # installer --check (registration AND visible count) + the per-layer audit\nfleet pi skills    # what Pi is pointed at, then the delegated visibility verdict\n```\n\n`fleet harness install pi --dir \u003Cproject>` is the PROJECT-scope command; `fleet pi` is the\nHOST-scope one (every Pi project on the machine).\n\n- **Registering is not executing.** A deploy that COPIES an installer into\n  `~\u002F.steadfaste-fleet\u002Fscripts\u002F` has wired nothing, so a host with Pi installed can sit unwired with\n  no signal at all. Gate the run on PRESENCE (`~\u002F.pi\u002Fagent\u002Fbin\u002Fpi` or the `~\u002F.pi\u002Fagent` dir), run\n  BOTH halves (`install-pi-mcp.sh`, `install-pi-integration.sh`), and report the outcome: a host\n  without Pi is not a fault; a host with Pi that comes out of a deploy unwired is. The doctor's\n  `Pi integration` line is the drift guard that keeps it from going quiet again.\n- **Point it at the PUBLISHED tree; never hand-build a bridge.** A bespoke loader (a `\u002Ftmp`\n  builder script, a JSON index, a shell script that fixes up links) has no owner: not deployed,\n  not verified, gone with the machine. The supported route is the published tree\n  (`~\u002F.agents\u002Fskills`, produced by `ops\u002Fscripts\u002Fmanage\u002Fpublish-agent-skills.py` from the\n  fleet-owned defaults) registered once at user scope. Wire the WHOLE library deliberately,\n  and expect its cost at startup: every installed skill's name + description is preloaded, so\n  the size of that tree IS the session's context cost.\n- **The skills half needs PyYAML and must not pick its interpreter by PATH.** `command -v python3`\n  is the interpreter most likely to LACK it, so the installer reports `PyYAML required` and skips\n  the skills half on a host that has everything — resolve through\n  `ops\u002Fscripts\u002Flib\u002Fpython-with-module.sh --print yaml` first and keep a bare PATH pick as the last\n  resort only.\n\nThe **memory\u002Fsession TOOLS** also come from that MCP server — the SAME\n`fleet-context-mcp.py` Claude Code and Codex use, so the schemas are DERIVED\nfrom the store contract and there is no per-harness tool list left to drift.\nThe extension keeps ONLY the lifecycle triggers, which MCP cannot provide:\n\n```bash\nbash ~\u002Fsteadfaste-fleet\u002Fops\u002Fscripts\u002Finstall\u002Finstall-pi-mcp.sh   # + fleet-context\ncp ~\u002Fsteadfaste-fleet\u002Fops\u002Finstall\u002Fharnesses\u002Fpi\u002Fextensions\u002Ffleet-context.ts extensions\u002F\npi -e extensions\u002Ffleet-context.ts --tools read,bash,edit,write\n```\n\nAn older Pi (\u003C= 0.87, no MCP client) reaches the same governance through the\n`loop-gov` CLI instead.\n\nThe extension registers **NO tools** and wires only the lifecycle:\n\n- `before_agent_start` → restore + inject the checkpoint (a fresh session resumes)\n  AND inject any standing rule you want in EVERY session (see \"Standing rules are\n  INJECTED\" below); cover BOTH branches — fresh and resume-with-no-snapshot — or a\n  restored session silently misses the rule.\n- **`turn_end` → write a checkpoint** — the harness owns WHEN, never the model\n- `session_before_compact` → checkpoint before continuity is lost\n- **`tool_result` → record the tool event** for tools a gate asks about. The git hook\n  is GLOBAL, so a Pi commit is gated by the same reflexion gate as a Hermes one, and\n  that gate reads HC's store — not the harness's own DB. With no `tool_result` hook a\n  Pi session has no recorded evidence and **every commit is refused** no matter how\n  well the agent behaved.\n\n### Standing rules are INJECTED, not loaded — the third binding surface\n\nPi's standing context = skill NAMES+descriptions + what the harness injects; a rule\ninside a skill body binds only if the agent happens to load it, and SOUL\u002FMEMORY\u002FUSER.md\nare never read by Pi. Three surfaces reach EVERY Pi session, cheapest-effective first:\n\n1. **`before_agent_start` systemPrompt injection** (fleet-context extension) — the\n   ONLY surface that is truly always-on; it is PAID as context on every turn, so keep\n   it to a compact checklist (~7 lines; the pre-ship checklist is the exemplar:\n   right-first-time, survey-before-build, test-edge-cases, evidence-before-done,\n   doctor-clean, plan-review-first, escalate-review-first). Inject in BOTH branches —\n   fresh AND resume-with-no-snapshot: the verifier sets `FLEET_STUB_EMPTY_RESTORE=1`\n   to force the no-snapshot branch and asserts the checklist appears in each output,\n   or a restore silently misses the rule.\n2. **AGENTS.md \u002F CLAUDE.md** — zero persistent token cost; the place for durable prose.\n3. **The commit-time ritual gate** — a discipline listed in the ritual loop\n   (`reflexion-check survey-before-action prove-before-create agent-contract`) is\n   REFUSED-until-loaded; the only surface with teeth.\n\nBehaviour rules for the agent: insurance at (1), durable prose at (2), the hard\nrule at (3) — never only in a skill body it may never load.\n\n### The WRITE GATE — a SECOND extension, because pi's tools are not Hermes' tools\n\n`extensions\u002Ffleet-governance.ts` (added 2026-10-14, titus). Its `tool_call` handler\nblocks a write-capable NATIVE tool call when no governance lock covers the session's\nrepo. Load it with the harness: `bash install-pi-integration.sh` registers both files.\n\n**Why the existing layers did not cover this — verify before believing either way.**\n\n- The Hermes enforcer plugin (`~\u002F.hermes\u002Fplugins\u002Fgovernance-enforcer\u002F`) is a *Hermes\n  plugin*. It runs in the Hermes agent loop, so pi's native `read`\u002F`bash`\u002F`edit`\u002F`write`\n  never cross it. Registering loop-governance over MCP gives pi the *ritual*, not a\n  gate: an MCP server is a tool surface and cannot see the host's own tools.\n- The commit-time hook DOES carry a lock check (`pre-commit-score`, \"Level 3\"), so a claim that it has none is wrong — but its refusal is scoped\n  `IS_FLEET_REPO && !LOCK_FOUND`, i.e. `~\u002Fsteadfaste-fleet` only, deliberately, so manual\n  human commits in client repos are not blocked. The RITUAL gate is NOT so scoped:\n  the reflexion\u002Fsurvey loop demands the ritual skills in EVERY repo since 2026-10-29,\n  skipping only no-session (human) commits — so a Pi session IS disciplined in its\n  project repos, by a gate placed where the agent actually works.\n\n**It adds no semantics.** The verdict comes from the shared implementation —\n`loop-gov.py check_repo_lock '{\"repo_path\":\"\u003Crepo>\"}'`, which is `loop-gov-mcp.py`'s\nown `_check_repo_lock` + `_live_locks` (staleness rule included). rc 0 = covered,\n1 = refusal, 3 = unreachable. Never re-implement \"does a lock cover this repo\" in a\nharness: the git hook already carries one copy and two copies drift.\n\n- **Classify bash by COMMAND, never by shell syntax.** A metachar rule (`;` `|` `>` …)\n  is a bypass: `cp`, `mv`, `rm`, `tee`, `dd`, `mkdir`, `touch` contain none of them.\n  The gate uses a read-only ALLOWLIST with deny-by-default, so anything not on it —\n  needs a lock. Investigation tools (docker ps\u002Flogs\u002Finspect\u002Fstats, journalctl,\n  ss\u002Fnetstat, curl GET, systemctl status, pip\u002Fnpm list) ARE on it — the gate\n  protects against CHANGES, not against investigation. Read-only COMPOUNDS\n  (`ls | grep foo`, `docker logs c | tail -20`) are lock-free too: every\n  `|`\u002F`&&`\u002F`;` segment must independently match (the enforcer's model). A\n  redirect, a substitution, a second write-class segment, or a mutating flag\n  inside a read primitive (find -exec, sort -o, date -s, journalctl --vacuum-*,\n  docker run\u002Fexec, systemctl start, curl -d\u002F-o) makes the whole thing a write.\n- **Fail CLOSED on every cannot-verify path** (CLI missing, governance unreachable, no\n  repo resolvable), with the cost stated in the block message and NO agent-side\n  override. A gate that reads \"could not check\" as \"carry on\" fails open exactly when\n  the host is broken.\n- **Resolve the governed repo from the CALL's own arguments first**, then\n  `FLEET_SESSION_REPO`, then the process cwd. A `tool_call` hook is handed the tool input\n  and no session cwd, so path-args-only resolution leaves every path-less command\n  (`git commit -m …`, a bare compound) with no repo — and a session launched outside the\n  checkout can never name the tree its call touches, including the `cd \u003Crepo> && git\n  rev-parse --show-toplevel` an agent would use to PROVE it. The measured failure is a\n  total deadlock: every write refused with \"cannot determine the repo\" while the agent was\n  standing in the repo, and the one command that would have settled it was itself the\n  blocked write. Take the repo from file-shaped inputs (`path`, `file_path`, `filePath`,\n  `filename`, `target`) and from absolute paths named inside a shell command, trying the\n  path and then its directory — a FILE is not a git cwd.\n- **Find the repo root by WALKING UP for a `.git` entry; never require the `git` binary to\n  find it.** A macOS launcher (app, service, GUI) commonly runs with a PATH that lacks\n  `\u002Fopt\u002Fhomebrew\u002Fbin`, so `execFileSync(\"git\", …)` raises ENOENT while git works fine in\n  the operator's own shell — and the gate then reports \"not in a git repo\" about a folder\n  that is one. Walk with `fs.statSync(path.join(dir, \".git\"))` (a `.git` FILE counts:\n  worktree or submodule) and hand git only what a walk cannot see (bare repo, `GIT_DIR`).\n  Finding where a repo STARTS needs no git; only reading it does.\n- **A fail-closed refusal must CARRY the reason it could not verify.** Keep stderr, the\n  exit code and the path tried, and print them in the block. That is the difference\n  between \"git is not on this process's PATH (ENOENT)\" and \"this folder is not a repo\" —\n  without it the operator is told the wrong thing and cannot fix it, and the next\n  diagnostic re-derives what the code already knew.\n- **Prove it by EXECUTING the extension**: `node ops\u002Finstall\u002Fharnesses\u002Fpi\u002Fverify-governance-extension.mjs`\n  loads it through pi's own jiti loader, hands it a stub `pi`, fires synthetic\n  `tool_call` events and asserts both directions — plus the no-metacharacter write\n  commands above. `tests\u002Ftest_pi_governance_gate.py` additionally requires the guard to\n  FAIL when pointed at a gate that blocks nothing (`PI_GOV_EXT=\u003Cbroken>`), and at the\n  REAL extension with only the named-lock rendering removed; a guard that\n  has never failed is a happy path.\n- **A refusal names the live locks it did NOT match.** `check_repo_lock` returns\n  `other_locks` (task_id, agent, session_id, repo_path, status, heartbeat_at) beside\n  `live_lock_count`, and the block message renders the first three as\n  \"Live locks on this host — none covers this repo:\" with a `… and N more` remainder.\n  A lock that records no `repo_path` is named as covering nothing rather than dropped.\n  The harness only RENDERS what the predicate reported — it must never parse lock\n  files to work out whose lock is blocking.\n- **A stub proves the HANDLER; only a real session proves the WIRING.** The guard above\n  hands the extension a synthetic `pi`, so it passes green even on a gate pi never\n  calls — those are two separate claims, and the second is the one that matters. Run one\n  real turn in a scratch project repo and read the gate's OWN log\n  (`~\u002F.steadfaste-fleet\u002Flogs\u002Fpi-governance.log`, one `GOV_VERDICT` line per decision) rather\n  than the agent's prose summary. Expect `refused` on the first write and then `allowed`,\n  because the block names `begin_change` as the remedy and the agent simply complies —\n  self-remediation is the gate working, not the gate failing. A gate that only ever\n  blocked would be a deadlock. Watch the log, not the file listing: the turn's stdout is\n  the agent's SELF-REPORT, and the write it claims may have been refused and retried.\n\n- **A Pi session's governance lock is tagged from the SESSION's repo, never from the\n  host's `~\u002Fsteadfaste-fleet` (2026-10-09, titus).** Pi injects no repo identity, so\n  `_derive_slug()` resolves it as `FLEET_SESSION_REPO`, else the MCP child's working\n  directory — the project you launched Pi in. Before that fix a Pi session working in a\n  project repo was locked as `steadfaste-fleet`, and the close gate refused forever with\n  \"the lock's repo cannot contain this session's work\": the lock stays HELD on a refusal,\n  and its prescribed remedy (an enforcer injection) does not exist on Pi, so only the\n  operator could delete `~\u002F.steadfaste-fleet\u002Fstate\u002F.governance-sess_*.json`. Launch Pi from\n  the project (`cd repo && pi`), or pin `FLEET_SESSION_REPO` in the MCP `env` block when\n  the cwd is not the project. It needs a DEPLOY, not a pull: the harness runs the\n  deployed copy (`~\u002F.steadfaste-fleet\u002Ftools\u002Floop-governance\u002Floop-gov-mcp.py`). Verify with\n  `python3 tests\u002Frun_non_hermes_lock_release_repro.py` (pre-fix \u002F working-tree \u002F DEPLOYED\n  in one run; it exits non-zero unless the lock is released). Full write-up:\n  `docs\u002Ftroubleshooting.md`.\n\n**Do NOT register the shared tools in the extension.** They used to live there as a\nhand-written `tool()` list with hand-written parameter maps — a SECOND definition of\ntools that already existed in the contract, and the copy that broke silently when pi\nmoved 0.87.1 → 1.0.0. Two definitions of one capability means the runtime resolves one\nand the other becomes a phantom. Tools stay in the shared MCP server; only the\ntriggers stay in the extension.\n\n### The COMMIT-time ritual gate — where DISCIPLINE binds (all repos)\n\nBeyond the write lock, a Pi commit is judged by the same pre-commit ritual gate as\nHermes — in EVERY repo. `reflexion-check.py --skill \u003Cname>` is generic, and the\ngate's loop demands `task-orient execute-right\nverify-and-ship` for a governed session. The session split is what makes \"all repos\"\nsafe: a Pi session holds a begin_change lock, so it is JUDGED anywhere; a human\ncommit has no session and is skipped (`--skip-no-session`). A discipline meant to\nchange Pi's behaviour belongs HERE — a skill in the loop that the gate refuses until\nthe agent loads (loading = reading the SKILL.md, recorded by the `tool_result`\nhook) — never only in a skill body it may never load.\n\n**Consequence for guidance placement:** the only files a non-Hermes agent always has\nin context are AGENTS.md (and CLAUDE.md for Claude). SOUL.md \u002F MEMORY.md \u002F USER.md\nare never read by Pi, and skills are name-only until the agent chooses to load one —\nso a rule living only in a SOUL trait or a skill's body reaches NO coding agent. Put\nbehaviour rules for Pi in AGENTS.md\u002FCLAUDE.md (a short \"Core Operating Rules\" block is\nthe pattern), and make them bind by putting the discipline into the ritual-gate loop.\n\nHarness index: `ops\u002Finstall\u002Fharnesses\u002FINDEX.md` · Adding another harness:\n`registry.yaml` + `generate-harnesses.py` · Runbook:\n`docs\u002Frunbooks\u002Fcontext-integration.md`.\n\n## Cortex-gateway — answer a Telegram bot with pi (the `command` backend)\n\nThe standalone `fleet-gateway` (a systemd\u002Flaunchd unit, decoupled from\n`hermes-gateway.service`) serves a Telegram bot with pi as a `kind: command`\nbackend. `pi` itself needs no new adapter — it is DECLARED, not coded:\n\n- **Config\u002Fexample:** `ops\u002Fscripts\u002Fgateway-pi.example.yaml` → copy to\n  `~\u002F.steadfaste-fleet\u002Fgateway.yaml` (OUTSIDE the repo). `command` is an ARGV LIST,\n  so use the ABSOLUTE pi launcher path (`\u002Fhome\u002F\u003Cuser>\u002F.local\u002Fbin\u002Fpi` etc.) — a\n  relative or `~`-containing path is a per-message silent no-op. Use\n  `output: raw` (pi's stdout is exactly the answer), `session: per_chat` with\n  `FLEET_SESSION_KEY={session_id}`, and a `timeout_s` that covers a real coding\n  turn (300s+), not a chat reply. Slash commands (`\u002Fcompact,` `\u002Fmodel` …) are the\n  GATEWAY's to handle via pi RPC (`fleet_gateway\u002Fpi_control.py`), never forwarded\n  as prompts.\n- **A second Telegram bot must use a DISTINCT token var — never\n  `TELEGRAM_BOT_TOKEN`.** `fleet-gateway.service` runs\n  `guard_distinct_token.py` as `ExecStartPre`, which REFUSES to start when\n  `gateway.yaml`'s `bots[].token_ref` is the live bot's var\u002Fname — two pollers on\n  one bot token get a Telegram **409 Conflict** and the casualty is the LIVE\n  channel. Give the pi bot its own env token (e.g. `MOSESPI_BOT_TOKEN`=\n  `PI_BOT_TOKEN`) and reference that; `guard_distinct_token.py` confirms it is\n  distinct (prints the value's hash, never the value) before the unit starts.\n- **The sender allowlist IS the security perimeter** — a bot answered by pi can\n  execute bash, so set `TELEGRAM_ALLOWED_USERS` (and `TELEGRAM_HOME_CHANNEL`) to\n  the operator's chat id ONLY; likewise `GATEWAY_SECRET` (HMAC signing key) is\n  mandatory — the daemon refuses to start without it, because an empty key makes\n  every bus signature forgeable. The bot+config are assembled per host: env vars\n  into the canonical fleet env (`~\u002Fsteadfaste-fleet\u002F.env`), `gateway.yaml` from the\n  example, then `enable --now` the unit. Full reference: `docs\u002Ftemplates\u002F\n  fleet-gateway.service` + `docs\u002Fdesign\u002Ffleet-gateway.md` (CR5 pi = the record,\n  live on the second-bot `@Esther0001Bot`).\n- **`TELEGRAM_API_BASE` is required and fails CLOSED — an `active` unit is not a\n  WORKING gateway.** The transport resolves the API base at call time and refuses\n  to build a URL without it (`TELEGRAM_API_BASE is not set — refusing to build a\n  Telegram API URL`), so the unit starts, reports `active`, and then backs off on\n  every poll. Set it in the fleet env (`TELEGRAM_API_BASE=https:\u002F\u002Fapi.telegram.org`\n  for the standard API) — Hermes's own gateway supplies this internally, so a\n  migration surfaces it as a NEW requirement. Verify a working gateway from the\n  JOURNAL, not `systemctl is-active`: `journalctl --user -u fleet-gateway.service`\n  must show a real dispatched turn and no recurring `poll error … backing off`.\n  Likewise a pi turn that exits non-zero with `No API key found for openrouter` is\n  the provider key missing, not the gateway — wire `auth.json` via the\n  `env-value.sh` `!command` pattern (see \"Configure a provider\" below) and prove it\n  with `pi auth check --provider openrouter` + one real turn before blaming the unit.\n- **The unit must run the FLEET VENV python, not `\u002Fusr\u002Fbin\u002Fpython3`.** The template's\n  default `ExecStart=\u002Fusr\u002Fbin\u002Fpython3 …\u002Fdaemon.py` crash-loops (`Restart=always`\n  spins it) on `ImportError: psycopg package required` the moment the bot-lock layer\n  tries to reach the PGMQ Postgres — the system python has neither psycopg nor the\n  fleet deps. Repoint both `ExecStartPre`\u002F`ExecStart` at\n  `\u003Chost>\u002F.steadfaste-fleet\u002Fvenv\u002Fbin\u002Fpython3`, and make sure `psycopg[binary]` is\n  installed in that venv (the fleet venv historically lacks it — the same gap that\n  keeps `fleet-update.sh` from exiting clean). `pg_isready -h 127.0.0.1 -p \u003Cpg-port>`\n  confirms the bus Postgres is reachable before blaming psycopg. The venv's dashes\n  `mcp`\u002F`jsonschema`\u002F`idna` are present; psycopg is the usual missing one.\n\n## Configure a provider (OpenRouter + a model)\n\nVerified against the installed package docs — `docs\u002Fproviders.md`,\n`docs\u002Fsettings.md`, `docs\u002Fconfiguration.md` — not inferred:\n\n```bash\n# \u003Cagent-dir>\u002Fauth.json   — {\"\u003Cprovider>\": {\"type\": \"api_key\", \"key\": \"... | !command\"}}\n# \u003Cagent-dir>\u002Fsettings.json — {\"defaultProvider\": ..., \"defaultModel\": ...}\n# \u003Cagent-dir>\u002Fmodels.json — custom\u002Fcompatible models and overrides\n```\n\nSet the model defaults (preserve existing keys — `extensions`, `skills`):\n\n```json\n{\"defaultProvider\": \"openrouter\", \"defaultModel\": \"deepseek\u002Fdeepseek-flash-latest\"}\n```\n\n**Mode-specific models (fleet policy):** the coding default is the fast\n`deepseek-flash-latest`; the **adversarial reviewer** uses the strongest tier,\n`deepseek-v4-pro` (`ops\u002Fscripts\u002Fmanage\u002Freviewer-agent-pi.sh`, overridable with\n`REVIEWER_PI_MODEL`). Every coding agent can override per agent in its own\n`gateway.yaml` backend `model:` field, and per chat via `\u002Fmodel`. A reviewer\nshould never silently drop to the cheap\u002Ffast default.\n\n**Do NOT source an env file to supply the key.** Pi's docs support a `!command`\nprecisely so the resolved key is never written to disk, but the obvious command —\n`bash -lc 'set -a; . ~\u002F.hermes\u002F.env; printf %s $OPENROUTER_API_KEY'` — hands the\ncoding agent EVERY secret in that file, and this skill's own pitfall says the agent\ncan print its own environment. Supply exactly one variable:\n\n```json\n{\"openrouter\": {\"type\": \"api_key\",\n                \"key\": \"!bash ~\u002F.steadfaste-fleet\u002Fscripts\u002Fenv-value.sh OPENROUTER_API_KEY\"}}\n```\n\n`env-value.sh` prints one named value (fleet env first, then the Hermes env, first\nmatch wins), fails closed when absent, and refuses a name that isn't\n`^[A-Z][A-Z0-9_]*$` so it can't become a pattern. Point it at a Hermes-only key and\ncopy that key into the fleet env: no harness should reach into a Hermes-owned file\nfor a provider key.\n\nVerify all three, in this order — the last one is the only real proof:\n\n```bash\npi auth check --provider openrouter          # ready\npi --list-models kimi                        # the model, with context\u002Fthinking capabilities\npi --model \"openrouter\u002F\u003Cvendor>\u002F\u003Cmodel>\" \"Reply with exactly: ready\"   # a real turn\n```\n\n`pi auth check --model \u003Cid>` without the provider qualifier reports `not_ready` even\nwhen the model is fine — check the provider-qualified form.\n\n## Jev integration (the cost-routing hooks)\nThe five high-value Jev hooks in the pi loop, from ten-levels-of-jev and mapped in\nsteadfaste `docs\u002Fdesign\u002Fcoding-cost-routing.md`:\n1. task-routing classifier (before any model is chosen — the biggest saving)\n2. destructive-command gate (before tool execution)\n3. compaction scoring (when context fills — prune lowest-scored instead of a summariser LLM)\n4. cheap file reads (judge a file without reading it into context — $0.00049 vs $0.091)\n5. output-type screening (after an LLM response)\n\n## Web search — pi has NO online tool until a package supplies one\n\nMeasured 2026-10-15 (pi 1.2.0): the built-ins are `read`, `bash`, `powershell`,\n`edit`, `write`, `grep`, `find`, `ls`, plus `codemode`\u002F`tool_search` — and\n`tool_search` ranks the LOCAL tool registry (deferred\u002FMCP tools), never the\nnetwork. The five fleet MCP servers expose no search either. So \"research\nthis\" and \"review this repo\" had no online path at all, and the gateway-served\nagent is no exception: the gateway only spawns this same pi.\n\n- **Install (pinned + age-gated):** `pi install npm:pi-web-access@\u003Cversion>`.\n  It registers `web_search`, `source_check`, `fetch_content` and\n  `get_search_content` — search, URL\u002FPDF\u002FYouTube fetching, and GitHub URLs are\n  CLONED locally so the agent reads real files instead of rendered HTML.\n  **Free is the requirement, not a nicety** — build the keyless chain first and\n  treat a keyed provider as an opt-in upgrade; never introduce a paid dependency\n  for a capability the fleet already gets for nothing.\n- **Pick the pin by MEASUREMENT, never from the README.** The latest release is\n  usually days old and fails the 14-day package age gate, and the gate is not\n  bypassed for convenience: enumerate the versions, sort them as SEMVER (a\n  lexical sort puts `0.5.1` after `0.41.0` and hands you a six-month-old build),\n  and take the newest one that passes.\n  ```bash\n  python3 -c \"import json,urllib.request,datetime,sys;\\\n  d=json.load(urllib.request.urlopen('https:\u002F\u002Fregistry.npmjs.org\u002Fpi-web-access'));\\\n  now=datetime.datetime.now(datetime.timezone.utc);\\\n  k=lambda v: tuple(int(x) for x in v.split('.') if x.isdigit());\\\n  rows=[(k(v),v,ts,(now-datetime.datetime.fromisoformat(ts.replace('Z','+00:00'))).days) \\\n        for v,ts in d['time'].items() if v not in ('created','modified')];\\\n  rows.sort();\\\n  print([(v,a) for _,v,_,a in rows if a>=14][-3:])\"\n  python3 ops\u002Fscripts\u002Fhealth\u002Fcheck-package-age.py npm pi-web-access==\u003Cchosen>   # rc 0 = allowed\n  ```\n  Then bump later through the same gate — the pinned spec is a variable in\n  `install-pi-integration.sh` (`PI_WEB_SEARCH_PACKAGE=...`), so a bump is one\n  env-overridable value, not an edit scattered through the script.\n- **Prove it with a REAL turn, not `pi list`.** A registered extension and a\n  working search are two different claims: run one turn in a scratch repo and\n  read which PROVIDER answered and the URLs it returned\n  (`04-search-exa.txt` \u002F `05-search-ddg.txt` under `docs\u002Fevidence\u002F` are the\n  captured shape). Run it from the contract's own cwd too when the consumer is a\n  service — the gateway spawns pi from its deploy dir, so a probe that only works\n  in a project directory proves nothing about the gateway-served agent.\n- **Free path, no API key:** Exa's keyless MCP free tier plus DuckDuckGo's\n  keyless HTML endpoint. `~\u002F.pi\u002Fagent\u002Fweb-search.json`:\n  ```json\n  {\"searchRouting\": {\"providers\": [\"exa\", \"duckduckgo\"],\n                     \"fallbackOn\": [\"unsupported\", \"transient\", \"quota\", \"network\", \"invalid-response\"]}}\n  ```\n- **`auto` is NOT the free path.** With no config the tool answers\n  `No search provider available …` and lists only KEYED providers — an agent\n  reads that as a broken tool rather than a missing config. Keyless DuckDuckGo\n  is explicit-only (never chosen by `auto`, never in `provider: \"all\"`), so\n  name it in `searchRouting` instead of relying on the default chain.\n- **`pi install` writes a package declaration, not a working tool.** Pi manages\n  its own npm root (`~\u002F.pi\u002Fagent\u002Fnpm\u002Fnode_modules\u002F\u003Cpkg>`); a declaration with\n  nothing on disk loads no extension. Check both halves — the declaration in\n  `settings.json` AND the directory.\n- **A web tool needs NO governance lock.** `fleet-governance.ts` gates only\n  `write`\u002F`edit` and non-read-only `bash`; every non-native tool (extension or\n  MCP) passes by design, so search\u002Ffetch work in an unlocked session.\n- **Wiring:** `ops\u002Fscripts\u002Finstall\u002Finstall-pi-integration.sh` declares the\n  package, installs it when the directory is absent, and writes\n  `web-search.json` only when no config exists (an operator's keyed file is\n  never clobbered). `ops\u002Fscripts\u002Fmanage\u002Faudit-pi-integration.sh` Layer 6\n  FAILs when either half is missing or the chain has no keyless provider;\n  `tests\u002Ftest_pi_registration_installer.sh` covers it.\n\n## Several pi agents in ONE repo — project-scoped state, and the commit sweep\n\npi keeps USER scope in `~\u002F.pi\u002Fagent`, but for a TRUSTED PROJECT it also writes\n`.pi\u002Fsettings.json` and `.pi\u002Fmcp.json` **inside the checkout**, and the fleet extensions add\nto that (the context extension checkpoints at `turn_end`, so those writes happen every turn).\nHermes keeps all of it in `~\u002F.hermes`, so this hazard does not exist for Hermes agents and\nnobody who has only run Hermes will expect it.\n\nWith more than one pi session in the same repo:\n\n- each session's `.pi\u002F` files appear as untracked files under the other's feet;\n- the first agent to run a broad add (`git add -A`, `git add .`) or `git commit -a` sweeps up\n  files it never wrote — which the operator reports as \"a sweep of the peer's files when the\n  first one tries to commit\", and reasonably blames on governance.\n\nRules:\n\n- **Ignore `.pi\u002F` in every repo pi runs in**, and prove it: `git check-ignore -v\n  .pi\u002Fsettings.json` must name the rule, and `git ls-files .pi` must be empty — a `.pi` path\n  already committed defeats a new ignore and needs `git rm -r --cached .pi`.\n- **Never `git commit -a` on a tree another session may be editing.** Commit by pathspec and\n  assert the staged set first (`git diff --cached --name-only`). No `.gitignore` prevents\n  sweeping a peer's SOURCE edits; only the pathspec does.\n- **When commits on a host keep carrying files nobody wrote, measure what the HARNESS writes\n  into the tree before suspecting the git hooks.** The Hermes hooks stage nothing (no\n  `git add`, `stash`, `checkout --`, `reset`, and no `commit -a` in the commit path), so a\n  sweep on a pi host points at pi's own project state, not at the gate.\n\n## Pitfalls\n- **A presence probe can be wrong about a managed install.** `command -v pi` reports\n  \"missing\" on a host where Pi is installed and working, because the entrypoint is a\n  symlink into a bin dir that need not be on PATH. When a probe says a tool is absent,\n  check the install LAYOUT (launcher, `current-version`, `releases\u002F`) before reporting\n  it missing to anyone — a false \"not installed\" sends the user chasing a non-problem,\n  and the correction costs more than the check did.\n- **Local small models (qwen2.5:3b) are weak at tool-calling** — use offline\u002Flocal\n  for *generation* and let pi do the *loop*; a ROUTINE task that needs tool-chaining\n  routes to a hosted workhorse rather than forcing the local model to tool-call.\n- **A block notice is an instruction, not a control** — an agent was observed\n  routing around a write gate by writing the same file via a bash heredoc. The\n  deterministic gate remains the authority; Jev gates add scrutiny, never remove it.\n- **The agent can read its own environment** — its bash tool can print every env\n  var it was given. Hand pi only shell basics + the Jev\u002Fprovider keys + Jev settings;\n  treat `.sessions\u002F` as sensitive.\n- **Never let the agent author its own Jev question blocks at runtime** (steadfaste\n  MN-3: the question is the policy). The questions are Steward-ratified Decision\n  Class config; the agent reaches for Jev, it does not write the questions.\n- **Fail closed on routing** — an undecidable\u002Funknown\u002Fmissing classification routes\n  pessimistically to the most capable (most expensive) tier, never a silent cheap\n  default.\n- **An optional chain over a guessed API hides the defect** — `event.completed?.()`\n  returned `undefined` against a non-existent method, so every checkpoint was\n  written EMPTY while the code looked defensive. When a hook must produce output,\n  assert the output is non-empty (warn loudly with the observed keys) rather than\n  letting `?.` be the difference between working and silent.\n- **Verify a hook's or tool's EFFECT without an LLM run.** A host with no provider\n  ready cannot run a turn, so don't wait on one to test wiring: load the extension\n  with **pi's OWN TypeScript loader** (it ships jiti in its release `node_modules`),\n  call its default export with a fake `pi` (`{ on, registerTool }`) that captures the\n  handlers\u002Ftools, fire a synthetic event in Pi's real shape, and assert the effect\n  landed (a store row exists) — a stderr marker alone proves only that the handler ran.\n- **A guard that greps cannot see a signature or a schema shape — EXECUTE the wiring.**\n  Guards asserting that tool NAMES exist and that the shared CLI is called all passed\n  while every tool was dead, because the defect was the tool definition's SHAPE. Load\n  the real extension, hand it a stub `pi`, and CALL `execute(id, params)` against a\n  throwaway CLI — never the real store. Then prove the guard discriminates: run it\n  against the PRE-FIX extension and require it to FAIL\n  (`TypeError: \u003Ctool>.execute is not a function`). A guard that has never failed on the\n  broken artifact is a happy path, not a guard. Recipe and exact shapes:\n  `references\u002Fextension-tool-api.md`.\n- **`ToolResultEventBase` carries `input`\u002F`content`\u002F`isError` but NOT `toolName`** —\n  only the concrete variants (`BashToolResultEvent`, …) declare it. Read `toolName`\n  defensively in a generic `tool_result` handler.\n- **Never put `*\u002F` inside a block comment — a GLOB will close it early.** Writing an\n  identifier like `mem_*\u002Fsession_*` (or any `foo_*\u002Fbar`) in a `\u002F** … *\u002F` header ends\n  the comment at the `*\u002F`, so the rest parses as code and the extension fails to LOAD\n  (`ParseError: Missing semicolon`, or `SyntaxError: Unexpected token '*'`). Pi then\n  reports the tools as missing, which reads like a wiring problem rather than a typo.\n  Write `memory\u002Fsession`, or space it (`mem_* \u002F session_*`). The same trap applies to\n  any glob you paste into a JSDoc\u002FTSDoc comment.\n- **`python3` may not be on pi's PATH on macOS** — Homebrew is `\u002Fopt\u002Fhomebrew\u002Fbin`\n  (Apple Silicon) or `\u002Fusr\u002Flocal\u002Fbin` (Intel), and a GUI-launched pi sees a narrower\n  PATH than your shell. Make the interpreter overridable (e.g.\n  `FLEET_CONTEXT_PYTHON`) instead of hardcoding `python3`.\n- **An MCP entry's interpreter needs its TLS dependencies, not just the module you probed.**\n  `python-with-module.sh --print mcp` proves `mcp` imports and says nothing about the CA bundle the\n  server's HTTP client needs, so an entry can resolve clean and still start DEAD on TLS. The\n  `Could not find a suitable TLS CA certificate bundle` message is raised byte-identically by both\n  `requests` and `httpx`, so it names no library — and never justify KEEPING a package with \"pip\n  would break\": pip vendors its own certifi\u002Frequests\u002Furllib3\u002Ftruststore and is unaffected. An\n  interpreter resolution, the import-chain rule for deciding a dependency is load-bearing, and the\n  old-venv-path failure after a home-dir migration: `references\u002Fmcp-server-interpreter-tls.md`.\n",{"name":5,"version":24,"description":7},"1.0.0","main","9dc0e92c5fa81d4db5292b205716e8ea0c00d10e","skills\u002Fautonomous-ai-agents\u002Fpi-coding-agent",1,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet","steadfaste.com","https:\u002F\u002Fgithub.com\u002Flukemcqueen","AI Architect | Building Hermes Cortex: governed multi-agent AI for autonomous software engineering | Enterprise Tech Consultant","2026-11-14 22:33:34",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pi-coding-agent",{"tool":40,"command":41},"bunx","bunx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pi-coding-agent",{"tool":43,"command":44},"pnpm","pnpm dlx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pi-coding-agent","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fautonomous-ai-agents\u002Fpi-coding-agent\u002FSKILL.md",true,[48,54,58],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fextension-tool-api.md","REFERENCE","参考文档",4333,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fautonomous-ai-agents\u002Fpi-coding-agent\u002Freferences\u002Fextension-tool-api.md",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fmcp-server-interpreter-tls.md",5221,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fautonomous-ai-agents\u002Fpi-coding-agent\u002Freferences\u002Fmcp-server-interpreter-tls.md",{"path":59,"resourceType":60,"resourceTypeDesc":61,"sizeBytes":62,"sourceHtmlUrl":63},"scripts\u002Fpi-skills-diagnostics.mjs","SCRIPT","脚本",3574,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fautonomous-ai-agents\u002Fpi-coding-agent\u002Fscripts\u002Fpi-skills-diagnostics.mjs",[65,73,80,87,94,101],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":72},"01M7DXY4G8NSVB59K8B6S2AQNP","macbook-linux-maintenance","Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fmacbook-linux-maintenance\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":72},"01M7DXXYJCXFJ3TGB84ZQ8KFE6","governance-regression-triage","Triage a host's governance issues: what changed.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fgovernance-regression-triage\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":72},"01M7DXXSAP1G8FDRJAMXQGBBMK","enforcement-immutability","Use when enforcement files lose their immutable flag.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fenforcement-immutability\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":72},"01M78SSDQVRYX64Y16X32TC0NS","steadfaste-fleet-repo-deploy","Use when committing to the steadfaste-fleet repo.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-repo-deploy\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":72},"01M78SS928F3R2RJAYVW4E30CE","steadfaste-fleet-maintenance","Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-maintenance\u002FSKILL.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":72},"01M78SP1CHW0T0BWE5ZT6JBPX8","fleet-preflight","DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its \"Repo-Specific Pre-Flight\" section covers git search, Hermes boundary, and deployment verification.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Ffleet-preflight\u002FSKILL.md",[],[]]