@sleep2agi/commhub-server 0.9.0-preview.30 → 0.9.0-preview.32

package/src/side-thread.ts

@@ -770,6 +770,12 @@ export class SideThreadCoordinator {
     if (existing) {
       if (existing.fingerprint !== fingerprint)
         throw conflict("idempotency key reused with different create payload");
+      if (this.createNeedsReconciliation(existing.record)) {
+        return this.singleFlight(
+          `create:${actor.userId}:${input.requestKey}`,
+          () => this.reconcileCreate(actor, input, attachments, fingerprint),
+        );
+      }
       return existing.record;
     }
     return this.singleFlight(
@@ -781,6 +787,8 @@ export class SideThreadCoordinator {
             throw conflict(
               "idempotency key reused with different create payload",
             );
+          if (this.createNeedsReconciliation(replay.record))
+            return this.reconcileCreate(actor, input, attachments, fingerprint);
           return replay.record;
         }
         const capability = await this.assertCapability(
@@ -880,7 +888,7 @@ export class SideThreadCoordinator {
             throw runtimeProtocol(
               "runtime returned source thread as side thread",
             );
-          this.store.db.transaction(() => {
+          this.applyRuntimeReceipt(() => {
             const t = this.now();
             this.store.db.run(
               "UPDATE side_chats SET derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND state='creating'",
@@ -921,16 +929,18 @@ export class SideThreadCoordinator {
             attachments,
           });
           requireRuntimeIdentity(started.turnId, "turnId");
-          this.store.db.transaction(() => {
+          const attemptBeforeApply = this.store.db.get<any>(
+            "SELECT state,turn_id FROM side_chat_attempts WHERE attempt_id=?1",
+            attemptId,
+          );
+          if (!attemptBeforeApply) throw conflict("attempt disappeared during start");
+          if (attemptBeforeApply.turn_id && attemptBeforeApply.turn_id !== started.turnId)
+            throw runtimeProtocol("runtime turn identity changed during start");
+          this.applyRuntimeReceipt(() => {
             const attempt = this.store.db.get<any>(
               "SELECT state,turn_id FROM side_chat_attempts WHERE attempt_id=?1",
               attemptId,
             );
-            if (!attempt) throw conflict("attempt disappeared during start");
-            if (attempt.turn_id && attempt.turn_id !== started.turnId)
-              throw runtimeProtocol(
-                "runtime turn identity changed during start",
-              );
             this.settleOperation(startOperationId, "completed", {
               threadId: forked.threadId,
               turnId: started.turnId,
@@ -964,10 +974,7 @@ export class SideThreadCoordinator {
             this.markAmbiguous(sideChatId, attemptId, activeOperationId, error);
             throw ambiguousError(activeOperationId, sideChatId, attemptId);
           }
-          this.settleOperation(activeOperationId, "failed", {
-            errorCode: auditErrorReason(error),
-          });
-          this.failStarting(sideChatId, attemptId, error);
+          this.failStarting(sideChatId, attemptId, error, activeOperationId);
           throw normalizePortError(error);
         }
         return this.mustOwned(sideChatId, actor);
@@ -975,6 +982,132 @@ export class SideThreadCoordinator {
     );
   }
 
+  /**
+   * Resume the stable fork/start operations after an ACK arrived outside the
+   * request window.  All identity needed to resume lives in SQLite; calling
+   * create again from another process therefore consumes the durable receipt
+   * instead of issuing a second native operation.
+   */
+  private async reconcileCreate(
+    actor: SideThreadActor,
+    input: CreateInput,
+    attachments: SideThreadAttachmentRef[],
+    fingerprint: string,
+  ): Promise<SideThreadRecord> {
+    const found = this.store.getByCreateKey(actor, input.requestKey);
+    if (!found) throw conflict("create record disappeared during reconciliation");
+    if (found.fingerprint !== fingerprint)
+      throw conflict("idempotency key reused with different create payload");
+    const sideChatId = found.record.sideChatId;
+    const attemptId = found.record.activeAttemptId;
+    if (!attemptId) throw conflict("create attempt disappeared during reconciliation");
+    const forkOperationId = stableOperationId(sideChatId, "fork", input.requestKey);
+    const startOperationId = stableOperationId(sideChatId, "start", input.requestKey);
+    let activeOperationId = forkOperationId;
+    try {
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.store.db.run(
+          "UPDATE side_chats SET state='reconciling',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('creating','ambiguous')",
+          [at, sideChatId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET state='reconciling',updated_at=?1 WHERE attempt_id=?2 AND state IN ('starting','ambiguous')",
+          [at, attemptId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+          [at, forkOperationId],
+        );
+      });
+      const forkOp = this.store.db.get<any>(
+        "SELECT state,thread_id FROM side_chat_operations WHERE operation_id=?1",
+        forkOperationId,
+      );
+      let threadId = forkOp?.state === "completed" ? forkOp.thread_id : undefined;
+      if (!threadId) {
+        const forked = await this.port.fork({
+          operationId: forkOperationId,
+          requestKey: input.requestKey,
+          sideChatId,
+          nodeId: input.nodeId,
+          sourceThreadId: input.sourceThreadId,
+          boundary: input.boundary,
+        });
+        threadId = forked.threadId;
+      }
+      requireRuntimeIdentity(threadId, "threadId");
+      if (threadId === input.sourceThreadId)
+        throw runtimeProtocol("runtime returned source thread as side thread");
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.settleOperation(forkOperationId, "completed", { threadId });
+        this.store.db.run(
+          "UPDATE side_chats SET derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND state IN ('creating','ambiguous','reconciling')",
+          [threadId, at, sideChatId],
+        );
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET thread_id=?1,updated_at=?2 WHERE attempt_id=?3 AND state IN ('starting','ambiguous','reconciling')",
+          [threadId, at, attemptId],
+        );
+        const existingStart = this.store.db.get<any>(
+          "SELECT operation_id FROM side_chat_operations WHERE operation_id=?1",
+          startOperationId,
+        );
+        if (!existingStart)
+          this.insertOperation({ operationId: startOperationId, sideChatId, attemptId, kind: "start", requestKey: input.requestKey, fingerprint, threadId, at });
+        else
+          this.store.db.run(
+            "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+            [at, startOperationId],
+          );
+      });
+      activeOperationId = startOperationId;
+      const startOp = this.store.db.get<any>(
+        "SELECT state,turn_id FROM side_chat_operations WHERE operation_id=?1",
+        startOperationId,
+      );
+      let turnId = startOp?.state === "completed" ? startOp.turn_id : undefined;
+      if (!turnId) {
+        const started = await this.port.start({ operationId: startOperationId, requestKey: input.requestKey, sideChatId, attemptId, nodeId: input.nodeId, threadId, prompt: input.prompt, attachments });
+        turnId = started.turnId;
+      }
+      requireRuntimeIdentity(turnId, "turnId");
+      this.applyRuntimeReceipt(() => {
+        const at = this.now();
+        this.settleOperation(startOperationId, "completed", { threadId, turnId });
+        this.store.db.run(
+          "UPDATE side_chat_attempts SET state='running',thread_id=?1,turn_id=?2,updated_at=?3 WHERE attempt_id=?4 AND state IN ('starting','ambiguous','reconciling')",
+          [threadId, turnId, at, attemptId],
+        );
+        this.store.db.run(
+          "UPDATE side_chats SET state='running',derived_thread_id=?1,updated_at=?2 WHERE side_chat_id=?3 AND active_attempt_id=?4 AND state IN ('creating','ambiguous','reconciling')",
+          [threadId, at, sideChatId, attemptId],
+        );
+      });
+      return this.mustOwned(sideChatId, actor);
+    } catch (error) {
+      if (isAmbiguousRuntimeError(error)) {
+        if (this.operationState(activeOperationId) === "completed")
+          return this.mustOwned(sideChatId, actor);
+        this.markAmbiguous(sideChatId, attemptId, activeOperationId, error);
+        throw ambiguousError(activeOperationId, sideChatId, attemptId);
+      }
+      this.failStarting(sideChatId, attemptId, error, activeOperationId);
+      throw normalizePortError(error);
+    }
+  }
+
+  private createNeedsReconciliation(record: SideThreadRecord): boolean {
+    if (["creating", "ambiguous", "reconciling"].includes(record.state)) return true;
+    const active = record.attempts.find((attempt) => attempt.attemptId === record.activeAttemptId);
+    if (active && ["starting", "ambiguous", "reconciling"].includes(active.state)) return true;
+    return record.operations.some((operation) =>
+      (operation.kind === "fork" || operation.kind === "start") &&
+      ["pending", "ambiguous", "reconciling"].includes(operation.state),
+    );
+  }
+
   get(actor: SideThreadActor, sideChatId: string): SideThreadRecord {
     this.assertEnabled();
     this.assertActor(actor);
@@ -1042,19 +1175,35 @@ export class SideThreadCoordinator {
           operation_id: string;
           attempt_id: string | null;
           state: SideThreadOperationRecord["state"];
+          error_code: string | null;
         }>(
-          "SELECT operation_id,attempt_id,state FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='cancel' AND request_key=?2",
+          "SELECT operation_id,attempt_id,state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='cancel' AND request_key=?2",
           sideChatId,
           input.requestKey,
         );
         if (replay?.state === "completed" || replay?.state === "pending")
           return record;
-        if (replay?.state === "ambiguous" || replay?.state === "reconciling")
-          throw ambiguousError(
-            replay.operation_id,
-            sideChatId,
-            replay.attempt_id ?? undefined,
-          );
+        if (replay?.state === "failed") throw persistedOperationFailure(replay.error_code);
+        if (replay?.state === "ambiguous" || replay?.state === "reconciling") {
+          const attempt = record.attempts.find((a) => a.attemptId === replay.attempt_id);
+          if (!attempt?.threadId || !attempt.turnId) throw conflict("cancel ownership missing");
+          await this.reconcileLifecycleOperation({
+            sideChatId, attemptId: attempt.attemptId, operationId: replay.operation_id,
+            invoke: () => this.port.cancel({ operationId: replay.operation_id, sideChatId, attemptId: attempt.attemptId, nodeId: record.nodeId, threadId: attempt.threadId!, turnId: attempt.turnId! }),
+            receipt: () => ({ threadId: attempt.threadId, turnId: attempt.turnId }),
+            accepted: () => {
+              const t = this.now();
+              this.store.db.run("UPDATE side_chat_attempts SET state='running',updated_at=?1 WHERE attempt_id=?2 AND state IN ('ambiguous','reconciling')", [t, attempt.attemptId]);
+              this.store.db.run("UPDATE side_chats SET state='running',updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3 AND state IN ('ambiguous','reconciling')", [t, sideChatId, attempt.attemptId]);
+            },
+            failed: () => {
+              const t = this.now();
+              this.store.db.run("UPDATE side_chat_attempts SET state='running',cancel_requested_at=NULL,updated_at=?1 WHERE attempt_id=?2 AND state IN ('ambiguous','reconciling')", [t, attempt.attemptId]);
+              this.store.db.run("UPDATE side_chats SET state='running',updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3 AND state IN ('ambiguous','reconciling')", [t, sideChatId, attempt.attemptId]);
+            },
+          });
+          return this.mustOwned(sideChatId, actor);
+        }
         const attempt = record.attempts.find(
           (a) => a.attemptId === record.activeAttemptId,
         );
@@ -1141,27 +1290,8 @@ export class SideThreadCoordinator {
           throw normalizePortError(error);
         }
         this.store.db.transaction(() => {
-          const t = this.now();
-          const changed = this.store.db.run(
-            "UPDATE side_chat_attempts SET state='cancelled',updated_at=?1 WHERE attempt_id=?2 AND state='running' AND thread_id=?3 AND turn_id=?4",
-            [t, attempt.attemptId, attempt.threadId, attempt.turnId],
-          );
-          if (changed.changes > 0) {
-            this.store.db.run(
-              "UPDATE side_chats SET state='cancelled',active_attempt_id=NULL,updated_at=?1 WHERE side_chat_id=?2 AND active_attempt_id=?3",
-              [t, sideChatId, attempt.attemptId],
-            );
-            this.emitStored(
-              sideChatId,
-              attempt.attemptId,
-              attempt.threadId,
-              attempt.turnId,
-              "attempt.cancelled",
-              "cancelled",
-              undefined,
-              t,
-            );
-          }
+          // Command acceptance only proves that interrupt was accepted.  The
+          // authoritative terminal event owns the cancelled/completed race.
           this.settleOperation(prepared.operationId, "completed", {
             threadId: attempt.threadId,
             turnId: attempt.turnId,
@@ -1337,10 +1467,7 @@ export class SideThreadCoordinator {
             this.markAmbiguous(sideChatId, attemptId, startOperationId, error);
             throw ambiguousError(startOperationId, sideChatId, attemptId);
           }
-          this.settleOperation(startOperationId, "failed", {
-            errorCode: auditErrorReason(error),
-          });
-          this.failStarting(sideChatId, attemptId, error);
+          this.failStarting(sideChatId, attemptId, error, startOperationId);
           throw normalizePortError(error);
         }
         return this.mustOwned(sideChatId, actor);
@@ -1379,6 +1506,11 @@ export class SideThreadCoordinator {
         if (!r.threadId) throw conflict("side chat has no derived thread");
         if (r.state === "purged") return r;
         if (action === "archive" && r.state === "archived") return r;
+        const priorOperation = this.store.db.get<{ state: string; error_code: string | null }>(
+          "SELECT state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind=?2 AND request_key=?3",
+          sideChatId, action, input.requestKey,
+        );
+        if (priorOperation?.state === "failed") throw persistedOperationFailure(priorOperation.error_code);
         await this.assertCapability(r.nodeId);
         const prepared = this.prepareStableOperation({
           sideChatId,
@@ -1388,8 +1520,18 @@ export class SideThreadCoordinator {
           threadId: r.threadId,
         });
         if (prepared.state === "completed") return r;
-        if (prepared.state === "ambiguous" || prepared.state === "reconciling")
-          throw ambiguousError(prepared.operationId, sideChatId);
+        if (prepared.state === "ambiguous" || prepared.state === "reconciling") {
+          await this.reconcileLifecycleOperation({
+            sideChatId, operationId: prepared.operationId,
+            invoke: () => action === "archive"
+              ? this.port.archive({ operationId: prepared.operationId, sideChatId, nodeId: r.nodeId, threadId: r.threadId! })
+              : this.port.purge({ operationId: prepared.operationId, sideChatId, nodeId: r.nodeId, threadId: r.threadId! }),
+            receipt: () => ({ threadId: r.threadId }),
+            accepted: () => this.applyLifecycleAccepted(sideChatId, action, prepared.operationId, r.threadId!),
+            failed: () => this.store.db.run("UPDATE side_chats SET state='failed',lifecycle_operation=NULL,updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [this.now(), sideChatId]),
+          });
+          return this.mustOwned(sideChatId, actor);
+        }
         if (!prepared.callable)
           throw conflict("side chat lifecycle operation already in progress");
         const claim = this.store.db.run(
@@ -1536,21 +1678,33 @@ export class SideThreadCoordinator {
             const operation = this.store.db.get<{
               operation_id: string;
               state: string;
+              error_code: string | null;
             }>(
-              "SELECT operation_id,state FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='bring-back' AND request_key=?2",
+              "SELECT operation_id,state,error_code FROM side_chat_operations WHERE side_chat_id=?1 AND operation_kind='bring-back' AND request_key=?2",
               sideChatId,
               input.requestKey,
             );
-            if (
-              operation &&
-              (operation.state === "ambiguous" ||
-                operation.state === "reconciling")
-            )
-              throw ambiguousError(
-                operation.operation_id,
-                sideChatId,
-                attempt.attemptId,
-              );
+            if (operation && (operation.state === "ambiguous" || operation.state === "reconciling")) {
+              const destinationTurnId = await this.reconcileLifecycleOperation({
+                sideChatId, attemptId: attempt.attemptId, operationId: operation.operation_id,
+                invoke: async () => (await this.port.bringBack({ operationId: operation.operation_id, sideChatId, attemptId: attempt.attemptId, nodeId: r.nodeId, sourceThreadId: attempt.threadId!, sourceTurnId: attempt.turnId!, destinationThreadId: input.destinationThreadId, requestKey: input.requestKey, text: attempt.result! })).destinationTurnId,
+                receipt: (turn) => ({ threadId: input.destinationThreadId, turnId: turn }),
+                accepted: (turn) => {
+                  requireRuntimeIdentity(turn, "destinationTurnId");
+                  const now = this.now();
+                  this.store.db.run("UPDATE side_chat_bring_backs SET state='completed',destination_turn_id=?1,error_text=NULL,updated_at=?2,completed_at=?2 WHERE bring_back_id=?3 AND state IN ('starting','ambiguous','reconciling')", [turn, now, old.bring_back_id]);
+                  this.store.db.run("UPDATE side_chats SET state='completed',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [now, sideChatId]);
+                  this.emitStored(sideChatId, attempt.attemptId, attempt.threadId, attempt.turnId, "side_chat.brought_back", "completed", undefined, now);
+                },
+                failed: (error) => {
+                  const now = this.now();
+                  this.store.db.run("UPDATE side_chat_bring_backs SET state='failed',error_text=?1,updated_at=?2 WHERE bring_back_id=?3 AND state IN ('starting','ambiguous','reconciling')", [safeReason(error instanceof Error ? error.message : String(error)), now, old.bring_back_id]);
+                  this.store.db.run("UPDATE side_chats SET state='completed',updated_at=?1 WHERE side_chat_id=?2 AND state IN ('ambiguous','reconciling')", [now, sideChatId]);
+                },
+              });
+              return { bringBackId: old.bring_back_id, destinationTurnId };
+            }
+            if (operation?.state === "failed") throw persistedOperationFailure(operation.error_code);
             throw conflict("bring-back is already in progress or failed");
           }
           return {
@@ -1723,6 +1877,84 @@ export class SideThreadCoordinator {
     );
   }
 
+  private applyRuntimeReceipt(apply: () => void): void {
+    try {
+      this.store.db.transaction(apply);
+    } catch {
+      // The runtime receipt remains authoritative and durable; only the local
+      // projection failed. Callers mark the stable operation ambiguous so a
+      // restart can consume the same receipt without another native command.
+      throw new SideThreadError(
+        "SIDE_THREAD_AMBIGUOUS",
+        "runtime receipt accepted; local apply requires reconciliation",
+        202,
+      );
+    }
+  }
+
+  private async reconcileLifecycleOperation<T>(input: {
+    sideChatId: string;
+    attemptId?: string;
+    operationId: string;
+    invoke: () => Promise<T>;
+    receipt: (value: T) => { threadId?: string; turnId?: string };
+    accepted: (value: T) => void;
+    failed: (error: unknown) => void;
+  }): Promise<T> {
+    this.store.db.run(
+      "UPDATE side_chat_operations SET state='reconciling',updated_at=?1 WHERE operation_id=?2 AND state='ambiguous'",
+      [this.now(), input.operationId],
+    );
+    let value: T;
+    try {
+      value = await input.invoke();
+    } catch (error) {
+      if (isAmbiguousRuntimeError(error)) {
+        this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, error);
+        throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+      }
+      try {
+        this.store.db.transaction(() => {
+          const won = this.store.db.run(
+            "UPDATE side_chat_operations SET state='failed',error_code=?1,updated_at=?2 WHERE operation_id=?3 AND state IN ('ambiguous','reconciling')",
+            [auditErrorReason(error), this.now(), input.operationId],
+          );
+          if (won.changes === 1) input.failed(error);
+        });
+      } catch {
+        this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, { code: "SIDE_THREAD_LOCAL_APPLY_FAILED" });
+        throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+      }
+      throw normalizePortError(error);
+    }
+    try {
+      this.store.db.transaction(() => {
+        const receipt = input.receipt(value);
+        const won = this.store.db.run(
+          "UPDATE side_chat_operations SET state='completed',thread_id=COALESCE(?1,thread_id),turn_id=COALESCE(?2,turn_id),error_code=NULL,updated_at=?3 WHERE operation_id=?4 AND state IN ('ambiguous','reconciling')",
+          [receipt.threadId ?? null, receipt.turnId ?? null, this.now(), input.operationId],
+        );
+        if (won.changes === 1) input.accepted(value);
+      });
+      return value;
+    } catch {
+      this.markAmbiguous(input.sideChatId, input.attemptId, input.operationId, { code: "SIDE_THREAD_LOCAL_APPLY_FAILED" });
+      throw ambiguousError(input.operationId, input.sideChatId, input.attemptId);
+    }
+  }
+
+  private applyLifecycleAccepted(sideChatId: string, action: "archive" | "purge", operationId: string, threadId: string): void {
+    const t = this.now();
+    if (action === "purge") {
+      this.store.db.run("UPDATE side_chats SET state='purged',question_text='',attachments_json='[]',lifecycle_operation=NULL,updated_at=?1,purged_at=?1 WHERE side_chat_id=?2 AND active_attempt_id IS NULL", [t, sideChatId]);
+      this.store.db.run("UPDATE side_chat_attempts SET result_text=NULL,error_text=NULL,attachments_json='[]',updated_at=?1 WHERE side_chat_id=?2", [t, sideChatId]);
+      this.store.db.run("UPDATE side_chat_bring_backs SET error_text=NULL,updated_at=?1 WHERE side_chat_id=?2", [t, sideChatId]);
+    } else {
+      this.store.db.run("UPDATE side_chats SET state='archived',lifecycle_operation=NULL,updated_at=?1,archived_at=?1 WHERE side_chat_id=?2 AND active_attempt_id IS NULL", [t, sideChatId]);
+    }
+    this.emitStored(sideChatId, undefined, threadId, undefined, `side_chat.${action === "archive" ? "archived" : "purged"}`, action === "archive" ? "archived" : "purged", undefined, t);
+  }
+
   listEvents(
     actor: SideThreadActor,
     sideChatId: string,
@@ -1983,14 +2215,19 @@ export class SideThreadCoordinator {
     sideChatId: string,
     attemptId: string,
     error: unknown,
+    operationId?: string,
   ): void {
     const t = this.now(),
       reason = safeReason(
         error instanceof Error ? error.message : String(error),
       );
     this.store.db.transaction(() => {
+      if (operationId)
+        this.settleOperation(operationId, "failed", {
+          errorCode: auditErrorReason(error),
+        });
       const changed = this.store.db.run(
-        "UPDATE side_chat_attempts SET state='failed',error_text=?1,updated_at=?2 WHERE attempt_id=?3 AND state='starting'",
+        "UPDATE side_chat_attempts SET state='failed',error_text=?1,updated_at=?2 WHERE attempt_id=?3 AND state IN ('starting','ambiguous','reconciling')",
         [reason, t, attemptId],
       );
       if (changed.changes > 0) {
@@ -2038,7 +2275,7 @@ export class SideThreadCoordinator {
       "SELECT event_id FROM side_chat_events WHERE side_chat_id=?1 ORDER BY event_id DESC LIMIT 1",
       sideChatId,
     );
-    this.emitter.emit(`side:${sideChatId}`, {
+    const event = {
       eventId: row?.event_id ?? 0,
       sideChatId,
       attemptId,
@@ -2048,7 +2285,19 @@ export class SideThreadCoordinator {
       state,
       reason: safeReason(reason),
       createdAt: at,
-    } satisfies SideThreadEventRecord);
+    } satisfies SideThreadEventRecord;
+    // Fanout is deliberately deferred until the current synchronous SQLite
+    // transaction has committed. Observers are never part of durable truth:
+    // one throwing listener cannot roll back state or starve another listener.
+    queueMicrotask(() => {
+      for (const listener of this.emitter.listeners(`side:${sideChatId}`)) {
+        try {
+          listener(event);
+        } catch {
+          // Durable side_chat_events + cursor replay are authoritative.
+        }
+      }
+    });
   }
   private mustOwned(
     sideChatId: string,
@@ -2239,3 +2488,8 @@ function normalizePortError(error: unknown): SideThreadError {
     502,
   );
 }
+function persistedOperationFailure(code: string | null | undefined): SideThreadError {
+  if (code === "SIDE_THREAD_UNSUPPORTED")
+    return new SideThreadError("SIDE_THREAD_UNSUPPORTED", "runtime operation is unsupported", 501);
+  return new SideThreadError(code === "SIDE_THREAD_CONFLICT" ? "SIDE_THREAD_CONFLICT" : "SIDE_THREAD_RUNTIME_ERROR", "runtime operation failed authoritatively", code === "SIDE_THREAD_CONFLICT" ? 409 : 502);
+}

package/src/tools.ts

@@ -1,9 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { parseDbTimestampMs } from "./db-timestamp.js";
 import { z } from "zod/v4";
 import { parseAliasFilter } from "./alias-filter.js";
 import { createHash } from "node:crypto";
 import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken, syncScheduledRunForTask } from "./db.js";
-import { getSSEStats, pushEvent, pushNetworkObserverEvent } from "./push.js";
+import { getSSEStats, hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { canRestWriteNetwork, getUserNetworkIds, singleNetworkId } from "./network-scope.js";
@@ -526,6 +527,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         config_revision: z.number().int().min(0).optional(),
         config_update_capable: z.boolean().optional(),
         peer_reply_inbox_capable: z.literal(true).optional(),
+        side_thread_capability: z.object({
+          supported: z.boolean(),
+          runtime: z.string().max(64),
+          runtimeVersion: z.string().max(64),
+          topology: z.string().max(64),
+          evidenceRevision: z.string().max(100),
+          mode: z.literal("native-exact-fork").optional(),
+          exactBoundary: z.object({ through: z.boolean(), before: z.boolean() }).strict().optional(),
+          reason: z.enum(["runtime", "version", "topology", "experimental-api", "exact-boundary"]).optional(),
+        }).strict().optional(),
         // RFC-026 P2 / #338 — daemon role surfaced for hub /api/nodes
         // discovery (#337 extracts this field). "host_supervisor" =
         // anet daemon. Default-stripping zod would drop this otherwise.
@@ -1419,12 +1430,17 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       let pendingSql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
       pendingSql = addScope(pendingSql, pendingParams, effectiveNetId);
       const pending = db.get<{ cnt: number }>(pendingSql, ...pendingParams);
-      if (target.state === "online") {
-        pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
-      }
+      // 🔴 不要用 last_seen_at 的时间戳去猜「有没有人在听」——SSE 订阅者注册表
+      // 就是那件事本身。pushEvent 在没有订阅者时已经是 no-op，所以这道闸不提供
+      // 任何保护，只会把**连着但最近没心跳**的会话排除掉；而全网「停发心跳/状态类
+      // 消息」的省额度规则让安静恰恰是常态。上面那段注释早就写着 "Push
+      // unconditionally"，同一类缺陷上次也是打在 Dashboard 任务上（f015d9d6：
+      // 任务标了 delivered，会话却从未收到推送）。
+      pushEvent(targetAlias, { type: "new_task", inbox_count: pending?.cnt ?? 1, priority, from: from_session, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
+      const actuallyDelivered = hasSubscribers(targetAlias, effectiveNetId);
       // #461 network observer summary — unconditional (task row exists
       // even when the target is offline/queued), metadata only.
-      pushNetworkObserverEvent(effectiveNetId, { type: "new_task", task_id: id, from: from_session, to: targetAlias, status: target.state === "online" ? "delivered" : "queued", priority });
+      pushNetworkObserverEvent(effectiveNetId, { type: "new_task", task_id: id, from: from_session, to: targetAlias, status: actuallyDelivered ? "delivered" : "queued", priority });
 
       if (target.state === "offline") {
         return {
@@ -1492,9 +1508,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         [id, targetAlias, target.session?.node_id ?? null, message, from_session, effectiveNetId ?? null]
       );
 
-      if (target.state === "online") {
-        pushEvent(targetAlias, { type: "new_message", from: from_session, message_id: id, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
-      }
+      // 同 send_task：可达性用订阅者注册表判，不用心跳时间戳猜。
+      pushEvent(targetAlias, { type: "new_message", from: from_session, message_id: id, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
 
       const offlineReply = deliveryTargetReply(target, { message_id: id });
       if (offlineReply) {
@@ -1524,7 +1539,15 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   // ── V2/V3 reply primitives ──
   const replyToolSchema = {
-      alias: z.string().min(1).max(200).describe("Target session alias"),
+      // #1085 — alias is OPTIONAL: when omitted (or empty) and `in_reply_to`
+      // is set, the hub derives the target from the original task's
+      // `from_name` (it already SELECTs that task by in_reply_to below).
+      // The SDK-runtime bridge (agent-node/src/commhub-mcp.ts) exposes
+      // send_reply as (task_id, text, status) with NO alias, so before this
+      // it always sent alias=undefined → -32602 "expected string, received
+      // undefined at alias". The target was already knowable from the task,
+      // so requiring the caller to pass it was a redundant-param trap.
+      alias: z.string().min(1).max(200).optional().describe("Target session alias — optional; derived from in_reply_to's task sender when omitted"),
       text: z.string().min(1).max(10000).describe("Reply content"),
       in_reply_to: z.string().max(200).optional().describe("Original task/message ID"),
       status: z.enum(["replied", "failed", "cancelled"]).optional().default("replied").describe("Task outcome"),
@@ -1575,9 +1598,29 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         : meta;
       const metaJson = normalizeMetaJson(mergedMeta);
 
-      const canonicalReplyTarget = resolveCanonicalAlias(effectiveNetId, alias);
+      // #1085 — derive the reply target when the caller omitted `alias`.
+      // The original task's `from_name` IS the reply target; the hub knows
+      // it from `in_reply_to`. Without this, an SDK-runtime send_reply
+      // (schema has no alias) died with -32602 before reaching this handler.
+      let effectiveAlias: string | undefined =
+        (typeof alias === "string" && alias.trim()) ? alias : undefined;
+      if (!effectiveAlias) {
+        if (!in_reply_to) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "reply_target_required", message: "alias omitted and no in_reply_to to derive it from" }) }] };
+        }
+        const derivParams: any[] = [in_reply_to];
+        let derivSql = "SELECT from_name FROM tasks WHERE task_id = ?1";
+        derivSql = addScope(derivSql, derivParams, effectiveNetId);
+        const derived = db.get<{ from_name: string }>(derivSql, ...derivParams);
+        if (!derived?.from_name) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "reply_target_unresolved", message: `alias omitted and could not derive target from in_reply_to (${in_reply_to})` }) }] };
+        }
+        effectiveAlias = derived.from_name;
+      }
+
+      const canonicalReplyTarget = resolveCanonicalAlias(effectiveNetId, effectiveAlias);
       const replyTargetAlias = canonicalReplyTarget.alias;
-      console.log(`[${ts()}] ${from_session} → send_reply (${replyStatus}) → ${replyTargetAlias}: ${text.slice(0, 60)}${attachmentsResult.attachments.length ? ` [+${attachmentsResult.attachments.length} attachments]` : ""}${canonicalReplyTarget.renamed ? ` [renamed from ${alias}]` : ""}`);
+      console.log(`[${ts()}] ${from_session} → send_reply (${replyStatus}) → ${replyTargetAlias}: ${text.slice(0, 60)}${attachmentsResult.attachments.length ? ` [+${attachmentsResult.attachments.length} attachments]` : ""}${canonicalReplyTarget.renamed ? ` [renamed from ${effectiveAlias}]` : ""}`);
       const id = uuidv4();
       const replyTargetNodeId = resolveNodeIdForAlias(replyTargetAlias, effectiveNetId);
       // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 3/6).
@@ -2767,7 +2810,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // schema-promoted columns runtimes_supported/allowed_secret_keys
       // are pre-extracted but role isn't a first-class column).
       const nowMs = Date.now();
-      const ONLINE_MS = 60_000;
+      // 心跳周期是 3 分钟（agent-node/src/cli.ts 的 report_status 定时器），
+      // 窗口必须大于它，否则每次心跳后的 60s~180s 之间必然抖成 offline
+      // （通信评审牛 #1279 独审④）。取 5min，与仓内既有 stale 口径一致。
+      const ONLINE_MS = 5 * 60_000;
       const daemons = rows
         .map(r => {
           let snapRole: string | null = null;
@@ -2786,7 +2832,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           let lastSeenAt: string | null = null;
           if (r.session_last_seen) {
             lastSeenAt = r.session_last_seen;
-            const t = Date.parse(r.session_last_seen);
+            const t = parseDbTimestampMs(r.session_last_seen);
             if (!isNaN(t)) online = (nowMs - t) <= ONLINE_MS;
           }
           // Parse self-declare arrays (default to [] for pre-PR2 daemons)