live: heartbeat sync 2026-10-19T14:21:41-07:00 (Refs #11)

agent/managed-skills/omp-extension-event-probe/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: omp-extension-event-probe
+description: "Prove which lifecycle events the omp harness actually dispatches to extensions, with a throwaway timestamping probe plugin, instead of inferring delivery from side effects."
+---
+
+# Prove harness→extension event delivery with a probe plugin
+
+Use when an extension handler seems never to fire, or when you must know *when* an
+event arrives relative to another (mid-run vs settle). Never infer dispatch from
+the feature's side effects: async work in the handler (LLM rewrites, synthesis,
+network) lags seconds and destroys the timing signal.
+
+## Shape (no build step needed)
+
+`/tmp/probe/package.json` — the installer validates the declared entry on disk:
+
+```json
+{
+  "name": "event-probe",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": "./index.js",
+  "pi": { "extensions": ["./index.js"] }
+}
+```
+
+`/tmp/probe/index.js` — append arrival times, not counts:
+
+```js
+import { appendFileSync } from "node:fs";
+const LOG = "/tmp/probe.log";
+const stamp = (line) => appendFileSync(LOG, `${new Date().toISOString().slice(11, 23)} ${line}\n`);
+export default function probe(pi) {
+  pi.on("agent_start", () => stamp("agent_start"));
+  pi.on("turn_end", (e) => stamp(`turn_end turn=${e.turnIndex} toolResults=${(e.toolResults ?? []).length}`));
+  pi.on("agent_end", (e) => stamp(`agent_end messages=${(e.messages ?? []).length} willContinue=${String(e.willContinue)}`));
+}
+```
+
+## Run
+
+1. `cd ~/.omp/plugins && omp plugin link /tmp/probe` (link, never edit
+   `node_modules`), then `omp plugin doctor` → expect a `✔ plugin:event-probe` line.
+2. Launch a **fresh** TUI session in a pty (`omp --cwd /tmp/probe-run`, `pty: true`).
+   Extensions load at startup only — an already-running session never sees the probe.
+3. PTY gotcha: input sent before the splash clears is swallowed. Read the screen
+   first, then submit text and finish with a separate write containing a bare
+   `\r` (LF alone left the text sitting in the composer).
+4. Drive a task with ≥2 tool rounds so turns and settles separate in time
+   (sequential reads work and need no approval; ask for steps "strictly one
+   after the other" or the model parallelises them into one turn).
+5. Wait for a terminal line with an async bounded loop (`grep -q agent_end`,
+   `sleep 1` inside one backgrounded bash call) — never poll across turns.
+
+## Read
+
+`turn_end` timestamps strictly earlier than `agent_end` ⇒ per-turn delivery
+works. `willContinue=true` on `agent_end` marks a non-terminal settle (harness
+maps `isTerminal === false` to it) — handlers that `return` on it never speak.
+
+## Teardown (mandatory)
+
+`omp plugin uninstall event-probe`; `omp plugin doctor`; delete `/tmp/probe*`.
+The link writes into `~/.omp/plugins/package.json` (tracked, live tier) —
+uninstall restores it; confirm with `grep` for the probe name returning nothing.
+
+## Ground truth read for free
+
+Event union + payloads: `~/.omp/plugins/node_modules/@oh-my-pi/pi-coding-agent/dist/types/extensibility/shared-events.d.ts`;
+the session→extension mapping lives in `src/extensibility/extensions/lifecycle-mirror.ts`
+(`extensionEventFromSessionEvent`). Extension-level `turn_end` carries
+`turnIndex`/`message`/`toolResults` but **no `willContinue`** — that field exists
+only on `agent_end`, so "is this the last turn" cannot be decided from `turn_end`.