[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79J7ZPZSHGQKWK0PMDVRQJP":3,"skill-same:01M79J7ZPZSHGQKWK0PMDVRQJP":44},{"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":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M79J7ZPZSHGQKWK0PMDVRQJP","pi-native-e2e-dev",null,"Spin up a live local Omnigent server + runner and exercise the native Pi TUI harness (pi-native) end-to-end — launch the real `pi` CLI via `omnigent pi`, drive turns through the web\u002Fbridge, smoke-test, and bug-bash. Load when developing, testing, or debugging the pi-native harness (omnigent\u002Finner\u002Fpi_native_executor.py, pi_native_harness.py, omnigent\u002Fpi_native.py, pi_native_bridge.py, pi_native_credentials.py) or its bridge \u002F extension \u002F auth \u002F model behavior.","McClain-Thiel\u002FOmniSci","McClain-Thiel","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F26270512?v=4","01M79J6KEGVM49NSQMSWABYZTQ","McClain Thiel","01M79J6KFBH6W8J65XXM22M7N0",1,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fpi-native-e2e-dev\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: pi-native-e2e-dev\ndescription: Spin up a live local Omnigent server + runner and exercise the native Pi TUI harness (pi-native) end-to-end — launch the real `pi` CLI via `omnigent pi`, drive turns through the web\u002Fbridge, smoke-test, and bug-bash. Load when developing, testing, or debugging the pi-native harness (omnigent\u002Finner\u002Fpi_native_executor.py, pi_native_harness.py, omnigent\u002Fpi_native.py, pi_native_bridge.py, pi_native_credentials.py) or its bridge \u002F extension \u002F auth \u002F model behavior.\n---\n\n# Pi native harness: end-to-end dev & testing (local server\u002Frunner)\n\nThe `pi-native` harness wraps the **real Pi coding-agent TUI**\n(`@earendil-works\u002Fpi-coding-agent`, the `pi` CLI). Unlike the SDK harnesses\n(cursor \u002F copilot \u002F antigravity), it does **not** run in-process: `omnigent pi`\nensures a host daemon, the daemon spawns a **runner** that launches `pi` inside a\nrunner-owned **tmux** terminal, and your TTY attaches to it. Omnigent's web-UI\nturns are forwarded into that live `pi` process through a **file-inbox bridge** +\na packaged **JS extension** (`pi.sendUserMessage`). This skill is the proven\nrecipe for running it **for real against a live local server + runner** — not\njust the unit tests.\n\n> Like the other harnesses, the runner imports from your **current checkout**, so\n> testing here exercises exactly the code you're on. (CWD\u002Fvenv selects the code,\n> not `PYTHONPATH`.)\n\n## What actually runs where\n\n```\nyour TTY ── (attach \u002F pexpect) ──► omnigent pi (CLI, local)\n                                        │ ensures\n                                        ▼\n                                  host daemon ──► local Omnigent server (AP)\n                                        │ spawns                      ▲\n                                        ▼                             │ HTTP\n                                  runner ── launches ──► pi (TUI, in tmux)\n                                                              │ loads\n                                                              ▼\n                                                 omnigent pi-native extension (JS)\n```\n\nTwo ways a turn reaches Pi — test both:\n\n1. **Type in the TUI** (your attached terminal). Exercises Pi natively; the\n   extension mirrors the transcript back to the server (`POST …\u002Fevents`).\n2. **Web \u002F API message.** Server → runner → **`PiNativeExecutor.run_turn`** →\n   `enqueue_user_message()` writes `inbox\u002F\u003Cordinal>_msg_*.json` → the resident\n   extension polls the inbox → `pi.sendUserMessage(...)`. This is the\n   harness-specific path most worth covering.\n\n## Prerequisites (check these first)\n\n1. **You're on the branch you want to test**, and running from that checkout\n   (`.venv\u002Fbin\u002Fomnigent` \u002F `.venv\u002Fbin\u002Fpython` from this repo).\n2. **The `pi` CLI is on PATH** — the harness can't launch without it:\n   ```bash\n   which pi && pi --version\n   # install if missing:  npm install -g @earendil-works\u002Fpi-coding-agent\n   # or point at an explicit binary:  export OMNIGENT_PI_PATH=\u002Fpath\u002Fto\u002Fpi\n   .venv\u002Fbin\u002Fpython -c \"from omnigent.onboarding.harness_readiness import harness_is_configured; print('pi-native ready:', harness_is_configured('pi-native'))\"\n   ```\n3. **`tmux` is on PATH.** The native wrapper attaches your TTY to the\n   runner-owned Pi tmux pane (`_preflight_local_tools` hard-fails without it).\n4. **`node` is on PATH.** The extension is JS executed inside Pi (also required\n   by the e2e extension tests). `node --version`.\n5. **Auth is resolvable (booleans\u002Fids only — never print keys).** Native Pi\n   normally logs in from its own `~\u002F.pi\u002Fagent`. Omnigent bridges the provider you\n   set with `omnigent setup` instead, writing a managed per-session `models.json`\n   and passing `--provider omnigent --model \u003Cresolved>`. Verify what it will use:\n   ```bash\n   .venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native_credentials import resolve_pi_native_provider as r; p=r(); print('provider:', getattr(p,'provider_id',None), '| api:', getattr(p,'api',None), '| model:', getattr(p,'model',None))\"\n   ```\n   `None` → no omnigent provider configured; Pi falls back to its own `\u002Flogin`\n   (run `omnigent setup`, or log into `pi` directly). A Databricks default\n   resolves to the AI-Gateway `anthropic-messages` surface with a refreshed\n   bearer token.\n6. **Network egress to the model backend.** A turn that hangs\u002Ffails to connect on\n   a locked-down host is usually egress, not a harness bug.\n\n## Step 1 — start a local server (real server + runner)\n\n```bash\ncd \u002Fpath\u002Fto\u002Fomnigent\n.venv\u002Fbin\u002Fomni server start          # detached managed server on a free loopback port\n.venv\u002Fbin\u002Fomni server status         # prints the URL, e.g. http:\u002F\u002F127.0.0.1:6767\nSERVER=http:\u002F\u002F127.0.0.1:6767         # use the printed URL below\ncurl -s \"$SERVER\u002Fhealth\"             # {\"status\":\"ok\"}\n```\n\n(`omnigent pi --server \"\"` also auto-spawns a persistent local server and uses\nit — handy for a one-shot manual run, but a known `$SERVER` URL is better for\nscripted API observation below.)\n\n## Step 2 — launch the native Pi terminal against the local server\n\n`omnigent pi` **attaches an interactive TUI**, so run it where you can hold it\nopen. Two patterns:\n\n**A. Background terminal (recommended for scripted drives).** Launch it in one\nterminal and drive\u002Fobserve from another:\n\n```bash\n.venv\u002Fbin\u002Fomnigent pi --server \"$SERVER\" 2>&1   # attaches the Pi TUI; leave it running\n```\n\nIt prints `Web UI: \u003Curl>` and a resume hint to stderr — grab the conversation id\n(the `…\u002Fc\u002F\u003Cconv_…>` segment). Capture it for the API calls below:\n\n```bash\nCONV=conv_xxxxxxxx   # from the \"Web UI:\" line \u002F resume hint\n```\n\n**B. PTY driver (fully automated).** Drive it under `pexpect` exactly like the\n`claude-native-e2e-test` skill's `cuj_driver.py` (a proven, generalizable base):\nspawn `omnigent pi --server \u003Curl>` in a PTY with `cwd=\u003Ccheckout>`, capture the\nconv id from the printed URL, send keystrokes \u002F poll the API, then **tear down\nthe whole process tree** (see Teardown — pexpect Ctrl-C only *detaches* tmux).\n\nPass-through Pi CLI args go after the command (persisted as\n`terminal_launch_args`), e.g. `omnigent pi --server \"$SERVER\" -- --model \u003Cid>`;\nomnigent still injects `--provider omnigent --model \u003Cresolved>` when a provider\nis configured (see `pi_native_credentials.py`).\n\n## Step 3 — drive a turn (and smoke-test)\n\n**Via the web\u002Fbridge path (exercises `PiNativeExecutor`).** Post a user message\nto the running session; the runner routes it through the harness → bridge inbox →\nextension → `pi.sendUserMessage`:\n\n```bash\ncurl -s -X POST \"$SERVER\u002Fv1\u002Fsessions\u002F$CONV\u002Fevents\" \\\n  -H 'content-type: application\u002Fjson' \\\n  -d '{\"type\":\"message\",\"data\":{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply with exactly the single word: PONG\"}]}}'\n```\n\nThen **observe** the mirrored transcript (the extension forwards Pi's output back\nvia `POST …\u002Fevents`):\n\n```bash\nsleep 20\ncurl -s \"$SERVER\u002Fv1\u002Fsessions\u002F$CONV\u002Fitems\" | python -m json.tool | tail -40\n```\n\nA healthy run shows your `user` message **and** a non-empty `assistant` reply\n(`PONG`) mirrored into the session — proving the full stack: server → runner →\nharness → inbox → extension → Pi → transcript forwarder. You'll also see Pi\nrender the message in the attached TUI.\n\n- **Type-driven smoke:** instead of the POST, type a prompt directly in the\n  attached TUI and confirm it answers + mirrors to `…\u002Fitems`.\n- **Specific model:** see Step 2 pass-through note; confirm the resolved model in\n  the Prereq-5 probe.\n\n## Inspect the bridge (debugging)\n\nEverything the harness writes for a session lives under a hashed bridge dir:\n\n```bash\n.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\"\n# ~\u002F.omnigent\u002Fpi-native\u002F\u003Csha256(conv)[:32]>\u002F\n#   inbox\u002F                 \u003C- *.json user_message \u002F interrupt payloads (poller drains + deletes)\n#   sessions\u002F              \u003C- pi --session-dir state\n#   config.json            \u003C- sessionId, serverUrl, inboxDir, authHeaders (extension config)\n#   omnigent_pi_native_extension.js\nls -la \"$(.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\")\u002Finbox\"\n```\n\nIf a queued message never reaches Pi, watch whether `inbox\u002F*.json` drains. The\nmanaged Pi config dir (`PI_CODING_AGENT_DIR`) holds the generated `models.json`\nthat wires Pi's provider\u002Fmodel. Key env vars: `HARNESS_PI_NATIVE_BRIDGE_DIR`,\n`HARNESS_PI_NATIVE_REQUEST_SESSION_ID`, `OMNIGENT_PI_NATIVE_CONFIG`,\n`OMNIGENT_PI_PATH` (legacy `HARNESS_PI_PATH`), `PI_CODING_AGENT_DIR`.\n\n## Targeted scenarios\n\n| Goal | How |\n|------|-----|\n| Web→Pi delivery | POST a message (Step 3); confirm a fresh `inbox\u002F*.json` appears then drains and the reply mirrors to `…\u002Fitems` |\n| Native tools (shell\u002Fedit\u002Fread) | prompt Pi to create→read→edit a file and run a shell command; confirm it touches disk |\n| Resume | stop the TUI, `omnigent pi --server \"$SERVER\" --resume \"$CONV\"` — reattaches; `--resume` (no value) opens the pi-native picker |\n| Interrupt | mid-turn, enqueue an interrupt (`pi_native_bridge.enqueue_interrupt(bridge_dir)`) or use the UI stop; confirm Pi's `abort()` fires and the next turn isn't poisoned (see `test_pi_native_interrupt_replay_e2e.py`) |\n| Policy \u002F guardrail | add a guardrail that denies a keyword; native Pi tool calls are gated by the extension POSTing `…\u002Fpolicies\u002Fevaluate` (not the turn-scoped evaluator) — confirm a DENY blocks |\n| Model routing | flip the configured provider\u002Fmodel; re-check the Prereq-5 probe and that the answer still lands |\n| Concurrency \u002F leaks | drive several sessions; then sweep for orphaned `pi` \u002F runner \u002F tmux (see Cleanup) |\n\n## Gotchas (these cost real time)\n\n1. **It's a TUI, not `omni run`.** Use `omnigent pi`. There is no\n   `omni run \u003Cbundle>` path for pi-native; the executor only enqueues into the\n   bridge — Pi must be alive (attached) for a turn to be processed.\n2. **`config.yaml`'s `server:` defaults to a remote server.** Always pass\n   `--server \"$SERVER\"` (or `--server \"\"` to auto-spawn local). If a *local*\n   server rejects `pi-native`, it's running stale code — restart it from your\n   checkout (allowlist: `omnigent\u002Fspec\u002F_omnigent_compat.py`).\n3. **No live LLM without auth.** If the Prereq-5 probe prints `None` and `pi`\n   isn't logged in, turns won't get a real answer. Configure a provider via\n   `omnigent setup` or `pi` `\u002Flogin`.\n4. **tmux must be reachable from the CLI process.** Direct tmux attach needs the\n   runner-owned socket visible locally; a missing socket\u002F`tmux` fails the attach.\n5. **Turns take ~20–90s** — wrap scripted waits\u002F`timeout` generously.\n6. **Never print\u002Fecho provider keys or gateway tokens.** Use the boolean\u002Fid\n   probes above.\n\n## Code & tests\n\n- **Executor (bridge enqueue):** `omnigent\u002Finner\u002Fpi_native_executor.py`\n- **Harness wrap (`harness: pi-native`):** `omnigent\u002Finner\u002Fpi_native_harness.py`\n- **CLI launch \u002F daemon-runner \u002F tmux attach:** `omnigent\u002Fpi_native.py`\n  (`run_pi_native`); CLI command `pi(...)` in `omnigent\u002Fcli.py`\n- **Bridge (inbox, extension\u002Fconfig writers):** `omnigent\u002Fpi_native_bridge.py`\n- **Auth\u002Fmodel → Pi `models.json`:** `omnigent\u002Fpi_native_credentials.py`\n- **Extension (JS, polls inbox, posts events\u002Fpolicies):**\n  `omnigent\u002Fresources\u002Fpi_native\u002Fomnigent_pi_native_extension.js`\n- **Readiness gate:** `omnigent\u002Fonboarding\u002Fharness_readiness.py`\n\n```bash\n.venv\u002Fbin\u002Fpython -m pytest \\\n  tests\u002Ftest_pi_native_bridge.py \\\n  tests\u002Ftest_pi_native_credentials.py \\\n  tests\u002Ftest_pi_native_extension.py \\\n  tests\u002Ftest_pi_native_interrupt_replay_e2e.py -q   # interrupt e2e needs `node`\n# JS unit tests: node omnigent\u002Fresources\u002Fpi_native\u002Fomnigent_pi_native_extension.test.js\n```\n\n## Bug-bash (fan out)\n\nStress the harness with several scenario probes against the same `$SERVER`: the\nweb→inbox→extension delivery path (lost messages \u002F inbox that won't drain),\ninterrupt replay semantics, native-tool policy gating, transcript-forwarder\nfidelity (does every assistant block reach `…\u002Fitems`?), resume\u002Freattach, and\norphaned `pi`\u002Frunner\u002Ftmux after teardown. Cross-check the API — a start failure\ncan leave the TUI empty while the session records an error.\n\n## Watch-outs from the code (verify live — not a live-bug-bash log)\n\n- **Empty inbox = no turn.** `PiNativeExecutor` yields `TurnComplete` once the\n  message is *queued*, not once Pi *answers*; the actual answer is async via the\n  extension. Judge success by `…\u002Fitems`, not the POST returning `queued: true`.\n- **Native Pi tool calls bypass the turn-scoped evaluator.** They're gated only\n  by the extension's `POST …\u002Fpolicies\u002Fevaluate`; if the extension's `config.json`\n  lacks `serverUrl`\u002F`authHeaders`, gating silently no-ops.\n- **History on a rebuilt session** depends on Pi's own `--session-dir` state under\n  the bridge dir, not on Omnigent re-injecting transcript.\n\n## Teardown — non-negotiable\n\nA pexpect Ctrl-C **detaches** from tmux; the runner, the tmux server, and `pi`\nkeep running. Tear down the process tree from the child PID\n(`ps --ppid …` → SIGTERM\u002FSIGKILL) and separately `tmux -S \u003Csock> kill-server`\n(the tmux server reparents to init). Then verify nothing lingers:\n\n```bash\n.venv\u002Fbin\u002Fomni server stop                 # stop the managed server + local daemon\npgrep -af \"(^|\u002F)pi( |$)|harnesses\\._runner|runner\\._entry|tmux\"   # confirm no orphans\n# remove a session's bridge dir if you want a clean slate:\n# rm -rf \"$(.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\")\"\n```\n\n## Honesty\n\nIf you can't reach a ready Pi TUI (missing `pi`, no `tmux`\u002F`node`, no auth,\nheadless limits), say so — don't claim a turn passed. The strongest evidence is\nthe round trip observed over the API: your `user` message **and** a non-empty\n`assistant` reply mirrored into `GET \u002Fv1\u002Fsessions\u002F$CONV\u002Fitems`.\n","# Pi native harness: end-to-end dev & testing (local server\u002Frunner)\n\nThe `pi-native` harness wraps the **real Pi coding-agent TUI**\n(`@earendil-works\u002Fpi-coding-agent`, the `pi` CLI). Unlike the SDK harnesses\n(cursor \u002F copilot \u002F antigravity), it does **not** run in-process: `omnigent pi`\nensures a host daemon, the daemon spawns a **runner** that launches `pi` inside a\nrunner-owned **tmux** terminal, and your TTY attaches to it. Omnigent's web-UI\nturns are forwarded into that live `pi` process through a **file-inbox bridge** +\na packaged **JS extension** (`pi.sendUserMessage`). This skill is the proven\nrecipe for running it **for real against a live local server + runner** — not\njust the unit tests.\n\n> Like the other harnesses, the runner imports from your **current checkout**, so\n> testing here exercises exactly the code you're on. (CWD\u002Fvenv selects the code,\n> not `PYTHONPATH`.)\n\n## What actually runs where\n\n```\nyour TTY ── (attach \u002F pexpect) ──► omnigent pi (CLI, local)\n                                        │ ensures\n                                        ▼\n                                  host daemon ──► local Omnigent server (AP)\n                                        │ spawns                      ▲\n                                        ▼                             │ HTTP\n                                  runner ── launches ──► pi (TUI, in tmux)\n                                                              │ loads\n                                                              ▼\n                                                 omnigent pi-native extension (JS)\n```\n\nTwo ways a turn reaches Pi — test both:\n\n1. **Type in the TUI** (your attached terminal). Exercises Pi natively; the\n   extension mirrors the transcript back to the server (`POST …\u002Fevents`).\n2. **Web \u002F API message.** Server → runner → **`PiNativeExecutor.run_turn`** →\n   `enqueue_user_message()` writes `inbox\u002F\u003Cordinal>_msg_*.json` → the resident\n   extension polls the inbox → `pi.sendUserMessage(...)`. This is the\n   harness-specific path most worth covering.\n\n## Prerequisites (check these first)\n\n1. **You're on the branch you want to test**, and running from that checkout\n   (`.venv\u002Fbin\u002Fomnigent` \u002F `.venv\u002Fbin\u002Fpython` from this repo).\n2. **The `pi` CLI is on PATH** — the harness can't launch without it:\n   ```bash\n   which pi && pi --version\n   # install if missing:  npm install -g @earendil-works\u002Fpi-coding-agent\n   # or point at an explicit binary:  export OMNIGENT_PI_PATH=\u002Fpath\u002Fto\u002Fpi\n   .venv\u002Fbin\u002Fpython -c \"from omnigent.onboarding.harness_readiness import harness_is_configured; print('pi-native ready:', harness_is_configured('pi-native'))\"\n   ```\n3. **`tmux` is on PATH.** The native wrapper attaches your TTY to the\n   runner-owned Pi tmux pane (`_preflight_local_tools` hard-fails without it).\n4. **`node` is on PATH.** The extension is JS executed inside Pi (also required\n   by the e2e extension tests). `node --version`.\n5. **Auth is resolvable (booleans\u002Fids only — never print keys).** Native Pi\n   normally logs in from its own `~\u002F.pi\u002Fagent`. Omnigent bridges the provider you\n   set with `omnigent setup` instead, writing a managed per-session `models.json`\n   and passing `--provider omnigent --model \u003Cresolved>`. Verify what it will use:\n   ```bash\n   .venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native_credentials import resolve_pi_native_provider as r; p=r(); print('provider:', getattr(p,'provider_id',None), '| api:', getattr(p,'api',None), '| model:', getattr(p,'model',None))\"\n   ```\n   `None` → no omnigent provider configured; Pi falls back to its own `\u002Flogin`\n   (run `omnigent setup`, or log into `pi` directly). A Databricks default\n   resolves to the AI-Gateway `anthropic-messages` surface with a refreshed\n   bearer token.\n6. **Network egress to the model backend.** A turn that hangs\u002Ffails to connect on\n   a locked-down host is usually egress, not a harness bug.\n\n## Step 1 — start a local server (real server + runner)\n\n```bash\ncd \u002Fpath\u002Fto\u002Fomnigent\n.venv\u002Fbin\u002Fomni server start          # detached managed server on a free loopback port\n.venv\u002Fbin\u002Fomni server status         # prints the URL, e.g. http:\u002F\u002F127.0.0.1:6767\nSERVER=http:\u002F\u002F127.0.0.1:6767         # use the printed URL below\ncurl -s \"$SERVER\u002Fhealth\"             # {\"status\":\"ok\"}\n```\n\n(`omnigent pi --server \"\"` also auto-spawns a persistent local server and uses\nit — handy for a one-shot manual run, but a known `$SERVER` URL is better for\nscripted API observation below.)\n\n## Step 2 — launch the native Pi terminal against the local server\n\n`omnigent pi` **attaches an interactive TUI**, so run it where you can hold it\nopen. Two patterns:\n\n**A. Background terminal (recommended for scripted drives).** Launch it in one\nterminal and drive\u002Fobserve from another:\n\n```bash\n.venv\u002Fbin\u002Fomnigent pi --server \"$SERVER\" 2>&1   # attaches the Pi TUI; leave it running\n```\n\nIt prints `Web UI: \u003Curl>` and a resume hint to stderr — grab the conversation id\n(the `…\u002Fc\u002F\u003Cconv_…>` segment). Capture it for the API calls below:\n\n```bash\nCONV=conv_xxxxxxxx   # from the \"Web UI:\" line \u002F resume hint\n```\n\n**B. PTY driver (fully automated).** Drive it under `pexpect` exactly like the\n`claude-native-e2e-test` skill's `cuj_driver.py` (a proven, generalizable base):\nspawn `omnigent pi --server \u003Curl>` in a PTY with `cwd=\u003Ccheckout>`, capture the\nconv id from the printed URL, send keystrokes \u002F poll the API, then **tear down\nthe whole process tree** (see Teardown — pexpect Ctrl-C only *detaches* tmux).\n\nPass-through Pi CLI args go after the command (persisted as\n`terminal_launch_args`), e.g. `omnigent pi --server \"$SERVER\" -- --model \u003Cid>`;\nomnigent still injects `--provider omnigent --model \u003Cresolved>` when a provider\nis configured (see `pi_native_credentials.py`).\n\n## Step 3 — drive a turn (and smoke-test)\n\n**Via the web\u002Fbridge path (exercises `PiNativeExecutor`).** Post a user message\nto the running session; the runner routes it through the harness → bridge inbox →\nextension → `pi.sendUserMessage`:\n\n```bash\ncurl -s -X POST \"$SERVER\u002Fv1\u002Fsessions\u002F$CONV\u002Fevents\" \\\n  -H 'content-type: application\u002Fjson' \\\n  -d '{\"type\":\"message\",\"data\":{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Reply with exactly the single word: PONG\"}]}}'\n```\n\nThen **observe** the mirrored transcript (the extension forwards Pi's output back\nvia `POST …\u002Fevents`):\n\n```bash\nsleep 20\ncurl -s \"$SERVER\u002Fv1\u002Fsessions\u002F$CONV\u002Fitems\" | python -m json.tool | tail -40\n```\n\nA healthy run shows your `user` message **and** a non-empty `assistant` reply\n(`PONG`) mirrored into the session — proving the full stack: server → runner →\nharness → inbox → extension → Pi → transcript forwarder. You'll also see Pi\nrender the message in the attached TUI.\n\n- **Type-driven smoke:** instead of the POST, type a prompt directly in the\n  attached TUI and confirm it answers + mirrors to `…\u002Fitems`.\n- **Specific model:** see Step 2 pass-through note; confirm the resolved model in\n  the Prereq-5 probe.\n\n## Inspect the bridge (debugging)\n\nEverything the harness writes for a session lives under a hashed bridge dir:\n\n```bash\n.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\"\n# ~\u002F.omnigent\u002Fpi-native\u002F\u003Csha256(conv)[:32]>\u002F\n#   inbox\u002F                 \u003C- *.json user_message \u002F interrupt payloads (poller drains + deletes)\n#   sessions\u002F              \u003C- pi --session-dir state\n#   config.json            \u003C- sessionId, serverUrl, inboxDir, authHeaders (extension config)\n#   omnigent_pi_native_extension.js\nls -la \"$(.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\")\u002Finbox\"\n```\n\nIf a queued message never reaches Pi, watch whether `inbox\u002F*.json` drains. The\nmanaged Pi config dir (`PI_CODING_AGENT_DIR`) holds the generated `models.json`\nthat wires Pi's provider\u002Fmodel. Key env vars: `HARNESS_PI_NATIVE_BRIDGE_DIR`,\n`HARNESS_PI_NATIVE_REQUEST_SESSION_ID`, `OMNIGENT_PI_NATIVE_CONFIG`,\n`OMNIGENT_PI_PATH` (legacy `HARNESS_PI_PATH`), `PI_CODING_AGENT_DIR`.\n\n## Targeted scenarios\n\n| Goal | How |\n|------|-----|\n| Web→Pi delivery | POST a message (Step 3); confirm a fresh `inbox\u002F*.json` appears then drains and the reply mirrors to `…\u002Fitems` |\n| Native tools (shell\u002Fedit\u002Fread) | prompt Pi to create→read→edit a file and run a shell command; confirm it touches disk |\n| Resume | stop the TUI, `omnigent pi --server \"$SERVER\" --resume \"$CONV\"` — reattaches; `--resume` (no value) opens the pi-native picker |\n| Interrupt | mid-turn, enqueue an interrupt (`pi_native_bridge.enqueue_interrupt(bridge_dir)`) or use the UI stop; confirm Pi's `abort()` fires and the next turn isn't poisoned (see `test_pi_native_interrupt_replay_e2e.py`) |\n| Policy \u002F guardrail | add a guardrail that denies a keyword; native Pi tool calls are gated by the extension POSTing `…\u002Fpolicies\u002Fevaluate` (not the turn-scoped evaluator) — confirm a DENY blocks |\n| Model routing | flip the configured provider\u002Fmodel; re-check the Prereq-5 probe and that the answer still lands |\n| Concurrency \u002F leaks | drive several sessions; then sweep for orphaned `pi` \u002F runner \u002F tmux (see Cleanup) |\n\n## Gotchas (these cost real time)\n\n1. **It's a TUI, not `omni run`.** Use `omnigent pi`. There is no\n   `omni run \u003Cbundle>` path for pi-native; the executor only enqueues into the\n   bridge — Pi must be alive (attached) for a turn to be processed.\n2. **`config.yaml`'s `server:` defaults to a remote server.** Always pass\n   `--server \"$SERVER\"` (or `--server \"\"` to auto-spawn local). If a *local*\n   server rejects `pi-native`, it's running stale code — restart it from your\n   checkout (allowlist: `omnigent\u002Fspec\u002F_omnigent_compat.py`).\n3. **No live LLM without auth.** If the Prereq-5 probe prints `None` and `pi`\n   isn't logged in, turns won't get a real answer. Configure a provider via\n   `omnigent setup` or `pi` `\u002Flogin`.\n4. **tmux must be reachable from the CLI process.** Direct tmux attach needs the\n   runner-owned socket visible locally; a missing socket\u002F`tmux` fails the attach.\n5. **Turns take ~20–90s** — wrap scripted waits\u002F`timeout` generously.\n6. **Never print\u002Fecho provider keys or gateway tokens.** Use the boolean\u002Fid\n   probes above.\n\n## Code & tests\n\n- **Executor (bridge enqueue):** `omnigent\u002Finner\u002Fpi_native_executor.py`\n- **Harness wrap (`harness: pi-native`):** `omnigent\u002Finner\u002Fpi_native_harness.py`\n- **CLI launch \u002F daemon-runner \u002F tmux attach:** `omnigent\u002Fpi_native.py`\n  (`run_pi_native`); CLI command `pi(...)` in `omnigent\u002Fcli.py`\n- **Bridge (inbox, extension\u002Fconfig writers):** `omnigent\u002Fpi_native_bridge.py`\n- **Auth\u002Fmodel → Pi `models.json`:** `omnigent\u002Fpi_native_credentials.py`\n- **Extension (JS, polls inbox, posts events\u002Fpolicies):**\n  `omnigent\u002Fresources\u002Fpi_native\u002Fomnigent_pi_native_extension.js`\n- **Readiness gate:** `omnigent\u002Fonboarding\u002Fharness_readiness.py`\n\n```bash\n.venv\u002Fbin\u002Fpython -m pytest \\\n  tests\u002Ftest_pi_native_bridge.py \\\n  tests\u002Ftest_pi_native_credentials.py \\\n  tests\u002Ftest_pi_native_extension.py \\\n  tests\u002Ftest_pi_native_interrupt_replay_e2e.py -q   # interrupt e2e needs `node`\n# JS unit tests: node omnigent\u002Fresources\u002Fpi_native\u002Fomnigent_pi_native_extension.test.js\n```\n\n## Bug-bash (fan out)\n\nStress the harness with several scenario probes against the same `$SERVER`: the\nweb→inbox→extension delivery path (lost messages \u002F inbox that won't drain),\ninterrupt replay semantics, native-tool policy gating, transcript-forwarder\nfidelity (does every assistant block reach `…\u002Fitems`?), resume\u002Freattach, and\norphaned `pi`\u002Frunner\u002Ftmux after teardown. Cross-check the API — a start failure\ncan leave the TUI empty while the session records an error.\n\n## Watch-outs from the code (verify live — not a live-bug-bash log)\n\n- **Empty inbox = no turn.** `PiNativeExecutor` yields `TurnComplete` once the\n  message is *queued*, not once Pi *answers*; the actual answer is async via the\n  extension. Judge success by `…\u002Fitems`, not the POST returning `queued: true`.\n- **Native Pi tool calls bypass the turn-scoped evaluator.** They're gated only\n  by the extension's `POST …\u002Fpolicies\u002Fevaluate`; if the extension's `config.json`\n  lacks `serverUrl`\u002F`authHeaders`, gating silently no-ops.\n- **History on a rebuilt session** depends on Pi's own `--session-dir` state under\n  the bridge dir, not on Omnigent re-injecting transcript.\n\n## Teardown — non-negotiable\n\nA pexpect Ctrl-C **detaches** from tmux; the runner, the tmux server, and `pi`\nkeep running. Tear down the process tree from the child PID\n(`ps --ppid …` → SIGTERM\u002FSIGKILL) and separately `tmux -S \u003Csock> kill-server`\n(the tmux server reparents to init). Then verify nothing lingers:\n\n```bash\n.venv\u002Fbin\u002Fomni server stop                 # stop the managed server + local daemon\npgrep -af \"(^|\u002F)pi( |$)|harnesses\\._runner|runner\\._entry|tmux\"   # confirm no orphans\n# remove a session's bridge dir if you want a clean slate:\n# rm -rf \"$(.venv\u002Fbin\u002Fpython -c \"from omnigent.pi_native import pi_bridge_dir_for_session as d; print(d('$CONV'))\")\"\n```\n\n## Honesty\n\nIf you can't reach a ready Pi TUI (missing `pi`, no `tmux`\u002F`node`, no auth,\nheadless limits), say so — don't claim a turn passed. The strongest evidence is\nthe round trip observed over the API: your `user` message **and** a non-empty\n`assistant` reply mirrored into `GET \u002Fv1\u002Fsessions\u002F$CONV\u002Fitems`.\n",{"name":5,"description":7},"main","922625532f94df5ec745affe5f52a751e296a2e2",".claude\u002Fskills\u002Fpi-native-e2e-dev","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel","2026-07-27 00:07:07",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add McClain-Thiel\u002FOmniSci --skill pi-native-e2e-dev",{"tool":36,"command":37},"bunx","bunx skills add McClain-Thiel\u002FOmniSci --skill pi-native-e2e-dev",{"tool":39,"command":40},"pnpm","pnpm dlx skills add McClain-Thiel\u002FOmniSci --skill pi-native-e2e-dev","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fpi-native-e2e-dev\u002FSKILL.md",true,[],[45,52,59,66,71,76],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":19},"01M79JBP2ZPFXG4NT9M82KX9Q0","deep-research","Research checklist and source-quality guidance for the archer e2e fixture.","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fexamples\u002Farcher\u002Fskills\u002Fdeep-research\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M79JBKPHZ40CQ5TM18JMFPKF","pi-e2e-xyz-greet-c4a8d5","Test greeter — pi skills e2e. The unique suffix c4a8d5 appears in the skill name so a string match in the agent's output proves Pi loaded this skill.","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_none\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M79JBG2WT8JHFR6R88TEQC8N","pi-e2e-xyz-count-d2f6e1","Test counter — pi skills e2e. The unique suffix d2f6e1 appears in the skill name so a string match in the agent's output proves Pi loaded this skill.","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_none\u002Fskills\u002Fpi-e2e-xyz-count-d2f6e1\u002FSKILL.md",[],[],{"skillNo":67,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M79JBC5A6FNJY4Q67K60K1PG","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_list\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[],{"skillNo":72,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M79JB8QHHYX07H6AWQ1BQ0NJ","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_list\u002Fskills\u002Fpi-e2e-xyz-count-d2f6e1\u002FSKILL.md",[],[],{"skillNo":77,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M79JB5SKWW13TENDM5MQWP0T","https:\u002F\u002Fgithub.com\u002FMcClain-Thiel\u002FOmniSci\u002Fblob\u002Fmain\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_all\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[]]