system-event-shape consumer-path leakage; propose per-event audience classification

## Summary

Under umbrella #69208 Track B ("Delivery-mirror and consumer-path leakage"), the 2026-04-20 cleanup comment names #39469 as the Track B canonical and scopes the supporting issues (#38061, #33263, #5964) to *assistant-message-shape* artifacts. PR #69217 is the active Track B fix for that slice — it adds `isTranscriptOnlyOpenClawAssistantMessage` in `src/config/sessions/transcript.ts` and wires it into `chat.history`, `sessions.get`, and the sessions history HTTP reader.

The same consumer-path boundary also leaks *system-event-shape* artifacts — `enqueueSystemEvent` outputs from the exec runtime, cron, and heartbeat flows. These events carry a different object shape (no `role`, no `provider`, no `model`; their fields are `text`, `ts`, `contextKey`, `deliveryContext`, `trusted`), so #69217's predicate does not filter them. There is no canonical Track B issue for this shape today, and the fixes currently in flight for specific symptoms are per-surface or per-channel.

This issue is intended as the system-event-shape canonical under Track B, and proposes a per-event `audience: 'internal' | 'user-facing' | 'auto'` classification as the underlying primitive. The consumer-path filter would follow as a sibling predicate to #69217's, in the same file.

## Status update — 2026-05-05

> Posted as a status amendment on the original 2026-04-20 issue. The original analysis below is preserved for historical context. Many of the referenced cross-refs have changed state since filing; this section documents the deltas and the live implementation track.

