@adhdev/daemon-core 0.9.82-rc.354 → 0.9.82-rc.356

package/dist/mesh/mesh-event-trace.d.ts

@@ -0,0 +1,21 @@
+export interface MeshEventTraceCtx {
+    /** Primary correlation anchor — the mesh task id (meshActiveTaskId / metadataEvent.taskId). */
+    taskId?: unknown;
+    /** Optional per-event id when the producer assigns one. */
+    eventId?: unknown;
+    /** Worker session id — the fallback anchor when no task is attached. */
+    sessionId?: unknown;
+    nodeId?: unknown;
+    meshId?: unknown;
+    event?: unknown;
+}
+/**
+ * Stable, greppable correlation key. `task=` and `sess=` are ALWAYS rendered (as `-`
+ * when absent) so the key shape is uniform across stages and a single grep alternation
+ * (`task=<id>\|sess=<id>`) follows the event end-to-end.
+ */
+export declare function meshEventTraceKey(ctx: MeshEventTraceCtx): string;
+/** Lifecycle progress (INFO). One line per stage the event clears. */
+export declare function traceMeshEventStage(stage: string, ctx: MeshEventTraceCtx, detail?: string): void;
+/** Event did not advance — rejected / held / skipped / deduped (WARN). */
+export declare function traceMeshEventDrop(reason: string, ctx: MeshEventTraceCtx, detail?: string): void;

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

@@ -129,7 +129,7 @@ export declare class MeshRuntimeStore {
         dispatchedAt: string;
         updatedAt: string;
     }>;
