feat(bin): add trusted process-event extension bindings

.agents/skills/process-event-sources/SKILL.md

@@ -38,7 +38,8 @@ bin/fm-captain-hold.sh bind <source-id>
 ```
 
 The runner then passes each captured result to that source's own adapter `answers` command and pipes the keyed answers it prints into the one keyed-answer intake, which owns every rule about what they mean; the keys are captain-held task ids.
-This is generic: any adapter with an `answers` command works, and the runner still wakes you to act on the result.
+This is generic across built-in adapters with an `answers` command, and the runner still wakes you to act on the result.
+External process-event bindings intentionally expose no answer operation and cannot feed the captain-answer intake.
 `captain-hold-lifecycle` owns when a binding is required and what the keys must be.
 
 A configured remote secondmate reply source is armed and handled through `bin/fm-procevent-remote-reply.sh`.
@@ -58,6 +59,10 @@ When in doubt, arm only the condition half as an ordinary check and keep the act
 
 `bin/fm-procevent.sh --help`, `bin/fm-procevent-lavish.sh --help`, `bin/fm-procevent-when.sh --help`, and `bin/fm-procevent-remote-reply.sh --help` own the exact commands and flags.
 
+An explicitly enabled external adapter registers through `bin/fm-procevent.sh register-extension`, never through a package-discovered script or package-supplied argv.
+[`docs/configuration.md`](../../../docs/configuration.md#trusted-external-process-event-adapters-configextensionsd) owns setup and [`docs/extension-bindings.md`](../../../docs/extension-bindings.md) owns the narrow trusted-code and untrusted-evidence boundary.
+Use the owner-matched retirement command registration prints, so an older package generation cannot retire its replacement.
+
 Two rules the commands cannot enforce for you:
 
 - **Never run the source's blocking command yourself in a conversational turn.** That is the problem the runner exists to remove, and for a destructive source it also consumes the result where nothing durable can capture it.
@@ -81,7 +86,7 @@ Two rules the commands cannot enforce for you:
   bin/fm-procevent.sh handled <source-id> <sequence>
   ```
   This call is atomically deduplicated by the exact source and sequence: it prints `handled: <id> <seq>` only the first time and `already-handled: <id> <seq>` on every repeat, so a paired effect gated on that distinction is never authorized twice. Reading the event line or the result file is not handling - only this call durably retires the wake, so call it every time, including on a repeat wake for a sequence you already acted on.
-: Ask the adapter what the result means rather than parsing it yourself - for Lavish, `bin/fm-procevent-lavish.sh classify <result-file>` returns `feedback`, `ended`, `waiting`, `missing`, or `unknown`. A `feedback` result can still be the last one a review ever produces, so never assume another wake is coming just because the state is not `ended`.
+: Ask the adapter what the result means rather than parsing it yourself. `bin/fm-procevent.sh classify <result-file>` routes through the immutable built-in or extension identity captured with that result; for Lavish, its existing direct command returns `feedback`, `ended`, `waiting`, `missing`, or `unknown`. A `feedback` result can still be the last one a review ever produces, so never assume another wake is coming just because the state is not `ended`.
 : A routine no-op an adapter positively identifies never becomes a wake at all - it is recorded as handled and stays silent, so you never see it. For Lavish that is exactly an ended session carrying nothing: a board the captain closed without saying anything. A board close carrying a real answer, and every other result, still wakes you unchanged. Never read the absence of a wake as proof a review is still open; ask the source, not the queue.
 : A Lavish wake whose source id matches `bin/fm-procevent-lavish.sh source-id "$(bin/fm-bearings-board.sh path)"` is a bearings board result; load the `bearings` skill's board-wake handling regardless of which answer kinds the result contains.
 : A `when` wake carries the watch's one terminal captured outcome and may be re-announced until handled: `bin/fm-procevent-when.sh classify <result-file>` returns `fired` (relay the success and its output); `action-failed` (relay the captured error and decide recovery); `condition-error`, `never-true`, or `rejected` (the watch stopped safely without acting - report why and decide whether to re-arm); or `ambiguous` (the action was claimed but its outcome was never captured - verify its effect manually before anything else). Every `when` outcome is terminal and the action is never retried automatically, so after handling and the generic acknowledgement above, run `bin/fm-procevent-when.sh retire <name>` to clean the watch's private records before any re-arm.

README.md

@@ -200,7 +200,8 @@ Firstmate's skills live in two separate places with different audiences:
 ## Documentation
 
 - [docs/architecture.md](docs/architecture.md) - maintainer architecture for the crew, supervision, worktrees, secondmates, and project modes.