**Track B canonical (#39469)** — open → **closed 2026-04-24** as already-implemented via `e95efa4373 fix(sessions): dedupe redundant delivery mirrors` and follow-up `d842ec4179 fix: tighten delivery mirror dedupe (#67185)`, both shipped in `v2026.4.15`. That fix is in the **transcript-append layer** (`src/config/sessions/transcript.ts`): before appending a `provider:"openclaw", model:"delivery-mirror"` assistant message, the writer trims visible text and reuses the latest assistant entry when the trimmed text matches. **Important framing:** that closure addresses **assistant-message-shape** Track B (the duplicate-mirror symptom). It does **not** touch the **system-event-shape** lane that this issue's subject is about — system events have a different object shape and do not flow through `appendAssistantMessageToSessionTranscript`. The system-event-shape lane remains unaddressed at the canonical layer.

**Track B canonical-adjacent PRs (state at filing → now)**
- #69217 Hide transcript-only OpenClaw history artifacts — open → **closed 2026-04-26 (NOT merged)**. Likely closed because `e95efa4373` / `d842ec4179` resolved the symptom at the producer layer instead of via consumer-side filtering. The audit-bypass concern flagged in review on this PR is the reason the implementation track for the system-event-shape lane (#72201, see below) avoids a consumer-side filter and uses wrap-on-drain instead.
- #69366 fix(ui): hide async exec system events and heartbeat acks — open → **closed 2026-04-25 (NOT merged)**. Per-surface display-layer filters were rejected as the canonical approach.
- #69084 fix(webchat): hide heartbeat chat output — **still open**. Scoped to `visibility.showAlerts` correction only.
- #71761 channel-message double-inject — **closed 2026-04-26**.

**Adjacent reshape that affects this PR's design (not a supersession)**
- `9180173f9a fix: preserve exec event routing and sanitize tool XML` (post-`v2026.5.4`). Introduces `selectGenericSystemEvents` + `consumeSelectedSystemEventEntries` so exec-completion events stay queued for the heartbeat path and only generic events are drained at the autoreply integration point. This **reshapes** the surface #72201 hooks into but does not replace it — the audience split still applies to the generic events that are drained. #72201 is rebased on top of this and now uses `consumeSelectedSystemEventEntries(...)` rather than `drainSystemEventEntries(...)`.

**Direct system-event-shape reports (original A list)**
- Closed since filing: #66460, #61990, #65498, #65994, #66648, #67527, #68508, #68992, #59871, #62418. Closure reasons vary; not all are substantive backend supersessions, several appear to be cleanups under the umbrella consolidation. The system-event-shape leakage primitive remains unfixed upstream regardless of these individual issue closures.
- Still open: #66748.

**Cross-cuts assistant-message-shape (B)**
- Closed since filing: #66814 — likely covered by the v2026.4.15 transcript-dedup fix on the assistant-message-shape side. The system-event-shape portion of that issue's analysis remains relevant for #72201.

**Cross-cuts Track A — duplicate persistence (C, canonical #66443 still open)**
- Closed since filing: #56489, #43168, #69037.

**Adjacent / overlapping FRs**
- Closed since filing: #66487, #66382, #67030, #46798, #69329, #50398.
- Still open: #62294, #13911.

**Correction on prior precedent**
- #17340 was originally cited as "merged" in the body below. It is **closed without merge** (closed 2026-03-19). If the duplicate-transcript-followup symptom recurs in the wild, that PR's premise may need re-opening.

**Implementation track**
- #72201 `feat(events): add audience field for hidden runtime-context system events` is the live implementation slice from this proposal. Currently OPEN, rebased onto current `main` (HEAD `e68ce9353c`). Adds optional `SystemEvent.audience` and wraps internal-audience events at `drainFormattedSystemEvents` in the existing `INTERNAL_RUNTIME_CONTEXT_*` delimiters; migrates exactly one producer (`queueCronAwarenessSystemEvent`) for review tractability. No batch migration committed.

**Self-correction on the original "Consumer-path filter" section**
That section proposed a sibling predicate to #69217's `isTranscriptOnlyOpenClawAssistantMessage`. With #69217 closed without merge AND the v2026.4.15 transcript-dedup fix landing producer-side, the consumer-side predicate approach is **no longer actively pursued by this issue** — #72201's wrap-on-drain primitive supplants it. The original "Proposed Shape" → "Consumer-path filter" subsection is preserved below for context but should be read as superseded by the wrap-on-drain design.


## Why This Issue Exists

Several open reports describe system-event text landing in user-visible chat transcripts across multiple channels. The individual reports differ in surface and exact symptom, but the shared pattern is:

1. An internal producer (`maybeNotifyOnExit`, heartbeat relay, cron) calls `enqueueSystemEvent` with a `SystemEvent` payload.
2. That event is consumed by downstream readers (`chat.history`, `sessions.get`, sessions history HTTP, channel dispatchers) that have no way to distinguish "this event was meant for internal agent awareness" from "this event should reach the user."
3. The event is rendered, persisted, or relayed as if it were user-facing conversational content.

Existing visibility controls in the runtime (`tools.exec.notifyOnExit`, `visibility.showAlerts`, `heartbeat.target`, `suppressToolErrors`, `ANNOUNCE_SKIP_TOKEN`) are each too coarse to express this distinction at event granularity. Prior work that closed similar reports by adding boolean flags (e.g., #22823, #20193) has not held up in practice — #19894 showed that `notifyOnExit:false + suppressToolErrors` still leaks sub-agent exec failures, which suggests that boolean notify flags are not the right primitive.

The `ExecToolDefaults.trigger` field already carries `'heartbeat'` / `'cron'` / caller context through `runExecProcess`, but `maybeNotifyOnExit` never reads it. That signal is present in the runtime today but unused for classification.

## Related Issues

### A. System-event-shape reports (direct)

- #66460 cron-owned exec completion events relayed to user by heartbeat. The reporter explicitly proposes "mark cron-owned exec completion events so heartbeat consumes them internally instead of relaying" — the narrowest statement of this design.
- #61990 exec completion events injected as `[Queued messages while agent was busy]`, derailing active conversation on Discord.
- #65498 heartbeat / exec-completion interrupt drops main-session final reply.
- #65994 exec completion events leak as System messages in webchat.
- #66648 "Exec completed" notifications leak into unrelated webchat sessions.
- #66748 subagent background exec triggers spurious heartbeat wake-ups on main.
- #67527 async command completion shown in user message bubbles.
- #68508 system event message — including the `"Handle the result internally. Do not relay it to the user unless explicitly requested."` directive itself — lands in visible transcript.
- #68992 Control UI renders async exec system events in visible chat transcript. Partially addressed by #69366 (UI-layer string-match for Control UI only).
- #59871 async completion events inject verbose agent instructions into session transcript in TUI.
- #62418 internal exec notifications surface in user-visible webchat Control UI.

### B. Cross-cuts assistant-message-shape (addressed by #69217)

- #66814 reports both system-event text and heartbeat-followup assistant-message leakage. The bundle-inspection analysis in that issue enumerates `bash-tools.exec-runtime-*`, `heartbeat-runner-*`, `session-system-events-*`, `sessions-history-http-*` as leak paths. Some symptoms should be covered by #69217 once it lands; residual system-event text is this issue's responsibility. Worth re-reading with the reporter after both changes are in place.

### C. Cross-cuts Track A (duplicate persistence — canonical #66443)

- #56489 system events and cron payloads appear as user messages in webchat.
- #43168 heartbeat wakeups persisted as synthetic user messages in the main dashboard session.
- #69037 async exec completion re-injects original user message, causing duplicate agent replies.

These overlap with Track A at the persistence layer. An event-level `audience` classification would prevent persistence for internal events, which partially addresses them from this direction; the Track A idempotency work covers the remainder.

### Adjacent (not addressed here)

- #66487, #66382 heartbeat relay drops payload and emits generic fallback.
- #67030 heartbeat relays failed exec notifications with wrong persona/language.
- #46798 heartbeat re-triggers on local exec completed events, spams duplicates.
- #62294 non-interval wake reasons bypass interval enforcement.
- #69329 exec runtime artifact-gated closure seam — orthogonal axis but touches `bash-tools.exec-runtime.ts`.

### Overlapping feature requests

- #13911 per-channel announce suppression for sub-agents. Would be subsumed by the per-channel `defaultCompletionAudience` config proposed below.
- #50398 coding-agent skill should recommend `sessions_spawn + sessions_yield` over `exec --background`. Workaround-level; would remain valid advice but the underlying reason `exec --background` is broken for heartbeat-invisible completion would go away.

### Prior attempts at this problem class (closed)

- #19894 sub-agent exec failures still leak despite `notifyOnExit:false + suppressToolErrors`.
- #20193 Node exec events ignore `tools.exec.notifyOnExit`.
- #22823 added `tools.nodes.notifyOnExit`.
- #41406 notifyOnExit wake reason doesn't bypass empty HEARTBEAT.md guard.
- #8997 background exec completion notifications interrupt active agent turn.

## Related PRs

### In-flight Track B slices

- #69217 — assistant-message-shape consumer-path filter (`isTranscriptOnlyOpenClawAssistantMessage`). Track B canonical-adjacent; this issue proposes a system-event-shape peer predicate in the same file.
- #69366 — UI-layer string-pattern filter (`EXEC_INJECTION_PREFIX_RE`) for `System (untrusted):` exec messages and `HEARTBEAT_OK` acks. Closes #68992 for Control UI. The author explicitly notes "fix is UI display-layer only, does not affect channel delivery" and "Did NOT verify: non-webchat channels" — so the same system events still leak on every non-Control-UI surface. Useful defense-in-depth; not a substitute for a backend fix.
- #69084 — webchat heartbeat filter corrected to use `visibility.showAlerts` instead of `showOk`. Scoped to one misreferenced flag; does not change the abstraction.

### Historical precedent

- #22823 (closed, merged) — `tools.nodes.notifyOnExit` flag.
- #17340 (closed, merged) — duplicate-transcript fix for followup queue.
- #40716 (open) — consumer-path filtering for delivery-mirror leakage (Track B precedent per umbrella cleanup).

## Current Working Hypotheses

### 1. Classification gap at the event layer

`SystemEvent` (`src/infra/system-events.ts`) has `text`, `ts`, `contextKey`, `deliveryContext`, `trusted` — no field that expresses the producer's intent about whether the event should reach the user. `deliveryContext` routes *where* an event goes; it does not say *whether* the event should appear on any user-facing surface.

`ExecToolDefaults.trigger` (`src/agents/bash-tools.exec-types.ts:12`) already carries `'heartbeat'` / `'cron'` / caller context through to the runtime. `maybeNotifyOnExit` in `src/agents/bash-tools.exec-runtime.ts:279–308` does not consult it when deciding what to emit. The signal is present, unused.

### 2. Consumer-path write-through to visible transcripts

`buildExecEventPrompt({ deliverToUser: false })` in `src/infra/heartbeat-events-filter.ts:41–54` produces text that literally says *"Handle the result internally. Do not relay it to the user unless explicitly requested."* #68508 shows this exact directive text landing in visible chat transcripts, which suggests the filter is happening at the agent-instruction level but not at the transcript-persistence level. The pattern #69217 establishes for assistant-message-shape artifacts — a shared predicate called at consumer-path boundaries — applies directly to the system-event shape as well.

### 3. Per-surface patches are running faster than the underlying problem shrinks

The three Track B PRs filed in the last 48 hours each address a different slice (artifact shape, one UI surface, one misreferenced flag). They collectively close roughly one of the open reports in the system-event cluster. The remaining reports span Matrix, Discord, Telegram, Teams, Mattermost, TUI, and webchat; without an event-level primitive, each new surface needs its own filter and each format change (timezone prefix, text wording, output length) re-opens existing filters. An event-level `audience` field is the layer at which this can be closed consistently.

### 4. Boolean notify flags are structurally insufficient

Closed-issue precedent #19894 showed that `notifyOnExit:false + suppressToolErrors` compositions still leak sub-agent exec failures. Adding more top-level booleans has not held. An enum field on the event itself is a different concept, not another boolean.

## Proposed Shape

This is a proposal, not a committed design. Happy to revise per maintainer preference on any of these.

### Core primitive

Extend `SystemEvent` with an optional `audience` field:

```ts
type SystemEventAudience = 'internal' | 'user-facing' | 'auto';

type SystemEvent = {
  text: string;
  ts: number;
  contextKey?: string | null;
  deliveryContext?: DeliveryContext;
  trusted?: boolean;
  audience?: SystemEventAudience;
};
```

Default is `'auto'`. No existing call site has to change.

- `'user-facing'` — reach the user when routing and visibility allow.
- `'internal'` — agent/session/log awareness only. Heartbeat may read; agent may reason; appears in session state. Does not flow to user-facing chat surfaces. Not written to `chat.history` as a visible entry.
- `'auto'` — defer to downstream (current behavior).

### Spawn-time intent

Extend `ExecToolDefaults` and `ProcessSession` with `completionAudience?: SystemEventAudience`. Derive at `maybeNotifyOnExit`:

```
completionAudience explicit from defaults?                → use it
else session.trigger ∈ {'heartbeat','cron','subagent'}?    → 'internal'
else                                                       → 'user-facing'
```

This activates the existing-but-unused `trigger` field. Matches #66460's reporter's explicit fix proposal, generalized beyond cron.

### Relay-time honoring

In `src/infra/heartbeat-runner.ts` (`canRelayToUser` computation around line 812):

```ts
const canRelayToUser = Boolean(
  delivery.channel !== 'none' &&
  delivery.to &&
  visibility.showAlerts &&
  !everyPendingExecEventIsInternal(events)
);
```

`buildExecEventPrompt({ deliverToUser })` already handles the downstream wording and does not need to change.

### Consumer-path filter (sibling to #69217)

Peer predicate in `src/config/sessions/transcript.ts`, alongside `isTranscriptOnlyOpenClawAssistantMessage`:

```ts
export function isInternalAudienceSystemEvent(event: unknown): boolean {
  if (!event || typeof event !== "object" || Array.isArray(event)) {
    return false;
  }
  const typed = event as { audience?: unknown };
  return typed.audience === 'internal';
}
```

Wired into the same consumer-path boundaries #69217 touches. The exact call-site shape — two peer predicates called per consumer, or one combined dispatcher that inspects entry shape — is a maintainer preference. Happy to match whatever #69217 settles on.

### Config fallback

Optional per-channel default for unspecified events:

```json5
{
  channels: {
    matrix: {
      defaultCompletionAudience: "internal"
    }
  }
}
```

Backward-compat: when unset, behavior collapses to current `visibility.showAlerts` semantics. Superset, not replacement. Subsumes #13911.

### What this does not change

- `notifyOnExit: false` still short-circuits before any event is emitted.
- `visibility.showAlerts: false` still mutes per channel.
- `ANNOUNCE_SKIP_TOKEN` for `sessions.send` is orthogonal and stays.
- #69217's `isTranscriptOnlyOpenClawAssistantMessage` is untouched — peer, not replacement.
- #69366's UI filter stays as defense-in-depth. After the backend gate is in place, it should rarely match anything the backend hasn't already filtered, but the pattern-match is cheap insurance against future write paths that skip the gate.
- #69084's `showAlerts` correction is complementary.

## What This Issue Should Track

1. Whether the Track B scope should be expanded to include system-event-shape artifacts, or whether this should be treated as a separate track.
2. Whether the per-event `audience` primitive is the right direction, versus alternatives such as extending per-channel `showAlerts` to be per-trigger, or extending `trusted` to be a tri-state visibility field.
3. Naming — `audience` vs `visibility` on the event; `completionAudience` vs `completionVisibility` on defaults. Draft uses `audience` to reduce conflation with the existing `visibility.showAlerts` channel-level knob.
4. Consumer-gate shape — two peer predicates or a single combined dispatcher.
5. Ordering relative to #69217 — waiting for it to land and layering on top, parallel branches, or expanding #69217's scope.

## Suggested Exit Criteria

This issue should not close until:

1. `SystemEvent` carries an `audience` field and the exec runtime derives a value from trigger context where available.
2. Heartbeat relay consults event-level audience in addition to per-channel visibility.
3. Consumer-path readers gate on audience in the same boundaries #69217 gates for assistant-message-shape artifacts.
4. At least #66460, #68508, and the system-event portion of #66814 are verified fixed by reporters.

## Notes On Issue Closure

Open issues in the list above with unique reproductions or unique affected surfaces should stay open until their exact symptom is verified fixed. This issue is meant to consolidate analysis and design, not to auto-close linked issues.

If #69366 merges and closes #68992 for Control UI only, non-Control-UI reports of the same symptom should stay open and be tracked here until the backend fix lands.

---

Happy to contribute an implementation PR along these lines if the direction is accepted, following the same iterative bot-review cadence as #67508.

AI-assisted research: cross-indexed open and closed issues, traced the event pipeline in `2026.4.19-beta.2`, and drafted this issue with Claude Code (Claude Opus 4.7, 1M context). Fully reviewed.



Uh oh!

system-event-shape consumer-path leakage; propose per-event audience classification #69492

Description

Summary

Status update — 2026-05-05

Why This Issue Exists

Related Issues

A. System-event-shape reports (direct)

B. Cross-cuts assistant-message-shape (addressed by #69217)

C. Cross-cuts Track A (duplicate persistence — canonical #66443)

Adjacent (not addressed here)

Overlapping feature requests

Prior attempts at this problem class (closed)

Related PRs

In-flight Track B slices

Historical precedent

Current Working Hypotheses

1. Classification gap at the event layer

2. Consumer-path write-through to visible transcripts

3. Per-surface patches are running faster than the underlying problem shrinks

4. Boolean notify flags are structurally insufficient

Proposed Shape

Core primitive

Spawn-time intent

Relay-time honoring

Consumer-path filter (sibling to #69217)

Config fallback

What this does not change

What This Issue Should Track

Suggested Exit Criteria

Notes On Issue Closure

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions