@chorus-aidlc/chorus 0.11.0 → 0.12.0

package/cli/event-router.mjs

@@ -10,6 +10,27 @@
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
+// Map a Notification.action to its DaemonSessionTurn trigger category — the daemon-side
+// MIRROR of the server's NOTIFICATION_ACTION_TO_TURN_TRIGGER (src/services/notification-turn.ts).
+// Used ONLY to match a re-read wake notification back to a DIRECTED autonomous pending turn
+// (the deliver_turn re-dispatch rebuilds the prompt from the notification, T2). Kept narrow
+// to the three triggers a `deliver_turn` ping can carry for an autonomous wake; every other
+// action collapses to the `task_assigned` trigger exactly as the server does, so a
+// task_assigned turn matches its task_reopened/task_verified/idea_claimed/proposal_* origins.
+const ACTION_TO_TURN_TRIGGER = {
+  mentioned: "mentioned",
+  elaboration_verified: "elaboration_verified",
+  elaboration_requested: "elaboration",
+  elaboration_answered: "elaboration",
+  human_instruction: "human_instruction",
+  task_assigned: "task_assigned",
+  task_reopened: "task_assigned",
+  task_verified: "task_assigned",
+  idea_claimed: "task_assigned",
+  proposal_approved: "task_assigned",
+  proposal_rejected: "task_assigned",
+};
+
 export class EventRouter {
   /**
    * @param {{
@@ -17,6 +38,15 @@ export class EventRouter {
    *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wake: (n: any, key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
    *   queue: { enqueue: (key: string, task: () => Promise<void>) => void },
    *   wakeActions: Set<string>,
+   *   getConnectionUuid?: () => (string|null),  This daemon's registered connection uuid
+   *                                             (null until the SSE handshake reports it).
+   *                                             Same self-identity source the control handler
+   *                                             uses — wired in cli/daemon.mjs. Used to suppress
+   *                                             a DIRECTED (pinned) wake whose stamped target is
+   *                                             NOT this connection (fix-pinned-wake-directed-
+   *                                             delivery). Absent ⇒ no targeting (no suppression
+   *                                             ever) — preserves the pre-change behavior for any
+   *                                             caller that does not wire it.
    *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
    * }} opts
    */
@@ -25,6 +55,12 @@ export class EventRouter {
     this.waker = opts.waker;
     this.queue = opts.queue;
     this.wakeActions = opts.wakeActions;
+    // This daemon's own connection uuid (lazy — read at routing time, not construction,
+    // since the SSE handshake assigns it after the router is built). Defaults to a getter
+    // returning null so an un-wired router behaves as before (a stamped target is then
+    // never "mine", but only `human_instruction`/directed paths stamp one — un-pinned wakes
+    // carry no target and are unaffected).
+    this.getConnectionUuid = opts.getConnectionUuid ?? (() => null);
     this.logger = opts.logger ?? NOOP_LOGGER;
     // Shared dedup set: the daemon passes the SAME Set to the reconnect backfill
     // so a notification handled live is never re-woken on reconnect, and a
@@ -37,7 +73,18 @@ export class EventRouter {
   /**
    * Handle one SSE event. Synchronous + non-throwing: it kicks off async
    * fetch/route work and returns immediately so the SSE consumer never blocks.
-   * @param {{ type?: string, notificationUuid?: string }} event
+   *
+   * DIRECTED-DELIVERY TRANSPORT FIELDS (fix-pinned-wake-directed-delivery): a live
+   * `new_notification` event for a PINNED autonomous wake carries two TRANSPORT-ONLY fields
+   * stamped by the server (NOT persisted, NOT on `chorus_get_notifications`):
+   *   - `targetConnectionUuid` — the resolved ONLINE target connection for a directed wake;
+   *     null for un-pinned / notify-only wakes.
+   *   - `suppressWake` — true ONLY for an offline-pin wake (a pin matched NO online
+   *     connection) so EVERY daemon suppresses (Q2 notify-only); false otherwise.
+   * They are threaded to `#fetchAndRoute` so the broadcast-suppression decision can be made
+   * there. A reconnect-backfill synthetic event omits both (so a backfilled wake behaves as
+   * un-pinned → online-first; the directed target is covered by its own `deliver_turn` ping).
+   * @param {{ type?: string, notificationUuid?: string, targetConnectionUuid?: string|null, suppressWake?: boolean }} event
    */
   dispatch(event) {
     if (event?.type !== "new_notification") {
@@ -51,13 +98,25 @@ export class EventRouter {
       return; // already handled (e.g. live delivery then reconnect backfill)
     }
     this.seen.add(event.notificationUuid);
-    this.#fetchAndRoute(event.notificationUuid).catch((err) => {
-      this.logger.error(`[Chorus] failed to route notification ${event.notificationUuid}: ${err}`);
-    });
+    // Snapshot the transport-only directed-delivery fields off the EVENT (NOT the fetched
+    // notification — the server stamps them on the SSE envelope only).
+    const targetConnectionUuid =
+      typeof event.targetConnectionUuid === "string" ? event.targetConnectionUuid : null;
+    const suppressWake = event.suppressWake === true;
+    this.#fetchAndRoute(event.notificationUuid, { targetConnectionUuid, suppressWake }).catch(
+      (err) => {
+        this.logger.error(`[Chorus] failed to route notification ${event.notificationUuid}: ${err}`);
+      }
+    );
   }
 
-  /** @param {string} notificationUuid */
-  async #fetchAndRoute(notificationUuid) {
+  /**
+   * @param {string} notificationUuid
+   * @param {{ targetConnectionUuid?: string|null, suppressWake?: boolean }} [transport]
+   *   Transport-only directed-delivery fields snapshotted off the SSE event (see `dispatch`).
+   *   Omitted/empty (e.g. reconnect backfill) ⇒ un-pinned behavior (no suppression).
+   */
+  async #fetchAndRoute(notificationUuid, transport = {}) {
     const result = await this.mcp.callTool("chorus_get_notifications", {
       status: "unread",
       limit: 50,
@@ -95,6 +154,59 @@ export class EventRouter {
       return;
     }
 
+    // DIRECTED-DELIVERY BROADCAST SUPPRESSION (fix-pinned-wake-directed-delivery, T2). The
+    // notification SSE stream is per-AGENT, so EVERY online (host, cwd) connection of the
+    // agent receives the same `new_notification`. A pinned autonomous wake (mention /
+    // task_assigned / elaboration_verified resolved to a specific online instance) must wake
+    // ONLY that instance — the others must ignore their broadcast copy. The decision uses the
+    // transport-only fields the server stamped on THIS event (read in `dispatch`):
+    //
+    //   1. suppressWake === true → OFFLINE-PIN (Q2): a real pin matched NO online connection.
+    //      Wake NO instance, agent-wide, even though this connection may be online and would
+    //      otherwise broadcast→online-first. This is the ONE place that realizes the design's
+    //      "no online target → every connection suppresses → notify-only" intent. Without this
+    //      explicit flag an offline-pin is indistinguishable from an un-pinned wake (both carry
+    //      targetConnectionUuid:null) and would be silently re-woken — the bug this guards.
+    //
+    //   2. targetConnectionUuid set AND !== my connection uuid → a DIRECTED wake for a
+    //      DIFFERENT instance. Suppress: the resolved target wakes from its own copy (and via
+    //      the precise deliver_turn ping); this connection must not also wake (the agent-wide
+    //      fan-out is the headline bug). Pre-handshake (my uuid still null) counts as "not mine"
+    //      → suppress, since this daemon cannot prove it is the target; delivery to the actual
+    //      target is covered by the deliver_turn ping + reconnect pending-turn backfill.
+    //
+    //   3. targetConnectionUuid set AND === my connection uuid → I am the resolved target →
+    //      wake (acting on this broadcast copy, which carries the full prompt context). The
+    //      target's own deliver_turn→pending-turn delivery is deduped against this via the
+    //      shared `seen` set (the pending re-dispatch keys turn:{uuid}; whichever runs first
+    //      marks the other seen) so the target wakes exactly ONCE.
+    //
+    //   4. no target AND not suppressed → UN-PINNED (or a fully-offline `none` agent): wake
+    //      exactly as before this change (broadcast → online-first). BYTE-IDENTICAL — the path
+    //      below is untouched for this case.
+    if (transport.suppressWake === true) {
+      this.logger.info(
+        `[Chorus] wake ${notificationUuid} (${n.action}) is an OFFLINE-PIN (pin matched no online instance) — notify-only, suppressing wake on every connection`
+      );
+      return;
+    }
+    const target =
+      typeof transport.targetConnectionUuid === "string" ? transport.targetConnectionUuid : null;
+    if (target) {
+      const me = this.getConnectionUuid();
+      if (target !== me) {
+        this.logger.info(
+          `[Chorus] wake ${notificationUuid} (${n.action}) is directed to connection ${target}` +
+            ` — not this daemon (${me ?? "<unregistered>"}); suppressing broadcast wake`
+        );
+        return;
+      }
+      // target === me: I am the resolved target — fall through and wake (deduped below).
+      this.logger.info(
+        `[Chorus] wake ${notificationUuid} (${n.action}) is directed to THIS connection (${me}) — waking`
+      );
+    }
+
     await this.#resolveAndEnqueue(n, notificationUuid);
   }
 
@@ -136,11 +248,21 @@ export class EventRouter {
    * pending turn already handled live (or by an earlier backfill) is not re-run.
    * Synchronous + non-throwing, mirroring `dispatch`/`dispatchResume`.
    *
-   * Only `human_instruction` pending turns are re-dispatched here: autonomous turns
-   * (task_assigned / mentioned / elaboration / resume) are re-driven by the
-   * notification backfill (their notifications are re-fetched), whereas a
-   * human_instruction's actionable payload lives ONLY on the turn — so the turn table
-   * is its sole reliable backfill source.
+   * DELIVERY SCOPE (fix-pinned-wake-directed-delivery, T2 — widened): a `deliver_turn` ping
+   * now also fires for a DIRECTED autonomous wake (`mentioned` / `task_assigned` /
+   * `elaboration_verified`), so this entrypoint re-dispatches those too — not only
+   * `human_instruction`. Unlike `human_instruction`, an autonomous turn has
+   * `promptText = null` (only human_instruction carries canonical free text), so its wake
+   * prompt CANNOT be rebuilt from the turn — it is rebuilt from the wake NOTIFICATION
+   * (re-read via `chorus_get_notifications`) for the turn's session. See the
+   * `#redispatchAutonomousTurn` helper.
+   *
+   * DEDUP (the two delivery routes for a DIRECTED target collapse to ONE wake): the
+   * target's BROADCAST copy (handled in `#fetchAndRoute`, keyed `notificationUuid` in the
+   * shared `seen` set when `target === me`) and THIS `deliver_turn`→pending delivery (keyed
+   * `turn:{uuid}`) both reach the target. They share the same `seen` set; the autonomous
+   * re-dispatch additionally marks the MATCHED notification's `notificationUuid` so whichever
+   * route runs first claims the other's key, and the second is dropped — exactly once.
    *
    * @param {{ turnUuid?: string, sessionId?: string, directIdeaUuid?: string|null,
    *           trigger?: string, promptText?: string|null }} pending
@@ -156,7 +278,36 @@ export class EventRouter {
       this.logger.warn(`[Chorus] pending-turn ${turnUuid} missing sessionId, skipping`);
       return;
     }
-    // Only human_instruction is re-derived from the turn table (see doc above).
+    // A DIRECTED autonomous turn (mentioned / task_assigned / elaboration_verified) is
+    // delivered by the deliver_turn ping too (T2). Its prompt must be rebuilt from the
+    // notification (promptText is null), so it takes a separate async path. resume /
+    // elaboration are not delivered by deliver_turn (resume is synthetic; elaboration
+    // request/answer rides the notification broadcast), so they are not re-dispatched here.
+    if (
+      pending.trigger === "mentioned" ||
+      pending.trigger === "task_assigned" ||
+      pending.trigger === "elaboration_verified"
+    ) {
+      // Shared dedup, marked BEFORE async work (mirrors the human_instruction path and
+      // `dispatch`) so concurrent deliveries collapse to one wake.
+      const seenKey = `turn:${turnUuid}`;
+      if (this.seen.has(seenKey)) return;
+      this.seen.add(seenKey);
+      const directIdeaUuid =
+        typeof pending.directIdeaUuid === "string" ? pending.directIdeaUuid : null;
+      this.#redispatchAutonomousTurn({
+        turnUuid,
+        sessionId,
+        directIdeaUuid,
+        trigger: pending.trigger,
+      }).catch((err) => {
+        this.logger.error(
+          `[Chorus] failed to re-dispatch autonomous pending turn ${turnUuid}: ${err}`
+        );
+      });
+      return;
+    }
+    // Only human_instruction is re-derived from the turn table directly (see doc above).
     if (pending.trigger !== "human_instruction") {
       return;
     }