-- [docs/configuration.md](docs/configuration.md) - environment variables, `FM_HOME`, runtime backend selection, optional Relay and its X and Discord setup steps, the files you set, and harness support.
+- [docs/configuration.md](docs/configuration.md) - environment variables, `FM_HOME`, runtime backend selection, optional Relay and its X and Discord setup steps, trusted external process-event adapter setup, the files you set, and harness support.
+- [docs/extension-bindings.md](docs/extension-bindings.md) - maintainer architecture for the narrow trusted external `process-event-adapter/1` package, binding, handshake, and evidence boundary.
 - [docs/remote-secondmates.md](docs/remote-secondmates.md) - current setup, routing, transfer, recovery, and safety behavior for whole-home remote second mates.
 - [docs/calm.md](docs/calm.md) - current Pi `/calm` behavior and supported presentation limits.
 - [docs/voice-relay.md](docs/voice-relay.md) - the optional spoken interface: setup on both machines, measured round-trip cost, what a spoken answer may read, and what this build does not do yet.

bin/fm-extension-launch-barrier.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Static core-owned launch barrier for one trusted extension invocation.
+//
+// The host starts this file directly with shell=false in a new process group.
+// The barrier publishes that exact group identity before it accepts a one-shot
+// host release, then starts the already-validated package executable in the
+// same group with inherited bounded protocol pipes. It never evaluates source
+// text and never discovers package code or authority on its own.
+
+import { spawn } from "node:child_process";
+import { open, readFile, rename } from "node:fs/promises";
+import path from "node:path";
+
+const READY_SCHEMA = "firstmate.extension-invocation-ready.v1";
+const OWNER_SCHEMA = "firstmate.extension-invocation-owner.v1";
+const RELEASE_SCHEMA = "firstmate.extension-invocation-release.v1";
+const STARTUP_WAIT_MS = 5000;
+const MAX_CONTROL_BYTES = 16384;
+const POLL_MS = 20;
+
+function die(message) {
+  process.stderr.write(`extension launch barrier: ${message}\n`);
+  process.exit(125);
+}
+
+function exactKeys(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+
+async function readControl(file) {
+  const bytes = await readFile(file);
+  if (bytes.length === 0 || bytes.length > MAX_CONTROL_BYTES) die("control record size is invalid");
+  let value;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    die("control record is invalid JSON");
+  }
+  return value;
+}
+
+async function writeExclusive(file, value) {
+  const temporary = `${file}.tmp`;
+  const handle = await open(temporary, "wx", 0o600).catch(() => die("cannot publish launch readiness"));
+  try {
+    await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, file).catch(() => die("cannot publish launch readiness"));
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const [token, ownerFile, readyFile, releaseFile, hostPidRaw, entrypoint, cwd, verb, ...extra] = process.argv.slice(2);
+  if (extra.length || !ownerFile || !readyFile || !releaseFile || !token || !hostPidRaw || !entrypoint || !cwd || !verb) {
+    die("invalid launch arguments");
+  }
+  if (![ownerFile, readyFile, releaseFile, entrypoint, cwd].every(path.isAbsolute)) die("launch paths must be absolute");
+  if (!/^[0-9]+$/u.test(hostPidRaw)) die("host pid is invalid");
+  const hostPid = Number(hostPidRaw);
+  if (!Number.isSafeInteger(hostPid) || hostPid <= 1) die("host pid is invalid");
+  // The host creates this tracked child with detached=true, making its PID the
+  // invocation PGID before this static file runs. The unguessable token also
+  // remains in the barrier's exact argv so recovery can reject PID reuse.
+  const identity = `barrier-token:${token}`;
+  await writeExclusive(readyFile, {
+    schema: READY_SCHEMA,
+    token,
+    group_pid: process.pid,
+    group_identity: identity,
+  });
+
+  const deadline = Date.now() + STARTUP_WAIT_MS;
+  let release;
+  while (Date.now() < deadline) {
+    if (!pidAlive(hostPid)) process.exit(125);
+    try {
+      release = await readControl(releaseFile);
+      break;
+    } catch (error) {
+      if (error && error.code !== "ENOENT") throw error;
+    }
+    await sleep(POLL_MS);
+  }
+  if (!release) die("host did not release the launch barrier");
+  if (!exactKeys(release, ["schema", "token"]) || release.schema !== RELEASE_SCHEMA || release.token !== token) {
+    die("launch release identity is invalid");
+  }
+  const owner = await readControl(ownerFile);
+  if (!exactKeys(owner, [
+    "schema", "token", "phase", "host_pid", "host_identity", "group_pid", "group_identity",
+    "extension_id", "binding_digest", "request_id", "source_id", "operation",
+  ]) || owner.schema !== OWNER_SCHEMA || owner.token !== token || owner.phase !== "group"
+      || owner.host_pid !== hostPid || owner.group_pid !== process.pid || owner.group_identity !== identity) {
+    die("launch ownership was not published before release");
+  }
+
+  const child = spawn(entrypoint, [verb], {
+    cwd,
+    env: process.env,
+    shell: false,
+    detached: false,
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  const outcome = await new Promise((resolve) => {
+    child.once("error", () => resolve({ code: 125, signal: null }));
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  if (outcome.signal) process.exit(128);
+  process.exit(outcome.code ?? 125);
+}
+
+main().catch((error) => die(error instanceof Error ? error.message : "unexpected launch failure"));