@adhdev/daemon-core 0.9.82-rc.459 → 0.9.82-rc.460

package/dist/mesh/contracts.d.ts

@@ -123,6 +123,15 @@ export interface PendingMeshCoordinatorEventV2 {
     readonly coordinatorMessage?: string;
     readonly queuedAt: number;
     readonly protocolVersion: MeshProtocolVersion;
+    /**
+     * Idempotency key. A UUID generated ONCE at emit time and preserved verbatim
+     * across every store (SQLite payload + column, JSONL) and the P2P relay
+     * boundary. The receiving drain uses eventId as the authoritative dedup key
+     * (B3): an event whose eventId was already drained is skipped even if its
+     * content fingerprint differs. Distinct from the content fingerprint, which
+     * stays the v1 dedup mechanism during rollout.
+     */
+    readonly eventId: string;
     readonly scope: MeshEventScope;
     readonly dispatchedBy: CoordinatorIdentity;
     /**
@@ -161,4 +170,61 @@ export declare function assertPendingMeshCoordinatorEventV2(raw: unknown, path?:
  * are quarantined to a dedicated drain endpoint instead.
  */
 export declare function shouldDeliverPendingEventToCoordinator(event: PendingMeshCoordinatorEventV2, drainer: CoordinatorIdentity): boolean;
+/**
+ * Default the v2 scope for an event by its producer event name (design decision
+ * §3). Terminal task events → unicast (routed to the originating coordinator).
+ * Ledger-consistency / dispatch-plane events → system. Everything else — node
+ * lifecycle and progress signals — → broadcast, which also matches v1's
+ * implicit "deliver to any coordinator" behaviour, so an unstamped v1 event and
+ * a v2-stamped-as-broadcast event route identically during rollout.
+ */
+export declare function defaultScopeForEvent(eventName: string): MeshEventScope;
+/**
+ * The v2 envelope stamp applied to a pending coordinator event at emit time.
+ * Additive over the v1 shape: every field is consulted by v2-aware drainers
+ * only, so a v1 reader that ignores them is unaffected.
+ */
+export interface PendingEventEmitStampV2 {
+    readonly protocolVersion: typeof MESH_PROTOCOL_VERSION_V2;
+    readonly eventId: string;
+    readonly scope: MeshEventScope;
+    readonly dispatchedBy: CoordinatorIdentity;
+    readonly intendedFor?: CoordinatorIdentity;
+}
+/**
+ * Build a coordinator identity from the loosely-typed fields the v1 emit call
+ * sites already carry (a daemonId, and — sometimes — a coordinator session id).
+ * Returns undefined when no usable daemonId is present; the caller then leaves
+ * the event unstamped (v1, broadcast-treated) rather than fabricating identity.
+ * coordinatorRunId is not known at every emit site yet (B2 wires the registry),
+ * so it falls back to the daemonId — a stable, non-empty value that keeps the
+ * identity well-formed for assertCoordinatorIdentity without inventing a UUID
+ * that would differ per emit and defeat equality.
+ */
+export declare function coordinatorIdentityFromEmitFields(fields: {
+    daemonId?: string | null;
+    coordinatorRunId?: string | null;
+    sessionId?: string | null;
+}): CoordinatorIdentity | undefined;
+/**
+ * Compute the v2 emit stamp for an event (B2a). `eventId` MUST be supplied by
+ * the caller (generated via crypto.randomUUID at the daemon-core boundary so
+ * this module stays dependency-free and deterministically testable). Scope
+ * defaults from the event name unless explicitly overridden.
+ *
+ * When `dispatchedBy` cannot be constructed (no coordinator daemon known),
+ * returns undefined: the event stays a v1 (unstamped) event and is broadcast-
+ * treated during rollout, exactly as before — no regression, no fabricated
+ * identity. When the resolved scope is 'unicast' but no `intendedFor` is
+ * available, the scope is downgraded to 'broadcast' so the stamp never violates
+ * the "unicast requires intendedFor" contract (a terminal event that cannot be
+ * addressed to its originator is safest delivered broadly, not dropped).
+ */
+export declare function buildPendingEventEmitStamp(opts: {
+    eventName: string;
+    eventId: string;
+    dispatchedBy?: CoordinatorIdentity;
+    intendedFor?: CoordinatorIdentity;
+    scope?: MeshEventScope;
+}): PendingEventEmitStampV2 | undefined;
 export {};

package/dist/mesh/coordinator-prompt.d.ts

@@ -39,8 +39,14 @@ export interface CoordinatorRecentActivity {
         /** Short task title/message, already truncated by the caller. */
         summary?: string;
     }>;
-    /** Count of task_failed entries inside the recent (30-min) window. */
+    /** Count of task_failed entries inside the recent window. */
     recentFailureCount?: number;
+    /**
+     * Size of the "recent" window in minutes. Drives the "failed in the last
+     * N min" phrasing. Omitted → defaults to 30, matching the prior hardcoded
+     * wording so existing callers render identically.
+     */
+    windowMinutes?: number;
     /** Pending (unclaimed) tasks in the work queue. */
     pendingTasks?: number;
     /** Assigned-but-not-yet-terminal tasks in the work queue. */
@@ -86,23 +92,4 @@ export interface CoordinatorPromptContext {
      */
     operatingNotes?: CoordinatorOperatingNote[];
 }
-/**
- * Compose the final coordinator prompt from four layers, in this precedence:
- *
- *   1. Per-launch `extraSystemPrompt` (always appended, as "## Additional
- *      Context"). Never wins as a base — it's launch-scope context.
- *   2. Mesh-level append (`mesh.coordinator.systemPromptAppend` or the legacy
- *      `systemPromptSuffix`). Stacks after whichever base won.
- *   3. User-file append (`~/.adhdev/coordinator-prompts/<cli>.append.md` or
- *      `default.append.md`). Also stacks; same placeholder expansion as the
- *      override path.
- *   4. Base prompt, picked in this order:
- *      a. `mesh.coordinator.systemPromptOverride` (mesh-level override)
- *      b. user-file override (`~/.adhdev/coordinator-prompts/<cli>.md` or
- *         `default.md`)
- *      c. daemon default (assembled from identity/nodes/policy/tools/…)
- *
- * That layering lets a user customize prompts at three increasing scopes
- * (machine, mesh, single launch) without losing the daemon's stock rules.
- */
 export declare function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string;

package/dist/mesh/mesh-events-pending.d.ts

@@ -1,3 +1,4 @@
+import { MESH_PROTOCOL_VERSION_V2, type CoordinatorIdentity, type MeshEventScope } from './contracts.js';
 export interface PendingMeshCoordinatorEvent {
     event: string;
     meshId: string;
@@ -23,13 +24,56 @@ export interface PendingMeshCoordinatorEvent {
      * the JSONL file without a dedicated column; it is NOT a drain-scoping key.
      */
     targetCoordinatorSessionId?: string;
+    /** '2.0' once stamped. Absent on v1 events. */
+    protocolVersion?: typeof MESH_PROTOCOL_VERSION_V2;
+    /** Idempotency key (UUID). The receiver's authoritative dedup key (B3). */
+    eventId?: string;
+    /** Routing scope. Defaulted from the event name unless the emit hint overrides. */
+    scope?: MeshEventScope;
+    /** Identity of the coordinator that dispatched the work this event reports. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Present only for unicast scope: the coordinator this event is addressed to. */
+    intendedFor?: CoordinatorIdentity;
+}
+/**
+ * Optional emit-time hint passed to queuePendingMeshCoordinatorEvent so a call
+ * site can override the name-defaulted scope or supply richer coordinator
+ * identity (e.g. a coordinatorRunId the base event fields don't carry). Every
+ * field is optional; when omitted the stamp is derived entirely from the
+ * event's own targetCoordinatorDaemonId / targetCoordinatorSessionId. Kept
+ * separate from the event so existing single-arg callers are untouched.
+ */
+export interface PendingEventEmitHint {
+    scope?: MeshEventScope;
+    /** Overrides the coordinator identity derived from the event's target fields. */
+    dispatchedBy?: CoordinatorIdentity;
+    /** Overrides the unicast target derived from the event's target fields. */
+    intendedFor?: CoordinatorIdentity;
+    /** coordinatorRunId to fold into the derived identity when the event lacks one. */
+    coordinatorRunId?: string;
 }
 export declare function readRefineJobId(event: {
     metadataEvent?: Record<string, unknown>;
 } | Record<string, unknown>): string;
 export declare function buildPendingEventFingerprint(event: PendingMeshCoordinatorEvent): string;
 export declare function hasPendingCoordinatorEventDuplicate(event: PendingMeshCoordinatorEvent): boolean;
-export declare function queuePendingMeshCoordinatorEvent(event: PendingMeshCoordinatorEvent): boolean;
+/**
+ * Stamp the v2 protocol envelope onto a pending event at emit time (B2a).
+ *
+ * Non-breaking: returns a NEW event object with protocolVersion/eventId/scope/
+ * dispatchedBy/intendedFor added when a coordinator identity can be derived,
+ * otherwise returns the input unchanged (a v1 event, broadcast-treated during
+ * rollout). Identity and the unicast target are derived from the event's own
+ * targetCoordinatorDaemonId / targetCoordinatorSessionId (already carried by
+ * every producer), so most call sites need no change; the optional `hint`
+ * overrides scope/identity where a site knows better.
+ *
+ * The eventId is generated here (randomUUID) exactly once, so re-queues that
+ * pass an already-stamped event keep their original eventId — the idempotency
+ * key is stable across re-delivery. An already-stamped event is returned as-is.
+ */
+export declare function stampPendingEventV2(event: PendingMeshCoordinatorEvent, hint?: PendingEventEmitHint): PendingMeshCoordinatorEvent;
+export declare function queuePendingMeshCoordinatorEvent(rawEvent: PendingMeshCoordinatorEvent, hint?: PendingEventEmitHint): boolean;
 /**
  * Drain and return pending coordinator events for meshId, removing the drained
  * ones from both the SQLite inbox and the JSONL legacy file.

package/dist/mesh/mesh-ledger.d.ts

@@ -14,6 +14,7 @@
  */
 import { EventEmitter } from 'events';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
+import { type MeshLedgerOriginatingCoordinatorV2 } from './contracts.js';
 export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis';
 export interface MeshLedgerEntry {
     id: string;
@@ -178,6 +179,23 @@ export declare function compactLedger(meshId: string): {
 };
 export declare function normalizeMeshWorkerResult(input?: Record<string, unknown>, source?: MeshWorkerResultArtifact['source']): MeshWorkerResultArtifact;
 export declare function buildTaskCompletionEvidence(opts: BuildTaskCompletionEvidenceOptions): MeshTaskCompletionEvidence;
+/**
+ * Build the v2 originating-coordinator stamp for a task_dispatched ledger entry
+ * (B2a / design decision §2). This is the source of truth from which a worker's
+ * completion emit later restores `dispatchedBy` — it records which coordinator
+ * dispatched the task, so the terminal event can be routed (unicast) back to it.
+ *
+ * Nested under `payload.originatingCoordinator`; additive, so existing readers
+ * of the task_dispatched payload are unaffected. Returns undefined when no
+ * coordinator daemon id is known (the pre-v2 path) so the caller omits the stamp
+ * entirely rather than writing a malformed identity — those entries stay v1 and
+ * are broadcast-treated during rollout.
+ */
+export declare function buildLedgerOriginatingCoordinatorStamp(fields: {
+    coordinatorDaemonId?: string | null;
+    coordinatorRunId?: string | null;
+    coordinatorSessionId?: string | null;
+}): MeshLedgerOriginatingCoordinatorV2 | undefined;
 /**
  * Append a new entry to the mesh ledger.
  * Handles file creation, rotation on size overflow, and atomic writes.

package/dist/mesh/mesh-queue-assignment.d.ts

@@ -52,6 +52,23 @@ export declare function __resolveSchedulingStrategyForTests(mesh: any): RepoMesh
 export declare function __orderEligibleNodesForTests(meshId: string, strategy: RepoMeshSchedulingStrategy, nodes: RankableNode[], opts?: {
     bumpCursor?: boolean;
 }): RankableNode[];
+/** One idle session eligible to claim a queued task, together with the resolved
+ *  mesh node record it belongs to. Local candidates come from live CLI instances,
+ *  remote candidates from the registered remote-idle-session store; the two arrive
+ *  with their `nodeId` under different serialization forms. */
+type IdleCandidate = {
+    nodeId: string;
+    sessionId: string;
+    providerType: string;
+    origin: 'local' | 'remote';
+    node: any;
+};
+/** Test-only: the pool-canonicalization + unique-node collapse stage. Exposed so
+ *  the mixed-form dedup invariant can be unit-tested without a live daemon. */
+export declare function __buildSchedulingPoolForTests(localCandidates: IdleCandidate[], remoteCandidates: IdleCandidate[]): {
+    pool: IdleCandidate[];
+    uniqueNodes: RankableNode[];
+};
 export declare function sessionHasActiveAssignment(meshId: string, sessionId: string): boolean;
 /**
  * CANON-IDENTITY single-flight hardening (restart-safe, observation-based).

package/dist/mesh/mesh-runtime-store.d.ts

@@ -1,4 +1,13 @@
 import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
+export interface MeshInflightHoldRow {
+    taskId: string;
+    meshId: string | null;
+    holdReason: string | null;
+    heldAt: number | null;
+    firstIdleSinceAck: number | null;
+    readFailureCount: number | null;
+    updatedAt: number | null;
+}
 export declare class MeshRuntimeStore {
     private static instance;
     private readonly db;
@@ -65,6 +74,18 @@ export declare class MeshRuntimeStore {
      * by for this pass). UPSERT keeps it lock-free across concurrent passes.
      */
     bumpSchedulerCursor(meshId: string): number;
+    private mapInflightHoldRow;
+    upsertInflightHold(entry: {
+        taskId: string;
+        meshId?: string | null;
+        holdReason?: string | null;
+        heldAt?: number | null;
+        firstIdleSinceAck?: number | null;
+        readFailureCount?: number | null;
+    }): void;
+    getInflightHold(taskId: string): MeshInflightHoldRow | null;
+    listInflightHoldsByMesh(meshId: string): MeshInflightHoldRow[];
+    deleteInflightHold(taskId: string): void;
     /**
      * Count active (status='assigned') tasks on a (node, provider) combination,
      * matched by the assignedProviderType stamped on the payload at claim time.
@@ -374,6 +395,11 @@ export declare class MeshRuntimeStore {
         payload?: unknown;
         fingerprint?: string | null;
         queuedAt: number;
+        protocolVersion?: string | null;
+        eventId?: string | null;
+        scope?: string | null;
+        dispatchedBy?: string | null;
+        intendedFor?: string | null;
     }): boolean;
     /**
      * Drain undrained pending events for a mesh, atomically marking them drained.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.459",
+  "version": "0.9.82-rc.460",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,7 @@
     "build": "tsup && npm run build:types",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly --declaration --declarationMap false",
     "dev": "tsup --watch --no-clean",
+    "lint": "eslint \"src/mesh/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json"
@@ -46,8 +47,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.459",
-    "@adhdev/session-host-core": "0.9.82-rc.459",
+    "@adhdev/mesh-shared": "0.9.82-rc.460",
+    "@adhdev/session-host-core": "0.9.82-rc.460",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -67,8 +68,10 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
+    "eslint": "^9.39.4",
     "tsup": "^8.2.0",
     "typescript": "^5.5.0",
+    "typescript-eslint": "^8.62.0",
     "vitest": "^4.1.3"
   },
   "repository": {

package/src/commands/router-refine.ts

@@ -131,7 +131,14 @@ export function queueRefineJobEvent(self: DaemonCommandRouter, event: 'refine:ac
 
 export async function appendRefineJobLedger(self: DaemonCommandRouter, kind: 'task_dispatched' | 'task_completed' | 'task_failed', handle: MeshRefineJobHandle, result?: Record<string, unknown>): Promise<void> {
         try {
-            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+            const { appendLedgerEntry, buildLedgerOriginatingCoordinatorStamp } = await import('../mesh/mesh-ledger.js');
+            // B2a: on dispatch, stamp the originating coordinator so a later completion
+            // emit can restore `dispatchedBy` and route the terminal event back (unicast).
+            // Refine jobs carry only a coordinator DAEMON id (no session), which is enough
+            // to route to the daemon-level coordinator. Absent → omitted (v1 entry).
+            const originatingStamp = kind === 'task_dispatched'
+                ? buildLedgerOriginatingCoordinatorStamp({ coordinatorDaemonId: handle.targetCoordinatorDaemonId })
+                : undefined;
             appendLedgerEntry(handle.meshId, {
                 kind,
                 nodeId: handle.targetNodeId,
@@ -152,6 +159,7 @@ export async function appendRefineJobLedger(self: DaemonCommandRouter, kind: 'ta
                     },
                     async: true,
                     retryOfJobId: handle.retryOfJobId,
+                    ...(originatingStamp ? { originatingCoordinator: originatingStamp } : {}),
                     ...(result ? {
                         success: result.success === true,
                         result,
@@ -1395,7 +1403,11 @@ export async function appendRefineBatchJobLedger(self: DaemonCommandRouter,
         result?: Record<string, unknown>,
     ): Promise<void> {
         try {
-            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+            const { appendLedgerEntry, buildLedgerOriginatingCoordinatorStamp } = await import('../mesh/mesh-ledger.js');
+            // B2a: stamp the originating coordinator on dispatch (see appendRefineJobLedger).
+            const originatingStamp = kind === 'task_dispatched'
+                ? buildLedgerOriginatingCoordinatorStamp({ coordinatorDaemonId: handle.targetCoordinatorDaemonId })
+                : undefined;
             appendLedgerEntry(handle.meshId, {
                 kind,
                 nodeId: handle.batchLabel,
@@ -1415,6 +1427,7 @@ export async function appendRefineBatchJobLedger(self: DaemonCommandRouter,
                     },
                     async: true,
                     batch: true,
+                    ...(originatingStamp ? { originatingCoordinator: originatingStamp } : {}),
                     ...(result ? {
                         success: result.success === true,
                         result,

package/src/mesh/contracts.ts

@@ -193,6 +193,15 @@ export interface PendingMeshCoordinatorEventV2 {
 
   // v2 additions
   readonly protocolVersion: MeshProtocolVersion;
+  /**
+   * Idempotency key. A UUID generated ONCE at emit time and preserved verbatim
+   * across every store (SQLite payload + column, JSONL) and the P2P relay
+   * boundary. The receiving drain uses eventId as the authoritative dedup key
+   * (B3): an event whose eventId was already drained is skipped even if its
+   * content fingerprint differs. Distinct from the content fingerprint, which
+   * stays the v1 dedup mechanism during rollout.
+   */
+  readonly eventId: string;
   readonly scope: MeshEventScope;
   readonly dispatchedBy: CoordinatorIdentity;
   /**
@@ -264,6 +273,9 @@ export function assertPendingMeshCoordinatorEventV2(raw: unknown, path = '$'): P
   if (!isSupportedMeshProtocolVersion(obj.protocolVersion)) {
     throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.protocolVersion`, `must be one of ${SUPPORTED_MESH_PROTOCOL_VERSIONS.join(', ')}`);
   }
+  if (!isNonEmptyString(obj.eventId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.eventId`, 'must be a non-empty string');
+  }
   if (!isMeshEventScope(obj.scope)) {
     throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.scope`, `must be one of ${MESH_EVENT_SCOPES.join(', ')}`);
   }
@@ -307,6 +319,7 @@ export function assertPendingMeshCoordinatorEventV2(raw: unknown, path = '$'): P
     coordinatorMessage: typeof obj.coordinatorMessage === 'string' ? obj.coordinatorMessage : undefined,
     queuedAt,
     protocolVersion: obj.protocolVersion,
+    eventId: obj.eventId,
     scope: obj.scope,
     dispatchedBy,
     ...(intendedFor ? { intendedFor } : {}),
@@ -336,3 +349,121 @@ export function shouldDeliverPendingEventToCoordinator(
   if (!event.intendedFor) return false;
   return coordinatorIdentityEquals(event.intendedFor, drainer);
 }
+
+// ─── Emit-side scope defaulting (B2a) ────────────────────────────────────────
+
+/**
+ * Terminal task events. In v2 these are unicast: a completion/failure/approval
+ * belongs to exactly the coordinator (session) that dispatched the task, so
+ * delivering it to a sibling coordinator on the same daemon is a routing bug.
+ * The names match the v1 producer event strings queued by the emit call sites
+ * (mesh-event-forwarding, mesh-events-stale, router-refine).
+ */
+const TERMINAL_TASK_EVENTS: ReadonlySet<string> = new Set([
+  'agent:generating_completed',
+  'agent:stopped',
+  'refine:completed',
+  'refine:failed',
+  'refine:accepted',
+]);
+
+/**
+ * Infrastructure/system events that no coordinator should surface — ledger
+ * consistency and dispatch-plane signals. Delivered to the daemon-level handler
+ * only (scope 'system').
+ */
+const SYSTEM_EVENTS: ReadonlySet<string> = new Set([
+  'mesh:dispatch_blocked',
+]);
+
+/**
+ * Default the v2 scope for an event by its producer event name (design decision
+ * §3). Terminal task events → unicast (routed to the originating coordinator).
+ * Ledger-consistency / dispatch-plane events → system. Everything else — node
+ * lifecycle and progress signals — → broadcast, which also matches v1's
+ * implicit "deliver to any coordinator" behaviour, so an unstamped v1 event and
+ * a v2-stamped-as-broadcast event route identically during rollout.
+ */
+export function defaultScopeForEvent(eventName: string): MeshEventScope {
+  if (SYSTEM_EVENTS.has(eventName)) return 'system';
+  if (TERMINAL_TASK_EVENTS.has(eventName)) return 'unicast';
+  return 'broadcast';
+}
+
+/**
+ * The v2 envelope stamp applied to a pending coordinator event at emit time.
+ * Additive over the v1 shape: every field is consulted by v2-aware drainers
+ * only, so a v1 reader that ignores them is unaffected.
+ */
+export interface PendingEventEmitStampV2 {
+  readonly protocolVersion: typeof MESH_PROTOCOL_VERSION_V2;
+  readonly eventId: string;
+  readonly scope: MeshEventScope;
+  readonly dispatchedBy: CoordinatorIdentity;
+  readonly intendedFor?: CoordinatorIdentity;
+}
+
+/**
+ * Build a coordinator identity from the loosely-typed fields the v1 emit call
+ * sites already carry (a daemonId, and — sometimes — a coordinator session id).
+ * Returns undefined when no usable daemonId is present; the caller then leaves
+ * the event unstamped (v1, broadcast-treated) rather than fabricating identity.
+ * coordinatorRunId is not known at every emit site yet (B2 wires the registry),
+ * so it falls back to the daemonId — a stable, non-empty value that keeps the
+ * identity well-formed for assertCoordinatorIdentity without inventing a UUID
+ * that would differ per emit and defeat equality.
+ */
+export function coordinatorIdentityFromEmitFields(fields: {
+  daemonId?: string | null;
+  coordinatorRunId?: string | null;
+  sessionId?: string | null;
+}): CoordinatorIdentity | undefined {
+  const daemonId = typeof fields.daemonId === 'string' && fields.daemonId.length > 0 ? fields.daemonId : undefined;
+  if (!daemonId) return undefined;
+  const coordinatorRunId = typeof fields.coordinatorRunId === 'string' && fields.coordinatorRunId.length > 0
+    ? fields.coordinatorRunId
+    : daemonId;
+  const sessionId = typeof fields.sessionId === 'string' && fields.sessionId.length > 0 ? fields.sessionId : undefined;
+  return sessionId !== undefined
+    ? { daemonId, coordinatorRunId, sessionId }
+    : { daemonId, coordinatorRunId };
+}
+
+/**
+ * Compute the v2 emit stamp for an event (B2a). `eventId` MUST be supplied by
+ * the caller (generated via crypto.randomUUID at the daemon-core boundary so
+ * this module stays dependency-free and deterministically testable). Scope
+ * defaults from the event name unless explicitly overridden.
+ *
+ * When `dispatchedBy` cannot be constructed (no coordinator daemon known),
+ * returns undefined: the event stays a v1 (unstamped) event and is broadcast-
+ * treated during rollout, exactly as before — no regression, no fabricated
+ * identity. When the resolved scope is 'unicast' but no `intendedFor` is
+ * available, the scope is downgraded to 'broadcast' so the stamp never violates
+ * the "unicast requires intendedFor" contract (a terminal event that cannot be
+ * addressed to its originator is safest delivered broadly, not dropped).
+ */
+export function buildPendingEventEmitStamp(opts: {
+  eventName: string;
+  eventId: string;
+  dispatchedBy?: CoordinatorIdentity;
+  intendedFor?: CoordinatorIdentity;
+  scope?: MeshEventScope;
+}): PendingEventEmitStampV2 | undefined {
+  if (!opts.dispatchedBy) return undefined;
+  let scope: MeshEventScope = opts.scope ?? defaultScopeForEvent(opts.eventName);
+  let intendedFor = opts.intendedFor;
+  if (scope === 'unicast' && !intendedFor) {
+    // No addressable target for a unicast event — fall back to broadcast so the
+    // stamp is contract-valid and the event is still delivered (never dropped).
+    scope = 'broadcast';
+  }
+  if (scope !== 'unicast') intendedFor = undefined;
+  return {
+    protocolVersion: MESH_PROTOCOL_VERSION_V2,
+    eventId: opts.eventId,
+    scope,
+    dispatchedBy: opts.dispatchedBy,
+    ...(intendedFor ? { intendedFor } : {}),
+  };
+}