@@ -211,6 +362,116 @@ export class EventRouter {
     this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
   }
 
+  /**
+   * Re-dispatch a DIRECTED autonomous pending turn (mentioned / task_assigned /
+   * elaboration_verified) delivered by the `deliver_turn` ping (T2 — fix-pinned-wake-
+   * directed-delivery). Unlike `human_instruction`, the turn carries `promptText = null`,
+   * so the wake prompt must be rebuilt from the wake NOTIFICATION — `buildPrompt` (run
+   * inside `waker.wake`) needs `entityType` / `entityUuid` / `entityTitle` / `actorName` /
+   * `message`, none of which live on the turn. We re-read the unread notifications (the
+   * same `chorus_get_notifications` the router already uses) and pick the wake notification
+   * for THIS turn's session + trigger.
+   *
+   * PROMPT-CONTEXT CONSTRAINT (Tech Design): in the normal live case the target is online,
+   * so it ALSO received the broadcast — which `#fetchAndRoute` already woke (and marked the
+   * notification `seen`). This path then finds that notification already `seen` and dedups
+   * away → exactly one wake. In the rare missed-broadcast case (the ping arrived but the
+   * broadcast copy did not), this path is the one that wakes, with the prompt rebuilt from
+   * the re-read notification. If no matching unread notification exists at all (e.g. it was
+   * already read), there is no autonomous context to rebuild — log and skip (the durable
+   * net is the reconnect notification backfill, which re-derives autonomous wakes).
+   *
+   * DEDUP across the two routes: this matched notification's `uuid` is the SAME key the
+   * broadcast path marks in the shared `seen` set, so whichever route runs first claims it
+   * and the other is dropped. The `turn:{uuid}` key was already marked by the caller.
+   *
+   * @param {{ turnUuid: string, sessionId: string, directIdeaUuid: string|null, trigger: string }} pending
+   */
+  async #redispatchAutonomousTurn(pending) {
+    const { turnUuid, sessionId, directIdeaUuid, trigger } = pending;
+    let result;
+    try {
+      result = await this.mcp.callTool("chorus_get_notifications", {
+        status: "unread",
+        limit: 50,
+        autoMarkRead: false,
+      });
+    } catch (err) {
+      this.logger.warn(
+        `[Chorus] autonomous pending turn ${turnUuid}: notification re-read failed: ${err}`
+      );
+      return;
+    }
+    const notifications = result?.notifications;
+    if (!Array.isArray(notifications)) {
+      this.logger.warn(
+        `[Chorus] autonomous pending turn ${turnUuid}: no notifications array to rebuild prompt from`
+      );
+      return;
+    }
+
+    // Candidate wake notifications: unread, wake-action, mapping to THIS turn's trigger.
+    // ACTION_TO_TURN_TRIGGER mirrors the server's action→trigger collapse, so e.g. a
+    // task_assigned turn matches task_reopened/task_verified/idea_claimed/proposal_* origins.
+    const candidates = notifications.filter(
+      (x) => x && typeof x.uuid === "string" && ACTION_TO_TURN_TRIGGER[x.action] === trigger
+    );
+
+    // Match the wake notification for THIS turn by its session ANCHOR. The anchor is the
+    // turn's direct idea (idea-anchored session) or, lacking one, its session id; a CROSS-CWD
+    // mention keys the per-instance session `${directIdeaUuid}::${connectionUuid}` with
+    // directIdeaUuid=null, so the idea prefix before "::" is also a valid anchor. We never run
+    // lineage on the daemon — these are the anchors the server itself keyed the session on.
+    const ideaPrefix =
+      directIdeaUuid == null && sessionId.includes("::") ? sessionId.split("::")[0] : null;
+    const anchors = new Set(
+      [directIdeaUuid, sessionId, ideaPrefix].filter((a) => typeof a === "string" && a)
+    );
+    let match = candidates.find((x) => anchors.has(x.entityUuid));
+
+    // MISSED-BROADCAST RECOVERY (the rare path this re-dispatch exists for): when the wake's
+    // notification entity is NOT the session anchor (a lineage-anchored task_assigned, a
+    // comment-on-task mention, or a cross-cwd mention whose entity is a child of the idea),
+    // the anchor equality above can't match without a lineage round-trip. If there is exactly
+    // ONE unread candidate for this trigger, it is unambiguously this turn's wake — recover it.
+    // With 2+ candidates we cannot disambiguate safely, so we defer to the reconnect
+    // notification backfill rather than risk waking the wrong one.
+    if (!match && candidates.length === 1) {
+      match = candidates[0];
+      this.logger.info(
+        `[Chorus] autonomous pending turn ${turnUuid} (${trigger}): no anchor match, recovering the ` +
+          `single unread ${trigger} notification ${match.uuid} (missed-broadcast recovery)`
+      );
+    }
+    if (!match || typeof match.uuid !== "string") {
+      this.logger.info(
+        `[Chorus] autonomous pending turn ${turnUuid} (${trigger}): no unambiguous unread wake ` +
+          `notification for session ${sessionId} (${candidates.length} candidate(s)) — skipping ` +
+          `(covered by reconnect notification backfill)`
+      );
+      return;
+    }
+
+    // Cross-route dedup: claim the broadcast's key. If the broadcast already woke it (target
+    // === me path), it is already seen → drop this delivery (exactly one wake). Otherwise we
+    // claim it so a later broadcast copy is dropped by `dispatch`'s seen check.
+    if (this.seen.has(match.uuid)) {
+      this.logger.info(
+        `[Chorus] autonomous pending turn ${turnUuid}: broadcast copy ${match.uuid} already handled — deduped`
+      );
+      return;
+    }
+    this.seen.add(match.uuid);
+
+    // Rebuild + enqueue through the SAME resolve→markQueued→enqueue path as a live broadcast
+    // wake, so the prompt (buildPrompt inside waker.wake), session anchor, and serialization
+    // are byte-identical to the broadcast route. `match` is a full NotificationDetail.
+    this.logger.info(
+      `[Chorus] autonomous pending turn ${turnUuid} (${trigger}): waking from re-read notification ${match.uuid}`
+    );
+    await this.#resolveAndEnqueue(match, match.uuid);
+  }
+
   /**
    * Resolve a wake's serialization key + idea attribution, mark it queued, and
    * enqueue it on the per-direct-idea queue. Shared by the notification path

package/cli/server-signal-handlers.mjs

@@ -0,0 +1,41 @@
+// cli/server-signal-handlers.mjs
+// The Chorus CLI entry (`chorus.mjs`) is dual-purpose: with no subcommand it
+// launches the embedded Next.js server (with a PGlite child); with `daemon` /
+// `login` it dispatches a client subcommand that connects OUT to a remote
+// server. The server-launch path installs three process-signal handlers — a
+// SIGINT/SIGTERM graceful-shutdown handler and an `exit` handler that
+// force-kills the PGlite child — but those are MEANINGLESS (and actively
+// harmful) on a client-subcommand process: a `chorus daemon` never starts
+// PGlite, and the server's SIGINT/SIGTERM handler would otherwise pre-empt the
+// daemon's OWN graceful shutdown (it runs first, in registration order, and
+// calls `process.exit(0)` synchronously). See the idea / design docs.
+//
+// This module is intentionally PURE — it runs no side effects at import — so a
+// unit test can import the function in isolation and drive it with a fake
+// `process`-like object, without executing `chorus.mjs`'s import-time side
+// effects (subcommand dispatch, server-config parsing) and without delivering a
+// real fatal signal to the test runner.
+
+/**
+ * Install the server-only process-signal handlers, but ONLY for the server
+ * launch path (no client subcommand). When invoked as a client subcommand
+ * (`chorus daemon` / `chorus login`), this registers NOTHING and returns false,
+ * so the process terminates exclusively through the subcommand's own handler
+ * (e.g. the daemon's graceful `daemon.stop()`).
+ *
+ * @param {object} params
+ * @param {boolean} params.isSubcommand  true when a client subcommand is running.
+ * @param {{ on(event: string, listener: (...args: any[]) => void): unknown }} params.processRef
+ *   the process to attach listeners to (real `process`, or a fake in tests).
+ * @param {(...args: any[]) => void} params.shutdown    SIGINT/SIGTERM handler.
+ * @param {(...args: any[]) => void} params.cleanupExit `exit` handler (PGlite SIGKILL).
+ * @returns {boolean} true if the server handlers were installed, false if skipped.
+ */
+export function installServerSignalHandlers({ isSubcommand, processRef, shutdown, cleanupExit }) {
+  // Client subcommand → install none of the server's signal handlers.
+  if (isSubcommand) return false;
+  processRef.on("SIGINT", shutdown);
+  processRef.on("SIGTERM", shutdown);
+  processRef.on("exit", cleanupExit);
+  return true;
+}

