@chorus-aidlc/chorus-openclaw-plugin 0.5.3 → 0.11.0

package/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -295,7 +295,7 @@ The table below shows default tool availability for each preset (no custom permi
 | `chorus_add_comment` / `chorus_get_comments` | (public) | Yes | Yes | Yes |
 | `chorus_update_task` (field edits + status) | (public; assignee required for status) | Yes | Yes | Yes |
 | `chorus_claim_task` / `chorus_release_task` / `chorus_submit_for_verify` / `chorus_report_work` / `chorus_report_criteria_self_check` | `task:write` | Yes | **Yes** (0.7.0+) | Yes |
-| `chorus_claim_idea` / `chorus_release_idea` / `chorus_move_idea` / `chorus_pm_create_idea` / `chorus_pm_*_elaboration` | `idea:write` | No | Yes | Yes |
+| `chorus_claim_idea` / `chorus_release_idea` / `chorus_move_idea` / `chorus_pm_create_idea` / `chorus_edit_idea` / `chorus_pm_*_elaboration` | `idea:write` | No | Yes | Yes |
 | `chorus_pm_create_proposal` / `chorus_pm_*_proposal` / `chorus_pm_*_draft` / `chorus_create_tasks` / `chorus_pm_assign_task` / `chorus_update_task` (dependency edits via `addDependsOn`/`removeDependsOn`) | `proposal:write` | No | Yes | Yes |
 | `chorus_pm_create_document` / `chorus_pm_update_document` / `chorus_create_report` | `document:write` | No | Yes | Yes |
 | `chorus_admin_create_project` / `chorus_admin_*_project_group` / `chorus_admin_move_project_to_group` | `project:write` | No | **Yes** (0.7.0+) | Yes |
@@ -314,18 +314,49 @@ Results are advisory — they do not hard-block approval or verification, but yo
 
 ---
 
-## SSE Event-Driven Model
+## SSE Event-Driven Model (Bidirectional Daemon Host)
 
-The OpenClaw Chorus plugin runs a background service that holds a **Server-Sent Events (SSE)** connection to the Chorus server and wakes the agent (via the plugin's in-process system-event bridge) when relevant events arrive. Instead of polling, the agent is notified the moment something needs its attention.
+The OpenClaw Chorus plugin runs a background service that holds a **Server-Sent Events (SSE)** connection to the Chorus server. It is a **fully bidirectional daemon host**, on a par with the Chorus CLI daemon: it is not just a receiver of notifications that wakes the agent — it also **registers a connection identity, reports its execution lifecycle back to the server, and accepts reverse control commands** (interrupt / resume / deliver an instruction turn) so a human in the Chorus UI can observe and steer an in-flight run. Instead of polling, the agent is notified the moment something needs its attention, and the server always has a live, controllable view of what this host is running.
 
-### How It Works
+### Inbound: notifications wake the agent
 
 1. The plugin connects to the Chorus SSE endpoint using the configured API Key
 2. When a notification event arrives, the plugin fetches the full notification details
 3. If `projectUuids` is configured, events from other projects are filtered out
-4. The plugin routes the event to the agent with context-rich instructions
+4. The plugin resolves the event's lineage and routes it to the agent (an in-process embedded-agent run) with context-rich instructions
 5. If `autoStart` is enabled, certain events (like `task_assigned`) auto-claim before waking the agent
 
+### Connection identity (`connection_registered`)
+
+Right after the SSE handshake, the server assigns this stream a **DaemonConnection** and reports its `connectionUuid` via a `connection_registered` data event. The plugin captures that uuid (refreshing it on every reconnect, so a recycled stream never carries a stale identity) and uses it as the single source of truth for "which connection am I." This identity is what makes the connection addressable: it appears in the Chorus **Agent Connections** UI, scopes the reverse control channel, and stamps every outbound report below.
+
+### Outbound: the daemon reports its lifecycle to the server
+
+While a woken run executes, the plugin reports back over the `/api/daemon/*` REST surface (host-agnostic, the same payload shapes the CLI daemon sends) so the connection's activity is observable in the UI in real time:
+
+| Report | What it conveys |
+|--------|-----------------|
+| **turn-advance** | Advances the wake's turn lifecycle (`running` → `ended`) so the UI knows when a turn starts and finishes |
+| **execution-state** | Publishes this connection's running/queued execution snapshot (entity, root idea, status, start time) — the live "what is this host doing" view |
+| **transcript** | Streams the finalized user/assistant text of the turn (only `{ role, text }` — no internals) so the run's transcript is visible in the UI |
+| **report-interrupt** | Records that a run ended as `interrupted` (reason `user` or `crash`) rather than completing |
+
+Reports are fire-and-forget and never crash the run: a network/non-2xx failure is logged with its cause and surfaced as a structured failure result, never silently swallowed.
+
+### Reverse control channel (interrupt / resume / deliver_turn)
+
+The server publishes control commands on a `control:{connectionUuid}` channel and forwards them as `type:"control"` SSE events. These are **forked away from the wake path** — a control event can never spawn a new agent run for itself. The plugin acts on a command only after a double-check: (1) the command's `targetConnectionUuid` matches this connection's own uuid (a stale/recycled uuid or another connection's command is ignored and logged), and (2) for `interrupt`, this host actually holds a running embedded-agent run for that entity.
+
+| Command | Effect |
+|---------|--------|
+| **interrupt** | Aborts the matching in-flight run (true mid-run stop via its AbortController), then reports `report-interrupt` |
+| **resume** | Re-dispatches the entity's wake to continue the **same** session (the synthetic "resume" wake; resolves lineage so it anchors on the same direct idea) |
+| **deliver_turn** | Runs a human instruction turn delivered into the conversation — precisely the one turn when a `turnUuid` is present (origin-only live delivery), or a full pending-turns sweep as a fallback for an older server |
+
+### Backfill on reconnect
+
+After an SSE gap, the plugin re-pulls (1) unread **notifications** missed during the gap and (2) this connection's unstarted **pending turns** from the turn table (the safety net for a `deliver_turn` ping lost while disconnected). The two sources share a seen-set, so a turn is run **at most once** across live delivery and backfill.
+
 ### Event Types
 
 | Event | Trigger | Agent Action |

package/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -37,10 +37,11 @@ All post-elaboration progress (planning, building, verifying, done) is **derived
 
 | Tool | Purpose |
 |------|---------|
-| `chorus_pm_create_idea` | Create a new idea in a project (on behalf of humans) |
+| `chorus_pm_create_idea` | Create a new idea in a project (on behalf of humans). Optional `parentUuid` derives a child idea from an existing same-project idea (single-parent lineage). |
+| `chorus_edit_idea` | Edit an existing idea's title, description, and/or lineage parent. `parentUuid`: another same-project idea to reparent under, `null` to detach to top-level, omit to leave unchanged (cycle-checked + same-project). Single-parent **weak** lineage — a parent shows a read-only `+N derived` rollup but never blocks either idea's flow. Records an "edited" activity and signals presence. |
 | `chorus_claim_idea` | Claim an open idea (open -> elaborating) |
 | `chorus_release_idea` | Release a claimed idea (elaborating -> open) |
-| `chorus_move_idea` | Move an Idea to a different Project. Cascade-migrates the Idea, all linked Proposals (any status), all materialized Documents and Tasks, and all related Activities atomically. Comments, TaskDependency, AcceptanceCriterion, AgentSession, SessionTaskCheckin, Notification history, and Task assignees are NOT modified. Returns `moved: { proposals, documents, tasks, activities }` counts. Requires `idea:write` only — no project-level checks. |
+| `chorus_move_idea` | Move an Idea to a different Project. Cascade-migrates the Idea **and its full lineage subtree** (all descendant Ideas; the moved root is detached from any parent left behind), all linked Proposals (any status), all materialized Documents and Tasks, and all related Activities atomically. Comments, TaskDependency, AcceptanceCriterion, AgentSession, SessionTaskCheckin, Notification history, and Task assignees are NOT modified. Returns `moved: { ideas, proposals, documents, tasks, activities }` counts. Requires `idea:write` only — no project-level checks. |
 
 **Requirements Elaboration:**
 
@@ -276,6 +277,20 @@ chorus_pm_skip_elaboration({
 
 ---
 
+## Idea Lineage (derive vs. task)
+
+Ideas can form a **single-parent forest**: an idea may have one parent (`parentUuid`), establishing a weak lineage. "Weak" means the parent only shows a read-only `+N derived` rollup of its **direct** children — it never blocks or alters either idea's elaboration/proposal/task flow, and a parent is always a full first-class idea (it can have its own content, proposals, and tasks).
+
+When a new direction surfaces (during elaboration, brainstorm, or review), decide where it belongs:
+
+- **Derive a child idea** (`chorus_pm_create_idea` with `parentUuid`, or `chorus_edit_idea` with `parentUuid` to reparent an existing idea) when the new direction needs **its own elaboration/proposal lifecycle** — it is an independent AI-DLC pass.
+- **Add a task** to the current idea's proposal when the new work is just *how to implement the current idea*.
+- **Create a plain top-level idea** (no `parentUuid`) when there is no lineage to the current idea.
+
+This is a soft heuristic, not a rule — use judgment. Cycle prevention is automatic: you cannot set a parent that is the idea itself or one of its descendants. Parent and child must be in the same project (cross-project lineage is not supported yet). Deleting a parent re-parents its children to top-level (it never cascades). (Reminder: invoke these as `chorus__chorus_pm_create_idea` / `chorus__chorus_edit_idea` — see the namespace note at the top of the `chorus` skill.)
+
+---
+
 ## Tips
 
 - When combining multiple ideas, explain how they relate in the proposal description

package/skills/openspec-aware/SKILL.md

@@ -4,7 +4,7 @@ description: Opt-in OpenSpec-mode authoring for Chorus PM workflows on OpenClaw.
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/proposal-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial read-only review of a submitted Chorus proposal — doc
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/task-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial verification of a submitted Chorus task against its AC
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.9.4"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/src/connection-state.ts

@@ -0,0 +1,66 @@
+// packages/openclaw-plugin/src/connection-state.ts
+// Holds the live DaemonConnection identity for this OpenClaw plugin process —
+// the `connectionUuid` the server assigns post-handshake and reports via the
+// `connection_registered` SSE data event (see api/events/notifications/route.ts).
+//
+// WHY A DEDICATED MODULE: the connectionUuid is captured in ONE place (the SSE
+// listener, via onConnectionId) but READ in several (the daemon REST client to
+// attribute execution-state / turn-advance, and the control handler to do its
+// `targetConnectionUuid === my uuid` double-check). Threading it through every
+// constructor would couple those modules to the listener's lifecycle; instead
+// the listener writes it here and the consumers read it through a stable
+// `getConnectionUuid()` accessor — the same accessor shape the shared
+// `daemon-rest-client` already expects (`getConnectionUuid?: () => string|null`).
+//
+// The value is refreshed on every `connection_registered` (so a reconnect that
+// registers a NEW DaemonConnection overwrites the stale uuid), and is the single
+// source of truth for "which connection am I" across the plugin.
+//
+// This mirrors the CLI host's `SseListener.connectionUuid` field
+// (cli/sse-listener.mjs), lifted into a module so the OpenClaw plugin's separate
+// modules can share one identity without a circular import on the listener.
+
+/**
+ * A read accessor for the live connection identity. This is the exact shape the
+ * shared `daemon-rest-client` (`getConnectionUuid?: () => string|null`) and the
+ * control handler consume, so a single `ConnectionState` instance can be passed
+ * to both.
+ */
+export interface ConnectionStateReader {
+  /** The connection uuid this stream registered as, or null before handshake. */
+  getConnectionUuid: () => string | null;
+}
+
+/**
+ * Mutable connection identity. One instance per plugin process; the SSE
+ * listener's `onConnectionId` writes it, the rest client + control handler read
+ * it. Not a singleton export — the entry owns the instance and injects it — so
+ * tests can construct an isolated state per case.
+ */
+export class ConnectionState implements ConnectionStateReader {
+  private connectionUuid: string | null = null;
+
+  /** The current connection identity, or null before the first handshake. */
+  getConnectionUuid(): string | null {
+    return this.connectionUuid;
+  }
+
+  /**
+   * Record (or refresh) the connection identity. Called from the SSE listener's
+   * `onConnectionId` on every `connection_registered` event, so a reconnect that
+   * registers a new DaemonConnection overwrites the previous uuid rather than
+   * leaving a stale one that could mis-route a control command.
+   */
+  setConnectionUuid(connectionUuid: string): void {
+    this.connectionUuid = connectionUuid;
+  }
+
+  /**
+   * Forget the connection identity (e.g. on a clean disconnect). After this,
+   * `getConnectionUuid()` returns null so the control handler's double-check
+   * treats every command as "not ours" until a fresh handshake re-registers.
+   */
+  clear(): void {
+    this.connectionUuid = null;
+  }
+}

package/src/control-handler.ts

@@ -0,0 +1,219 @@
+// packages/openclaw-plugin/src/control-handler.ts
+// OpenClaw-host handler for reverse (server→daemon) control commands — the
+// in-process analog of cli/control-handler.mjs. The SSE listener forks a
+// `type:"control"` SSE event here (NOT to the wake router — see sse-listener.ts),
+// so a control command can NEVER spawn a new embedded-agent run for the control
+// event itself. This module is the ROUTING + DOUBLE-CHECK layer only; the actual
+// abort / re-dispatch / pending-turns-sweep BEHAVIORS are injected (filled by the
+// openclaw-daemon-client task, T4).
+//
+// The single safety property this module enforces is the DOUBLE-CHECK, identical
+// to the CLI host (cli/control-handler.mjs): act ONLY when —
+//   Check 1 (every command): event.targetConnectionUuid === this plugin's OWN
+//            registered connectionUuid (from connection-state). On mismatch — a
+//            stale/recycled uuid, another connection's command, or a handshake not
+//            yet complete — IGNORE + LOG. This is what stops a recycled connection
+//            uuid from aborting the wrong run (Tech Design "Risks": mis-kill after
+//            a reconnect).
+//   Check 2 (interrupt only): the injected `isEntityRunning(entityType, entityUuid)`
+//            predicate returns true — i.e. this plugin currently holds a running
+//            embedded-agent run for that entity. (In the CLI host this is "the
+//            execution registry holds a running child"; here it is an injected
+//            predicate the daemon client backs with its AbortController registry.)
+//            On mismatch — only queued, never ran, or already finished — IGNORE + LOG.
+//
+// `resume` and `deliver_turn` carry NO running-entity requirement (mirroring the
+// CLI host): the run for a resumed entity is already gone, and a `deliver_turn`
+// resolves its turn by uuid from the persisted turn table. They only require
+// Check 1.
+//
+// The three verbs route to injected behavior hooks (the seams T4 plugs into):
+//   - interrupt    → onInterrupt(entityType, entityUuid)
+//   - resume       → onResume(entityType, entityUuid)
+//   - deliver_turn → onDeliverTurn(turnUuid?)   (turnUuid present = precise single
+//                    turn; absent = older server, full connection sweep fallback)
+//
+// Non-throwing: a control event must NEVER crash the SSE loop, so the whole body
+// is wrapped in a try/catch backstop and the hooks' own throws are caught + logged
+// (memory: no-silent-errors — every ignore/failure is logged, never swallowed).
+
+import type { ConnectionStateReader } from "./connection-state.js";
+
+/**
+ * The control event shape the server publishes on `control:{connectionUuid}` and
+ * forwards verbatim as a `type:"control"` SSE data event. Mirrors the server's
+ * `ControlEvent` (src/lib/event-bus.ts). `entityType`/`entityUuid` are present for
+ * `interrupt`/`resume`; `turnUuid` is present only for `deliver_turn`.
+ */
+export interface ControlEvent {
+  // `string` (not the `"control"` literal) because this is the raw forked SSE
+  // event — the handler re-validates `type === "control"` and the command enum at
+  // runtime before acting. Matches the listener's `SseControlEvent` shape so the
+  // listener can pass its parsed event straight through.
+  type: string;
+  command?: string;
+  targetConnectionUuid?: string;
+  entityType?: string;
+  entityUuid?: string;
+  turnUuid?: string;
+}
+
+/**
+ * Injected behavior hooks. These are the seams the openclaw-daemon-client task
+ * (T4) fills with the real abort / re-dispatch / pending-turns-sweep. This task
+ * (T3) only ROUTES verified commands to them — it does not implement the
+ * behaviors. All hooks are optional so a partially-wired host (or a test) can
+ * verify routing without every behavior present.
+ */
+export interface ControlBehaviorHooks {
+  /**
+   * Whether this plugin currently holds a RUNNING embedded-agent run for the
+   * entity — the OpenClaw analog of the CLI host's "execution registry holds a
+   * running child" check. Gates `interrupt` (Check 2). Defaults to "nothing is
+   * running" (always false) when absent, so an interrupt with no registry is a
+   * safe no-op rather than a blind abort.
+   */
+  isEntityRunning?: (entityType: string, entityUuid: string) => boolean;
+
+  /**
+   * Abort the matching in-flight run for the entity (true mid-run stop via the
+   * run's AbortController). Invoked only after BOTH checks pass. (T4)
+   */
+  onInterrupt?: (entityType: string, entityUuid: string) => void;
+
+  /**
+   * Re-dispatch the entity's wake to continue the same session — the synthetic
+   * "resume" wake. Invoked after Check 1 only (no running-entity requirement —
+   * the run is gone). (T4)
+   */
+  onResume?: (entityType: string, entityUuid: string) => void;
+
+  /**
+   * Run the connection-scoped pending turn(s). With a `turnUuid` (origin-only
+   * live delivery) run PRECISELY that one turn; without one (older server /
+   * reconnect) sweep all pending turns. Invoked after Check 1 only. (T4)
+   */
+  onDeliverTurn?: (turnUuid?: string) => void;
+}
+
+export interface ControlHandlerOptions {
+  /** Live connection identity (connection-state). Provides Check 1's "my uuid". */
+  connectionState: ConnectionStateReader;
+  /** Injected behavior hooks (filled by T4). */
+  hooks: ControlBehaviorHooks;
+  logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+/**
+ * Build the `onControl(event)` callback the SSE listener invokes for a
+ * `type:"control"` event. The returned function is synchronous and non-throwing:
+ * it performs the double-check and routes to the (injected) behavior hook,
+ * returning immediately so the SSE consumer never blocks.
+ *
+ * A control event NEVER enqueues a wake or spawns a run for the control event
+ * itself — that structural guarantee is owned by the SSE listener fork (the
+ * control event never reaches `onEvent` / the wake router) and reinforced here
+ * by routing ONLY to the abort/resume/deliver hooks, never to the wake path.
+ */
+export function createControlHandler(opts: ControlHandlerOptions): (event: ControlEvent) => void {
+  const { connectionState, hooks, logger } = opts;
+  const isEntityRunning = hooks.isEntityRunning ?? (() => false);
+
+  return function onControl(event: ControlEvent): void {
+    try {
+      if (!event || event.type !== "control") {
+        logger.warn(`[Chorus] control-handler received non-control event; ignoring`);
+        return;
+      }
+
+      if (
+        event.command !== "interrupt" &&
+        event.command !== "resume" &&
+        event.command !== "deliver_turn"
+      ) {
+        // Forward-compatible: the wire enum may grow. Unknown command → ignore + log.
+        logger.warn(`[Chorus] control command "${event.command}" not supported; ignoring`);
+        return;
+      }
+
+      const { command, targetConnectionUuid, entityType, entityUuid } = event;
+
+      // --- Check 1: connection-uuid match (applies to EVERY command) ---
+      const myConnectionUuid = connectionState.getConnectionUuid();
+      if (!myConnectionUuid || targetConnectionUuid !== myConnectionUuid) {
+        // Not ours (stale/recycled uuid, another connection, or handshake not yet
+        // complete). Ignore — never abort/resume/deliver for a command that isn't ours.
+        logger.info(
+          `[Chorus] control: ignoring ${command} for connection ${targetConnectionUuid} ` +
+            `(this plugin is ${myConnectionUuid ?? "<unregistered>"})`,
+        );
+        return;
+      }
+
+      // --- deliver_turn: origin-only live delivery. No entity on the wire (the
+      //     turn is read by uuid) and NO running-entity requirement (mirrors
+      //     resume). With a turnUuid, run PRECISELY that turn; without one (older
+      //     server), the hook falls back to a full connection sweep. ---
+      if (command === "deliver_turn") {
+        const turnUuid = typeof event.turnUuid === "string" ? event.turnUuid : undefined;
+        logger.info(
+          `[Chorus] control: deliver_turn for connection ${targetConnectionUuid} ` +
+            (turnUuid ? `(turn ${turnUuid})` : "(no turnUuid — full sweep fallback)"),
+        );
+        try {
+          hooks.onDeliverTurn?.(turnUuid);
+        } catch (err) {
+          logger.warn(`[Chorus] control: deliver_turn hook failed: ${err}`);
+        }
+        return;
+      }
+
+      // interrupt / resume both target a specific entity — require both fields.
+      if (typeof entityType !== "string" || typeof entityUuid !== "string") {
+        logger.warn(`[Chorus] control: ${command} missing entityType/entityUuid; ignoring`);
+        return;
+      }
+
+      // --- resume: re-dispatch the wake for this entity. No running-entity check —
+      //     the run is gone (it was interrupted); the wake path re-enters the same
+      //     session. Check 1 already passed. ---
+      if (command === "resume") {
+        logger.info(`[Chorus] control: resuming ${entityType}:${entityUuid} (re-dispatch wake)`);
+        try {
+          hooks.onResume?.(entityType, entityUuid);
+        } catch (err) {
+          logger.warn(
+            `[Chorus] control: resume re-dispatch failed for ${entityType}:${entityUuid}: ${err}`,
+          );
+        }
+        return;
+      }
+
+      // --- interrupt path: Check 2 — this plugin must hold a RUNNING run for the
+      //     entity. The injected predicate is backed by the daemon client's
+      //     AbortController registry (T4). ---
+      if (!isEntityRunning(entityType, entityUuid)) {
+        // Either we never ran this entity, it's only queued, or the run already
+        // finished (race: interrupt arrived after completion). Safe no-op.
+        logger.info(
+          `[Chorus] control: no running embedded-agent run for ${entityType}:${entityUuid} ` +
+            `on this plugin; ignoring interrupt`,
+        );
+        return;
+      }
+
+      // --- Both checks passed: route to the abort hook (true mid-run stop). ---
+      logger.info(`[Chorus] control: interrupting running run for ${entityType}:${entityUuid}`);
+      try {
+        hooks.onInterrupt?.(entityType, entityUuid);
+      } catch (err) {
+        logger.warn(
+          `[Chorus] control: interrupt hook failed for ${entityType}:${entityUuid}: ${err}`,
+        );
+      }
+    } catch (err) {
+      // Absolute backstop — a control event must never crash the SSE loop.
+      logger.error(`[Chorus] control-handler unexpected error: ${err}`);
+    }
+  };
+}