-    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+    updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale', taskId?: string): void;
     cleanupTerminalDirectDispatches(olderThanMs: number): void;
     deleteDirectDispatches(meshId: string): void;
     /**

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

@@ -320,7 +320,7 @@ export declare function insertDirectDispatch(meshId: string, data: {
     dispatchedAt: string;
 }): void;
 export declare function getActiveDirectDispatches(meshId: string): DirectDispatchRecord[];
-export declare function updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
+export declare function updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale', taskId?: string): void;
 export declare function cleanupTerminalDirectDispatches(olderThanMs?: number): void;
 export declare function markStaleDirectDispatches(meshId: string, olderThanMs?: number): void;
 /**

package/dist/providers/cli-provider-instance.d.ts

@@ -184,6 +184,8 @@ export declare class CliProviderInstance implements ProviderInstance {
     private shouldSuppressStaleParsedBusyStatus;
     private getCompletedFinalizationBlock;
     private scheduleCompletedDebounceFlush;
+    private isMeshWorkerSession;
+    private meshTraceCtx;
     private flushCompletedDebounceIfFinalized;
     private maybeAutoApproveStatus;
     /**

package/dist/providers/spec/adapter.d.ts

@@ -33,6 +33,21 @@ export interface TerminalAdapterHandlers {
     }): void;
     tick?(): void;
 }
+/**
+ * One entry in the PTY input/output event timeline (debug-only). Captured at
+ * the single common point every spec@4 provider funnels through — this adapter
+ * — so the Spec Debug Snapshot can answer "what input / output preceded a status
+ * transition?". Observation only; nothing here feeds the FSM decision.
+ */
+export interface SpecPtyEvent {
+    /** Wall-clock ms. */
+    ts: number;
+    kind: 'spawn' | 'input' | 'output' | 'resize' | 'cursor' | 'exit';
+    /** Human-readable, control-char-escaped, length-capped preview. */
+    content: string;
+    /** Raw byte length before truncation (output/input only). */
+    bytes?: number;
+}
 export declare class TerminalAdapter {
     private readonly opts;
     private readonly handlers;
@@ -46,6 +61,9 @@ export declare class TerminalAdapter {
     private screenTimer;
     private tickTimer;
     private lastScreen;
+    /** Debug-only ring buffer of PTY input/output/resize/cursor events. */
+    private events;
+    private lastCursorKey;
     constructor(opts: TerminalAdapterOpts, handlers: TerminalAdapterHandlers);
     start(): void;
     resize(cols: number, rows: number): void;
@@ -62,6 +80,10 @@ export declare class TerminalAdapter {
         col: number;
     };
     send_keys(text: string): void;
+    /** Debug-only: most-recent PTY input/output/resize/cursor events, oldest
+     *  first. Pure observation — never consulted by the FSM. */
+    getEventTimeline(limit?: number): SpecPtyEvent[];
+    private recordEvent;
     kill(): void;
     private onChunk;
     private computeScreen;

package/dist/providers/spec/cli-adapter.d.ts

@@ -121,6 +121,12 @@ export declare class SpecCliAdapter implements CliAdapter {
      * — not this code — decides how a selection is keyed for each CLI.
      */
     private selectPickerChoice;
+    /** Parse the picker choices only if the picker already appears rendered on
+     *  the live screen (its `wait_for` condition currently matches and at least
+     *  one choice parses). Returns the parsed choices when open, else null so
+     *  the caller knows it must send the trigger to open it. Used to de-dup the
+     *  picker open in {@link selectPickerChoice}. */
+    private extractPickerChoicesIfRendered;
     /** Poll the live screen until the picker's `wait_for` condition matches,
      *  up to a short budget. Returns true if it rendered, false on timeout. */
     private waitForPickerRendered;

package/dist/providers/spec/evaluator.d.ts

@@ -20,4 +20,5 @@ export declare function extractButtonsFromRule(rule: ExtractButtons, hay: string
     index: number;
     label: string;
     key: string;
+    current: boolean;
 }[];

package/dist/providers/spec/fsm-driver.d.ts

@@ -1,3 +1,4 @@
+import { type SpecPtyEvent } from './adapter.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
 import { type TraceEntry } from './evaluator.js';
 import { type TransitionEval } from './fsm-evaluator.js';
@@ -139,6 +140,7 @@ export interface ISpecDriver {
     } | null;
     getFsmDebug?(): unknown;
     getFsmSnapshotHistory?(): ReadonlyArray<FsmSnapshotEntry>;
+    getEventTimeline?(limit?: number): ReadonlyArray<SpecPtyEvent>;
 }
 export interface SpecDriverOpts {
     specPath: string;
@@ -152,6 +154,10 @@ export interface SpecDriverOpts {
     extraCliArgs?: string[];
 }
 export declare function resolveSubmitDelayMs(specBeforeSubmit: number | undefined, text: string): number;
+/** Split `text` into chunks of at most `size` UTF-16 units without ever cutting
+ *  between a high and low surrogate (which would corrupt an astral char — emoji,
+ *  etc. — on the UTF-8 PTY write). */
+export declare function chunkPreservingSurrogates(text: string, size: number): string[];
 export declare function guessExt(mime: string): string;
 type HistoryEntry = DriverHistoryEntry;
 export declare class FsmDriver implements ISpecDriver {
@@ -181,6 +187,16 @@ export declare class FsmDriver implements ISpecDriver {
      *  WIN32_SUBMIT_* and scheduleWin32Submit). Re-arms itself until the FSM
      *  leaves idle (submitted) or the resend budget is spent. */
     private win32SubmitTimer;
+    /** Wall-clock (ms) of the most recent raw PTY output chunk. Advances on every
+     *  on_pty_data — including the echo of text written into the composer — so the
+     *  win32 submit settle-gate can tell when input has finished landing. */
+    private lastPtyDataAt;
+    /** Wall-clock (ms) of the most recent win32 message-body input write. Bridges
+     *  the gap between writing a chunk and its echo so the settle-gate does not
+     *  declare "quiet" mid-write. */
+    private lastWin32WriteAt;
+    /** Pending paced chunk-write timer for a large win32 body (see writeWin32Body). */
+    private win32WriteTimer;
     private currentEval;
     private stateHistory;
     private prevStateAt;
@@ -230,6 +246,8 @@ export declare class FsmDriver implements ISpecDriver {
     };
     getStateHistory(): ReadonlyArray<HistoryEntry>;
     getFsmSnapshotHistory(): ReadonlyArray<FsmSnapshotEntry>;
+    /** Debug-only PTY input/output/resize/cursor timeline from the adapter. */
+    getEventTimeline(limit?: number): ReadonlyArray<SpecPtyEvent>;
     getSections(): Array<{
         id: string;
         text: string;
@@ -300,14 +318,38 @@ export declare class FsmDriver implements ISpecDriver {
     private actuallySendMessage;
     /** The agent's current coarse status, derived from the FSM node we're in. */
     private currentStatus;
+    /** Record a win32 body write so the settle-gate counts it as input activity
+     *  even before the echo arrives. */
+    private markWin32Write;
+    /** Most recent win32 input activity — a write we issued OR a PTY output chunk
+     *  (echo). The submit settle-gate waits for this to go quiet. */
+    private lastWin32InputActivityAt;
     /**
-     * win32 verification-based submit. Sends the submit key, waits a gap, and if
-     * the FSM is still 'idle' (the prompt did not submit — the CR was absorbed as
-     * a multiline-paste newline) resends, up to WIN32_SUBMIT_MAX_RESENDS. The
-     * first CR always fires (so a stale/edge status never suppresses the submit);
-     * subsequent resends are gated on still being idle, and stop the instant the
-     * agent leaves idle (submitted → generating / approval). This converges the
-     * nondeterministic multiline window without spamming Enter into the next turn.
+     * Write the message body to the PTY for win32, paced into bounded chunks. A
+     * single unbounded ConPTY write can overflow the input pipe and drop leading
+     * bytes; splitting it with a short inter-chunk gap keeps the console input
+     * buffer from overflowing. Small bodies still go out in a single write. Each
+     * chunk advances lastWin32WriteAt so the submit settle-gate keeps waiting until
+     * the final chunk is out and echoed.
+     */
+    private writeWin32Body;
+    /**
+     * win32 submit. Two phases:
+     *
+     *  Phase 1 (settle-gate): hold the first CR until the PTY output has been quiet
+     *  for WIN32_SUBMIT_SETTLE_MS after the last input write — i.e. the full
+     *  (possibly multi-KB / multiline) body has finished arriving in the composer
+     *  and echoing. Honors an initial minimum delay and is bounded by
+     *  WIN32_SUBMIT_MAX_SETTLE_WAIT_MS so a noisy screen can never hang the submit.
+     *  This is what stops a long message from being submitted half-arrived (its
+     *  leading lines lost). A short message settles almost immediately.
+     *
+     *  Phase 2 (verified resend — unchanged): send the submit key, wait a gap, and
+     *  if the FSM is still 'idle' (the CR was absorbed as a multiline-paste
+     *  newline) resend, up to WIN32_SUBMIT_MAX_RESENDS. The first CR always fires
+     *  (a stale/edge status never suppresses it); resends are gated on still being
+     *  idle and stop the instant the agent leaves idle (submitted → generating /
+     *  approval). This preserves the win32 lone-CR-swallow handling.
      */
     private scheduleWin32Submit;
     private handleClickControl;

package/dist/providers/spec/fsm-evaluator.d.ts

@@ -19,6 +19,10 @@ export interface CondResult {
     /** Remaining ms until a time-based condition would flip to true. 0 if
      *  already true or not applicable. Lets the UI show a countdown. */
     remainingMs?: number;
+    /** Debug-only: the actual substring a TRUE regex condition matched, so the
+     *  snapshot shows WHAT text the rule fired on — not just which regex. Never
+     *  read by the FSM; purely for the Spec Debug Snapshot. */
+    matchedText?: string;
     children?: CondResult[];
 }
 /** One evaluated transition with its full reasoning. */

package/dist/providers/spec/types.d.ts

@@ -19,6 +19,24 @@ export type ControlAction = {
     wait_for: WaitForCondition;
     extract_choices: SectionPattern;
     submit_key: string;
+    /**
+     * How a parsed choice is committed once the picker is open.
+     *   'index' (default) — type the on-screen number then `submit_key`
+     *     (`{index}\r`). Correct for CLIs whose picker is number-selectable
+     *     (codex-cli, hermes-cli).
+     *   'arrow_keys' — the picker is a cursor list that ignores number keys
+     *     (claude-cli /model): move the cursor from its current row to the
+     *     target row with up/down arrows, then confirm with the `submit_key`
+     *     tail (the `\r` left after stripping `{index}`). Requires the
+     *     extracted choices to flag the current cursor row.
+     */
+    select_mode?: 'index' | 'arrow_keys';
+    /** Arrow byte sequences for `select_mode: 'arrow_keys'`. Defaults to
+     *  ANSI cursor up/down (`` / ``) when omitted. */
+    cursor_keys?: {
+        up: string;
+        down: string;
+    };
 } | {
     type: 'attach_image';
     method: 'tempfile_then_keys';
@@ -123,11 +141,15 @@ export interface SectionDef {
     until?: string;
     /**
      * Anchor regex(es). A single string anchors on the first/last matching line
-     * (per `anchor_last`). An array is an OR-set: every candidate line is one
-     * that matches ANY entry; with `anchor_last` the LAST such line across all
-     * patterns wins, otherwise the FIRST. This lets one section capture two
-     * different shapes — e.g. a box-divider modal AND a divider-less modal whose
-     * only stable landmark is the question line above its numbered choices.
+     * (per `anchor_last`). An array is an OR-set of candidate shapes: each
+     * candidate resolves its OWN anchor line independently (anchor_last → that
+     * candidate's last matching line, else its first), then the TOPMOST resolved
+     * line across candidates wins — a section's anchor marks the top of its
+     * block, so the highest recognized landmark bounds the whole block. This
+     * lets one section capture two shapes — e.g. a box-divider modal AND a
+     * divider-less modal whose only stable landmark is the question line above
+     * its numbered choices — while preventing a stray LOWER landmark (e.g. an
+     * input-box `────` rule below the choices) from clipping the block.
      */
     anchor?: string | string[];
     anchor_flags?: string;
@@ -177,4 +199,24 @@ export interface ExtractButtons {
     key_for_index: string;
     min_count?: number;
     continuation_lines?: boolean;
+    /**
+     * How a button is committed when its modal is resolved (auto-approve or an
+     * explicit dashboard click).
+     *   'index' (default) — send `key_for_index` with `{index}` filled in
+     *     (`{index}\r` → `1\r`). Correct for modals whose buttons are
+     *     number-selectable (codex, hermes, antigravity number rows).
+     *   'arrow_keys' — the modal is a cursor list that IGNORES number keys
+     *     (claude-cli's new TUI approval modal): a typed `1` leaks into the
+     *     composer as literal text and `\r` submits it. Instead move the cursor
+     *     from its current row to the target row with up/down arrows, then
+     *     confirm with the `key_for_index` tail (the `\r` left after stripping
+     *     `{index}`). Mirrors the `open_picker` `select_mode` of the same name.
+     */
+    select_mode?: 'index' | 'arrow_keys';
+    /** Arrow byte sequences for `select_mode: 'arrow_keys'`. Defaults to ANSI
+     *  cursor up/down (`[A` / `[B`) when omitted. */
+    cursor_keys?: {
+        up: string;
+        down: string;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.354",
+  "version": "0.9.82-rc.356",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.354",
+    "@adhdev/mesh-shared": "0.9.82-rc.356",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/router.ts

@@ -8110,7 +8110,10 @@ export class DaemonCommandRouter {
                 // _meshDirectDispatch prevents re-forwarding (and P2P self-dial) when the stored
                 // daemonId uses a legacy format that doesn't match the receiving daemon's identity.
                 const selfDaemonId = this.deps.statusInstanceId;
-                const isRemote = nodeDaemonId && selfDaemonId && nodeDaemonId !== selfDaemonId;
+                // daemonIdsEquivalent: a legacy-form stored daemonId that resolves to THIS
+                // machine's core must be treated as local (not remote) so it is not forwarded /
+                // P2P self-dialed. Equivalent → local.
+                const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
                 if (isRemote && this.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
                     const forwarded = await this.deps.dispatchMeshCommand(nodeDaemonId!, 'fast_forward_mesh_node', {
                         ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
@@ -8154,7 +8157,9 @@ export class DaemonCommandRouter {
                 // once the call lands on the owning daemon — that daemon then reads
                 // its own logs even if the stored daemonId uses a legacy form.
                 const selfDaemonId = this.deps.statusInstanceId;
-                const isRemote = nodeDaemonId && selfDaemonId && nodeDaemonId !== selfDaemonId;
+                // daemonIdsEquivalent: a legacy-form daemonId resolving to this machine's core is
+                // local — read locally instead of forwarding. Equivalent → local.
+                const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
                 if (isRemote && this.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
                     const forwarded = await this.deps.dispatchMeshCommand(nodeDaemonId!, 'get_mesh_node_logs', {
                         ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
@@ -8230,7 +8235,9 @@ export class DaemonCommandRouter {
                     const forwardNode = meshRecordForForward?.mesh?.nodes?.find((n: any) => meshNodeIdMatches(n, nodeId));
                     const nodeDaemonId = typeof forwardNode?.daemonId === 'string' ? forwardNode.daemonId.trim() : undefined;
                     const selfDaemonId = this.deps.statusInstanceId;
-                    const isRemote = nodeDaemonId && selfDaemonId && nodeDaemonId !== selfDaemonId;
+                    // daemonIdsEquivalent: a legacy-form daemonId resolving to this machine's core
+                    // is local — execute locally instead of forwarding. Equivalent → local.
+                    const isRemote = nodeDaemonId && selfDaemonId && !daemonIdsEquivalent(nodeDaemonId, selfDaemonId);
                     if (isRemote && this.deps.dispatchMeshCommand && !args?._meshDirectDispatch) {
                         const callerCoordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
                             ? args.coordinatorDaemonId.trim()
@@ -8347,7 +8354,9 @@ export class DaemonCommandRouter {
                     let worktreeCleanup: Record<string, unknown> | undefined;
                     if (node?.isLocalWorktree) {
                         const nodeDaemonId = typeof node.daemonId === 'string' ? node.daemonId.trim() : undefined;
-                        const isRemoteWorktree = nodeDaemonId && nodeDaemonId !== this.deps.statusInstanceId && this.deps.dispatchMeshCommand
+                        // daemonIdsEquivalent: an equivalent-form daemonId is this machine —
+                        // clean up locally, do not forward. Equivalent → local.
+                        const isRemoteWorktree = nodeDaemonId && !daemonIdsEquivalent(nodeDaemonId, this.deps.statusInstanceId) && this.deps.dispatchMeshCommand
                             && !args?._meshDirectDispatch;
                         if (isRemoteWorktree) {
                             // Worktree lives on a different machine — ask that daemon to clean it up.
@@ -8473,7 +8482,9 @@ export class DaemonCommandRouter {
                     // _meshDirectDispatch prevents infinite re-forwarding when the stored daemonId
                     // uses a legacy format that doesn't match the receiving daemon's statusInstanceId.
                     const sourceDaemonId = typeof sourceNode.daemonId === 'string' ? sourceNode.daemonId.trim() : undefined;
-                    if (sourceDaemonId && sourceDaemonId !== this.deps.statusInstanceId && this.deps.dispatchMeshCommand
+                    // daemonIdsEquivalent: an equivalent-form source daemonId is this machine —
+                    // clone locally, do not forward. Equivalent → local.
+                    if (sourceDaemonId && !daemonIdsEquivalent(sourceDaemonId, this.deps.statusInstanceId) && this.deps.dispatchMeshCommand
                         && !args?._meshDirectDispatch) {
                         const forwarded = await this.deps.dispatchMeshCommand(sourceDaemonId, 'clone_mesh_node', {
                             ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),
@@ -8748,7 +8759,9 @@ export class DaemonCommandRouter {
                     // Bootstrap runs scripts in the worktree path — forward to the node's daemon if remote.
                     // _meshDirectDispatch prevents re-forwarding when stored daemonId uses legacy format.
                     const nodeDaemonId = typeof node.daemonId === 'string' ? node.daemonId.trim() : undefined;
-                    if (nodeDaemonId && nodeDaemonId !== this.deps.statusInstanceId && this.deps.dispatchMeshCommand
+                    // daemonIdsEquivalent: an equivalent-form daemonId is this machine —
+                    // bootstrap locally, do not forward. Equivalent → local.
+                    if (nodeDaemonId && !daemonIdsEquivalent(nodeDaemonId, this.deps.statusInstanceId) && this.deps.dispatchMeshCommand
                         && !args?._meshDirectDispatch) {
                         const forwarded = await this.deps.dispatchMeshCommand(nodeDaemonId, 'retry_mesh_node_bootstrap', {
                             ...(typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}),

package/src/mesh/mesh-event-trace.ts

@@ -0,0 +1,67 @@
+/**
+ * EVTTRACE — observation-only lifecycle tracing for mesh completion events.
+ *
+ * Pure logging. This module adds NO decision logic: every call site is a bare log
+ * statement inserted ALONGSIDE (never replacing) the existing control flow. Its only
+ * job is to make a single completion event greppable across its whole lifecycle by a
+ * stable correlation key, and to mark — with one uniform anchor — every point where
+ * such an event is rejected / held / skipped / deduped.
+ *
+ * grep anchors:
+ *   [EvtTrace] [stage:<name>]   — lifecycle progressed a step (INFO)
+ *   [EvtTrace] [drop:<reason>]  — event did NOT advance here, with the reason (WARN)
+ *
+ * Follow one completion: grep the daemon log for its `task=<id>` (or `sess=<id>`)
+ * across the [stage:*] lines; the line with [drop:*] is where it died.
+ *
+ * Dependency-light on purpose (only the logger) so both providers/ and mesh/ can
+ * import it without any cycle risk.
+ */
+import { LOG } from '../logging/logger.js';
+
+const CAT = 'EvtTrace';
+
+function s(v: unknown): string {
+    return typeof v === 'string' && v.trim() ? v.trim() : '';
+}
+
+export interface MeshEventTraceCtx {
+    /** Primary correlation anchor — the mesh task id (meshActiveTaskId / metadataEvent.taskId). */
+    taskId?: unknown;
+    /** Optional per-event id when the producer assigns one. */
+    eventId?: unknown;
+    /** Worker session id — the fallback anchor when no task is attached. */
+    sessionId?: unknown;
+    nodeId?: unknown;
+    meshId?: unknown;
+    event?: unknown;
+}
+
+/**
+ * Stable, greppable correlation key. `task=` and `sess=` are ALWAYS rendered (as `-`
+ * when absent) so the key shape is uniform across stages and a single grep alternation
+ * (`task=<id>\|sess=<id>`) follows the event end-to-end.
+ */
+export function meshEventTraceKey(ctx: MeshEventTraceCtx): string {
+    const segs = [`task=${s(ctx.taskId) || '-'}`];
+    const eventId = s(ctx.eventId);
+    if (eventId) segs.push(`evt=${eventId}`);
+    segs.push(`sess=${s(ctx.sessionId) || '-'}`);
+    const nodeId = s(ctx.nodeId);
+    if (nodeId) segs.push(`node=${nodeId}`);
+    const meshId = s(ctx.meshId);
+    if (meshId) segs.push(`mesh=${meshId}`);
+    const event = s(ctx.event);
+    if (event) segs.push(`event=${event}`);
+    return segs.join(' ');
+}
+
+/** Lifecycle progress (INFO). One line per stage the event clears. */
+export function traceMeshEventStage(stage: string, ctx: MeshEventTraceCtx, detail?: string): void {
+    LOG.info(CAT, `[stage:${stage}] ${meshEventTraceKey(ctx)}${detail ? ` — ${detail}` : ''}`);
+}
+
+/** Event did not advance — rejected / held / skipped / deduped (WARN). */
+export function traceMeshEventDrop(reason: string, ctx: MeshEventTraceCtx, detail?: string): void {
+    LOG.warn(CAT, `[drop:${reason}] ${meshEventTraceKey(ctx)}${detail ? ` — ${detail}` : ''}`);
+}