package/cli/sse-listener.mjs

@@ -8,11 +8,19 @@
 // API key; data lines are `data: <json>\n\n`, heartbeats are `: ...` comments.
 //
 // Self-report: the listener appends ?clientType=claude_code&clientVersion=…&
-// host=…&startedAt=… to the endpoint so the server's DaemonConnection registry
-// (src/services/daemon-connection.service.ts → parseSelfReport) can record which
-// client is on the other end. The CLI reports clientType=claude_code (it only
-// drives a local Claude Code subprocess — not a generic "daemon"). These params
-// are display-only metadata; auth remains the unchanged Bearer header.
+// host=…&cwd=…&startedAt=… to the endpoint so the server's DaemonConnection
+// registry (src/services/daemon-connection.service.ts → parseSelfReport) can
+// record which client is on the other end. The CLI reports clientType=claude_code
+// (it only drives a local Claude Code subprocess — not a generic "daemon"). These
+// params are display-only metadata; auth remains the unchanged Bearer header.
+//
+// `cwd` is the working directory this daemon connection serves. Today the CLI
+// runs single-cwd (the directory it was launched from), so it reports
+// `process.cwd()`. The server keys the connection registry on
+// (agentUuid, clientType, host, cwd) — so the same agent on the same host driving
+// two different working directories registers as two independent connections
+// instead of overwriting each other. An *older* daemon that does not send `cwd`
+// registers as a `cwd=null` row (HARD-1: no error, behaves exactly as before).
 
 import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
