Add external presenter support

README.md

@@ -363,6 +363,7 @@ implementation architecture.
 | `PLANNOTATOR_REMOTE` | `1`/`true` for remote mode, `0`/`false` for local, unset for SSH auto-detection |
 | `PLANNOTATOR_PORT` | Fixed port (default: random locally, `19432` remote) |
 | `PLANNOTATOR_BROWSER` | Custom browser to open plans in |
+| `PLANNOTATOR_PRESENTER` | Executable implementing the one-request JSON presenter protocol; overrides `config.json` and may run outside Herdr |
 | `PLANNOTATOR_AI` | `disabled` to disable Ask AI, Review Agents, and Guided Review; the annotate agent terminal is separate |
 | `PLANNOTATOR_SHARE` | `disabled` to turn off URL sharing |
 | `PLANNOTATOR_SHARE_URL` | Custom base URL for share links (self-hosted portal) |
@@ -378,6 +379,24 @@ All Plannotator data lives in a single directory — `~/.plannotator` by default
 export PLANNOTATOR_DATA_DIR=~/.local/share/plannotator
 ```
 
+Host integrations can persist an external presenter in
+`~/.plannotator/config.json`:
+
+```json
+{
+  "presenter": {
+    "command": "/absolute/path/to/presenter",
+    "when": "herdr"
+  }
+}
+```
+
+The command is executed directly without a shell. `when` defaults to
+`"herdr"`, so the presenter is selected only when `HERDR_ENV=1`; use
+`"always"` to enable it everywhere. An explicitly set
+`PLANNOTATOR_PRESENTER` takes priority, and an empty value disables the
+configured presenter for that invocation.
+
 ---
 
 ## Development

apps/hook/server/annotate-command.test.ts

@@ -61,6 +61,55 @@ async function runCompletion(
 }
 
 describe("completeAnnotateCommand", () => {
+  test("waits for server cleanup before publishing or exiting", async () => {
+    const events: string[] = [];
+    let finishCleanup!: () => void;
+    const cleanupFinished = new Promise<void>((resolve) => {
+      finishCleanup = resolve;
+    });
+    let confirmCleanupStarted!: () => void;
+    const cleanupStarted = new Promise<void>((resolve) => {
+      confirmCleanupStarted = resolve;
+    });
+
+    const completion = completeAnnotateCommand({
+      waitForDecision: async () => {
+        events.push("decision");
+        return { approved: true, feedback: "" };
+      },
+      settleAfterDecision: async () => {
+        events.push("settle");
+      },
+      stopServer: async () => {
+        events.push("stop:start");
+        confirmCleanupStarted();
+        await cleanupFinished;
+        events.push("stop:done");
+      },
+      requireApproval: false,
+      emitLegacyOutcome: () => {
+        events.push("legacy");
+      },
+      exit: (code) => {
+        events.push(`exit:${code}`);
+      },
+    });
+
+    await cleanupStarted;
+    expect(events).toEqual(["decision", "settle", "stop:start"]);
+
+    finishCleanup();
+    await completion;
+    expect(events).toEqual([
+      "decision",
+      "settle",
+      "stop:start",
+      "stop:done",
+      "legacy",
+      "exit:0",
+    ]);
+  });
+
   test("publishes approved feedback to matching stdout and result bytes", async () => {
     const result = await runCompletion(
       {

apps/hook/server/annotate-command.ts

@@ -9,7 +9,7 @@ import {
 export interface CompleteAnnotateCommandOptions {
   waitForDecision: () => Promise<AnnotateOutcome>;
   settleAfterDecision: () => Promise<void>;
-  stopServer: () => void;
+  stopServer: () => void | Promise<void>;
   requireApproval: boolean;
   resultFile?: string;
   writeResultFile?: (
@@ -45,7 +45,7 @@ export async function completeAnnotateCommand({
 }: CompleteAnnotateCommandOptions): Promise<void> {
   const result = await waitForDecision();
   await settleAfterDecision();
-  stopServer();
+  await stopServer();
 
   if (requireApproval || resultFile) {
     const serialized = serializeStrictAnnotateResult(result);