@@ -63,6 +71,12 @@ const PROCESS_STARTED_AT = new Date();
  *   connection + entity and interrupts the running subprocess (see control-handler.mjs).
  * @property {() => Promise<void>} [onReconnect]  Called after a reconnect so the
  *   caller can back-fill notifications missed during the gap.
+ * @property {string} [cwd]  The working directory THIS connection serves (T3 — 单
+ *   daemon 多路径). A multi-path daemon runs one SseListener per declared path, each
+ *   self-reporting its own cwd so the server registers them as distinct connections
+ *   (the registry key includes cwd). Omitted ⇒ the daemon's process cwd (single-path
+ *   / HARD-1 default — identical to today). It is JUST the served path; it carries no
+ *   project binding (DEC-5: cwd ⟂ project).
  * @property {{info(m:string):void,warn(m:string):void,error(m:string):void}} [logger]
  * @property {typeof fetch} [fetchImpl]  Injectable for tests.
  * @property {number} [initialDelayMs]
@@ -87,10 +101,18 @@ export class SseListener {
 
     // Build the self-reporting endpoint URL once and reuse it across every
     // (re)connect, so the reconnect path always re-sends the same params.
+    // Working directory THIS connection serves. A multi-path daemon (T3) constructs
+    // one SseListener per declared path, each with its own `opts.cwd`, so the server's
+    // (agentUuid, clientType, host, cwd) registry key lands them as distinct rows —
+    // same agent + same host + different cwd no longer overwrite each other. When no
+    // cwd is supplied the daemon is single-path: report the process cwd (the directory
+    // it was launched from), identical to today / an old daemon (HARD-1).
+    this.cwd = opts.cwd ?? process.cwd();
     const params = new URLSearchParams({
       clientType: "claude_code",
       clientVersion: CLI_VERSION,
       host: hostname(),
+      cwd: this.cwd,
       startedAt: PROCESS_STARTED_AT.toISOString(),
     });
     this.endpoint = `${this.url}/api/events/notifications?${params.toString()}`;

package/cli/waker.mjs

@@ -28,7 +28,7 @@ export class Waker {
    *   creds: { url: string, apiKey: string },
    *   lineage: { resolve: (event: any) => Promise<{ rootIdeaUuid: string|null, directIdeaUuid: string|null }> },
    *   spawner: { wake: (params: any) => Promise<{ sessionId: string, exitCode: number|null, isNew: boolean }> },
-   *   cwd?: string,  Spawn working directory; used BOTH for the transcript probe and the spawn (default process.cwd()).
+   *   cwd?: string,  The connection/session-bound working directory this Waker serves; resolveCwd() is the single source the probe + spawn + resume use. `undefined` ⇒ the process default cwd (HARD-1 / single-path).
    *   hooks?: import("./upload-hooks.mjs").UploadHooks,
    *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
    *   writeMcpConfigFn?: typeof writeMcpConfig,
@@ -54,10 +54,14 @@ export class Waker {
     // line per lifecycle event (arrival / spawn new-vs-resume / completion).
     // When true, additional detail is emitted alongside those lines.
     this.verbose = opts.verbose ?? false;
-    // The daemon spawns in one fixed working directory; the transcript probe must
-    // use the SAME cwd as the spawn, or it would decide new-vs-resume against the
-    // wrong directory (claude scopes --resume to cwd).
-    this.cwd = opts.cwd ?? process.cwd();
+    // The connection/session-bound working directory this Waker serves (T3 — 单
+    // daemon 多路径引擎). A daemon process may run SEVERAL Wakers, one per declared
+    // path, each pinned to its own cwd; the daemon process's OWN cwd never changes
+    // (NFR-3). `opts.cwd` is that bound path; `undefined` (unspecified / old daemon /
+    // single-path default) degrades to the process cwd via resolveCwd(). Stored raw
+    // so resolveCwd() is the SINGLE place the process-default fallback is applied
+    // (Module Contract 1 — one cwd source of truth, no scattered process.cwd()).
+    this.cwd = opts.cwd;
     this.hooks = opts.hooks;
     this.logger = opts.logger ?? NOOP_LOGGER;
     this.writeMcpConfigFn = opts.writeMcpConfigFn ?? writeMcpConfig;
@@ -105,6 +109,25 @@ export class Waker {
     this.executions = new Map();
   }
 
+  /**
+   * The SINGLE source of truth for this Waker's working directory (Module Contract
+   * 1 — 不变式安全 / cwd 事实源统一). transcript probing (new-vs-resume), spawn, and
+   * resume ALL resolve cwd through here, so they can never diverge — a divergence
+   * would make the on-disk transcript probe decide new-vs-resume against a different
+   * directory than the one we spawn in (`claude --resume` is cwd-bound).
+   *
+   * Returns the connection/session-bound cwd when one was declared, else the daemon
+   * process's own cwd. The process-default fallback lives ONLY here: `this.cwd` is
+   * stored raw (possibly `undefined`) and `process.cwd()` is read at exactly this one
+   * site — Module Contract 2's HARD-1 degrade path (an old daemon / unspecified cwd
+   * behaves exactly as today, spawning at the process default). No other code in the
+   * wake path reads `process.cwd()`.
+   * @returns {string}
+   */
+  resolveCwd() {
+    return this.cwd ?? process.cwd();
+  }
+
   /**
    * Mark a running entity as INTERRUPTING (子3) — called by the control handler the
    * moment an authorized interrupt is verified, BEFORE the killer signals the child.
@@ -295,7 +318,12 @@ export class Waker {
       // spawn in. The spawner re-validates the id is a lowercase UUID before
       // spawning, so a garbage id surfaces visibly rather than misanchoring.
       const sessionId = directIdeaUuid ?? notification.entityUuid ?? null;
-      const isNew = sessionId ? this.isNewSessionFn(sessionId, this.cwd) : true;
+      // Resolve the connection/session-bound cwd ONCE for this wake (Module Contract
+      // 1). The transcript probe and the spawn below BOTH use this same value, so a
+      // session's repeated wakes/probes always land the same cwd (NFR-3) — and a
+      // multi-path daemon's other Wakers (other cwds) never bleed in.
+      const cwd = this.resolveCwd();
+      const isNew = sessionId ? this.isNewSessionFn(sessionId, cwd) : true;
 
       // Lifecycle line 2 — spawn: new vs resume, plus the (otherwise hidden)
       // `claude --resume <id>` takeover hint so an operator can attach to the
@@ -305,7 +333,7 @@ export class Waker {
           (sessionId ? ` — take over with: claude --resume ${sessionId}` : "")
       );
       if (this.verbose) {
-        this.logger.info(`[Chorus]   cwd=${this.cwd} action=${notification.action} root=${rootIdeaUuid ?? "(none)"}`);
+        this.logger.info(`[Chorus]   cwd=${cwd} action=${notification.action} root=${rootIdeaUuid ?? "(none)"}`);
       }
 
       cfg = this.writeMcpConfigFn(this.creds);
@@ -331,7 +359,7 @@ export class Waker {
         prompt,
         sessionId,
         isNew,
-        cwd: this.cwd,
+        cwd,
         mcpConfigPath: cfg.path,
         // Capture the live child into the running execution entry the instant it
         // spawns (子3) so the control handler can interrupt it mid-wake. Guarded so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The Agent Harness for AI-Human Collaboration — session lifecycle, task state, sub-agent orchestration, observability, and failure recovery",
   "homepage": "https://github.com/Chorus-AIDLC/Chorus",
   "repository": {

package/prisma/migrations/20260622115159_add_daemon_connection_cwd/migration.sql

@@ -0,0 +1,9 @@
+-- DropIndex
+DROP INDEX "DaemonConnection_agentUuid_clientType_host_key";
+
+-- AlterTable
+ALTER TABLE "DaemonConnection" ADD COLUMN     "cwd" TEXT;
+
+-- CreateIndex
+CREATE UNIQUE INDEX "DaemonConnection_agentUuid_clientType_host_cwd_key" ON "DaemonConnection"("agentUuid", "clientType", "host", "cwd");
+

package/prisma/migrations/20260623020208_task_pinned_target_instance/migration.sql

@@ -0,0 +1,3 @@
+-- AlterTable
+ALTER TABLE "Task" ADD COLUMN     "targetCwd" TEXT,
+ADD COLUMN     "targetHost" TEXT;

package/prisma/migrations/20260624142248_add_agent_instance/migration.sql

@@ -0,0 +1,31 @@
+-- AlterTable
+ALTER TABLE "DaemonConnection" ADD COLUMN     "agentInstanceUuid" TEXT;
+
+-- CreateTable
+CREATE TABLE "AgentInstance" (
+    "id" SERIAL NOT NULL,
+    "uuid" TEXT NOT NULL,
+    "companyUuid" TEXT NOT NULL,
+    "agentUuid" TEXT NOT NULL,
+    "host" TEXT NOT NULL DEFAULT '',
+    "cwd" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AgentInstance_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AgentInstance_uuid_key" ON "AgentInstance"("uuid");
+
+-- CreateIndex
+CREATE INDEX "AgentInstance_companyUuid_idx" ON "AgentInstance"("companyUuid");
+
+-- CreateIndex
+CREATE INDEX "AgentInstance_agentUuid_idx" ON "AgentInstance"("agentUuid");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AgentInstance_companyUuid_agentUuid_host_cwd_key" ON "AgentInstance"("companyUuid", "agentUuid", "host", "cwd");
+
+-- CreateIndex
+CREATE INDEX "DaemonConnection_agentInstanceUuid_idx" ON "DaemonConnection"("agentInstanceUuid");

package/prisma/migrations/20260624165025_drop_task_target_host_cwd/migration.sql

@@ -0,0 +1,10 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `targetCwd` on the `Task` table. All the data in the column will be lost.
+  - You are about to drop the column `targetHost` on the `Task` table. All the data in the column will be lost.
+
+*/
+-- AlterTable
+ALTER TABLE "Task" DROP COLUMN "targetCwd",
+DROP COLUMN "targetHost";