comisai 1.0.42 → 1.0.44

package/node_modules/@comis/observability/dist/trajectory/event-bus-bridge.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Trajectory event-bus bridge.
+ *
+ * Subscribes to the typed `EventBus` and translates each mapped event
+ * into a trajectory `recordEvent` call. The bridge avoids N call-site
+ * instrumentations — one subscription per session is the entire surface.
+ *
+ * The mapping is declared as a single `TRAJECTORY_BRIDGE_MAPPING`
+ * record so the architecture test (`trajectory-event-types-known.test.ts`)
+ * can enumerate it at test time. Every EventBus emit site in
+ * `packages/agent` and `packages/orchestrator` whose name is in
+ * `EventMap` (compile-time enforced) must EITHER appear as a key here
+ * OR appear in the `EVENTS_NOT_TRAJECTORY_MAPPED` allowlist
+ * (defined in the architecture test).
+ *
+ * Dedup contract:
+ *   - `tool:executed{errorKind:"timeout"}` AND `tool:timeout` are
+ *     BOTH mapped. They share `toolCallId` — downstream consumers
+ *     join on that key to dedupe. The architecture test enforces
+ *     both events have entries in this table.
+ *   - `model:lkw_fallback_attempt` AND `model:fallback_attempt` both
+ *     map to `model.fallback_attempt`; the LKW variant emits a
+ *     `data.lkw: true` flag so the trajectory consumer can
+ *     distinguish.
+ *
+ * @module
+ */
+import type { TypedEventBus } from "@comis/core";
+import type { TrajectoryRecorder } from "./types.js";
+/**
+ * Bridge mapping table — keys are `EventMap` event names that the bridge
+ * translates into trajectory events. Architecture test enumerates this.
+ *
+ * NOTE: events not in this table AND not explicitly allowlisted (in the
+ * architecture test's `EVENTS_NOT_TRAJECTORY_MAPPED` set) will fail the
+ * architecture test if used at an `eventBus.emit(...)` site. Add new
+ * entries here when wiring a new EventMap event into the trajectory.
+ */
+export declare const TRAJECTORY_BRIDGE_MAPPING: {
+    readonly "tool:started": "tool.call";
+    readonly "tool:executed": "tool.result";
+    readonly "tool:timeout": "tool.timeout";
+    readonly "tool:policy_filtered": "tool.policy_filtered";
+    readonly "tool:breaker_opened": "tool.breaker_opened";
+    readonly "tool:breaker_reset": "tool.breaker_reset";
+    readonly "tool:result_offloaded": "tool.result_offloaded";
+    readonly "observability:token_usage": "model.completed";
+    readonly "model:fallback_attempt": "model.fallback_attempt";
+    readonly "model:lkw_fallback_attempt": "model.fallback_attempt";
+    readonly "model:fallback_exhausted": "model.fallback_exhausted";
+    readonly "model:auth_cooldown": "model.auth_cooldown";
+    readonly "skill:prompt_loaded": "skill.prompt_loaded";
+    readonly "skill:prompt_invoked": "skill.prompt_invoked";
+    readonly "memory:skill_used": "memory.skill_used";
+    readonly "memory:skill_surfaced": "memory.skill_surfaced";
+    readonly "prompt:submitted": "prompt.submitted";
+    readonly "session:started": "session.started";
+    readonly "session:ended": "session.ended";
+    readonly "session:summary": "session.summary";
+    readonly "memory:injected": "memory.injected";
+    readonly "memory:recalled": "memory.recalled";
+    readonly "memory:reranked": "memory.reranked";
+    readonly "memory:generation_quality": "memory.generation_quality";
+    readonly "observability:cache_break": "cache.break";
+    readonly "pipeline:authored": "pipeline.authored";
+    readonly "graph:repaired": "graph.repaired";
+    readonly "graph:synthesized_from_intent": "graph.synthesized_from_intent";
+    readonly "subagent:steered": "subagent.steered";
+    readonly "security:sandbox_downgrade_refused": "security.sandbox_downgrade_refused";
+    readonly "subagent:delivery_deadlettered": "subagent.delivery_deadlettered";
+    readonly "subagent:budget_exceeded": "subagent.budget_exceeded";
+    readonly "capability:audited": "capability.audited";
+    readonly "graph:node_spawned": "graph.node_spawned";
+    readonly "learning:outcome_observed": "learning.outcome_observed";
+    readonly "learning:memory_demoted": "learning.memory_demoted";
+    readonly "learning:memory_evicted": "learning.memory_evicted";
+    readonly "learning:memory_failure_attributed": "learning.memory_failure_attributed";
+    readonly "reflect:admitted": "reflect.admitted";
+    readonly "reflect:funnel": "reflect.funnel";
+    readonly "learning:skill_promoted": "learning.skill_promoted";
+    readonly "learning:skill_demoted": "learning.skill_demoted";
+    readonly "background_task:promoted": "background_task.promoted";
+    readonly "background_task:completed": "background_task.completed";
+    readonly "background_task:failed": "background_task.failed";
+    readonly "terminal:drive_promoted": "terminal.drive_promoted";
+    readonly "delivery:enqueued": "delivery.queued";
+    readonly "delivery:complete": "delivery.dispatched";
+    readonly "context:pipeline": "context.compiled";
+    readonly "queue:enqueued": "queue.enqueued";
+    readonly "queue:dequeued": "queue.dequeued";
+    readonly "queue:overflow": "queue.overflow";
+    readonly "queue:coalesced": "queue.coalesced";
+    readonly "execution:aborted": "execution.aborted";
+    readonly "execution:budget_warning": "execution.budget_warning";
+    readonly "execution:prompt_timeout": "execution.prompt_timeout";
+    readonly "execution:output_escalated": "execution.output_escalated";
+    readonly "execution:signed_replay_recovered": "execution.replay_recovered";
+    readonly "execution:tool_schema_unsupported": "execution.tool_schema_unsupported";
+    readonly "security:injection_detected": "security.injection_detected";
+    readonly "sender:blocked": "sender.blocked";
+    readonly "retry:attempted": "delivery.retry";
+    readonly "retry:exhausted": "delivery.retry_exhausted";
+    readonly "retry:markdown_fallback": "delivery.markdown_fallback";
+    readonly "mcp:server:disconnected": "mcp.disconnected";
+    readonly "mcp:server:reconnecting": "mcp.reconnecting";
+    readonly "mcp:server:reconnect_failed": "mcp.reconnect_failed";
+    readonly "mcp:server:reconnected": "mcp.reconnected";
+    readonly "mcp:server:tools_changed": "mcp.tools_changed";
+    readonly "channel:health_changed": "channel.health_changed";
+    readonly "channel:registered": "channel.lifecycle";
+    readonly "channel:deregistered": "channel.lifecycle";
+    readonly "security:memory_tainted": "security.memory_tainted";
+    readonly "security:warn": "security.warn";
+    readonly "compaction:started": "compaction.started";
+    readonly "compaction:flush": "compaction.flush";
+    readonly "compaction:recommended": "compaction.recommended";
+    readonly "context:budget_computed": "context.budget";
+    readonly "context:evicted": "context.evicted";
+    readonly "context:masked": "context.masked";
+    readonly "context:reread": "context.reread";
+    readonly "context:overflow": "context.overflow";
+    readonly "context:integrity": "context.integrity";
+    readonly "context:rehydrated": "context.rehydrated";
+    readonly "context:script_zero_hit": "context.script_zero_hit";
+    readonly "context:summary_language_mismatch": "context.summary_language_mismatch";
+    readonly "approval:requested": "approval.requested";
+    readonly "approval:resolved": "approval.resolved";
+    readonly "dedup:duplicate_inbound": "dedup.duplicate_inbound";
+    readonly "health:budget_exceeded": "health.budget_exceeded";
+    readonly "image:requested": "image.requested";
+    readonly "image:generated": "image.generated";
+    readonly "image:delivered": "image.delivered";
+    readonly "image:failed": "image.failed";
+    readonly "media.vision:requested": "media.vision.requested";
+    readonly "media.vision:completed": "media.vision.completed";
+    readonly "media.vision:failed": "media.vision.failed";
+    readonly "video:requested": "video.requested";
+    readonly "video:submitted": "video.submitted";
+    readonly "video:generated": "video.generated";
+    readonly "video:delivered": "video.delivered";
+    readonly "video:failed": "video.failed";
+    readonly "media.stt:requested": "media.stt.requested";
+    readonly "media.stt:completed": "media.stt.completed";
+    readonly "media.stt:failed": "media.stt.failed";
+    readonly "media.tts:requested": "media.tts.requested";
+    readonly "media.tts:completed": "media.tts.completed";
+    readonly "media.tts:failed": "media.tts.failed";
+    readonly "observability:spend_warning": "spend.warning";
+    readonly "observability:spend_exceeded": "spend.exceeded";
+    readonly "observability:spend_unpriceable": "spend.unpriceable";
+};
+/**
+ * Closed string union of every EventBus event name the bridge maps.
+ * Useful for callers that want to type-narrow without re-listing.
+ */
+export type TrajectoryBridgedEventName = keyof typeof TRAJECTORY_BRIDGE_MAPPING;
+/** Parameters for `attachTrajectoryToEventBus`. */
+export interface AttachTrajectoryParams {
+    /** Typed event bus to subscribe to. */
+    readonly eventBus: TypedEventBus;
+    /** Per-session recorder built by `createTrajectoryRecorder`. */
+    readonly recorder: TrajectoryRecorder;
+    /**
+     * Optional filter: when present, only event names that pass the
+     * predicate are subscribed. The predicate runs ONCE per event name
+     * at attach time — it does not run per event emit.
+     */
+    readonly filter?: (eventName: TrajectoryBridgedEventName) => boolean;
+}
+/**
+ * Subscribe the bridge to the given event bus. Returns a single
+ * `unsubscribe` function that removes every handler registered by
+ * this call.
+ *
+ * Per-session lifecycle: pi-executor calls this once after `formattedKey`
+ * materializes; the returned `unsubscribe()` runs in the `try/finally`
+ * covering the runner block.
+ */
+export declare function attachTrajectoryToEventBus(params: AttachTrajectoryParams): () => void;

package/node_modules/@comis/observability/dist/trajectory/event-bus-bridge.js

@@ -0,0 +1,423 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Trajectory event-bus bridge.
+ *
+ * Subscribes to the typed `EventBus` and translates each mapped event
+ * into a trajectory `recordEvent` call. The bridge avoids N call-site
+ * instrumentations — one subscription per session is the entire surface.
+ *
+ * The mapping is declared as a single `TRAJECTORY_BRIDGE_MAPPING`
+ * record so the architecture test (`trajectory-event-types-known.test.ts`)
+ * can enumerate it at test time. Every EventBus emit site in
+ * `packages/agent` and `packages/orchestrator` whose name is in
+ * `EventMap` (compile-time enforced) must EITHER appear as a key here
+ * OR appear in the `EVENTS_NOT_TRAJECTORY_MAPPED` allowlist
+ * (defined in the architecture test).
+ *
+ * Dedup contract:
+ *   - `tool:executed{errorKind:"timeout"}` AND `tool:timeout` are
+ *     BOTH mapped. They share `toolCallId` — downstream consumers
+ *     join on that key to dedupe. The architecture test enforces
+ *     both events have entries in this table.
+ *   - `model:lkw_fallback_attempt` AND `model:fallback_attempt` both
+ *     map to `model.fallback_attempt`; the LKW variant emits a
+ *     `data.lkw: true` flag so the trajectory consumer can
+ *     distinguish.
+ *
+ * @module
+ */
+// The exhaustive payload translators live in `translate-payload.ts` (extracted
+// for the file-size cap); `TrajectoryBridgedEventName` (the switch's
+// exhaustiveness key) stays here and is type-imported back there.
+import { translatePayload } from "./translate-payload.js";
+// ---------------------------------------------------------------------------
+// Mapping table (EventName → TrajectoryEventType)
+// ---------------------------------------------------------------------------
+/**
+ * Bridge mapping table — keys are `EventMap` event names that the bridge
+ * translates into trajectory events. Architecture test enumerates this.
+ *
+ * NOTE: events not in this table AND not explicitly allowlisted (in the
+ * architecture test's `EVENTS_NOT_TRAJECTORY_MAPPED` set) will fail the
+ * architecture test if used at an `eventBus.emit(...)` site. Add new
+ * entries here when wiring a new EventMap event into the trajectory.
+ */
+export const TRAJECTORY_BRIDGE_MAPPING = {
+    // ---- Tool lifecycle ----
+    "tool:started": "tool.call",
+    "tool:executed": "tool.result",
+    "tool:timeout": "tool.timeout",
+    "tool:policy_filtered": "tool.policy_filtered",
+    // D3 breaker transitions (Phase 151).
+    "tool:breaker_opened": "tool.breaker_opened",
+    "tool:breaker_reset": "tool.breaker_reset",
+    // D7 result offload (Phase 151).
+    "tool:result_offloaded": "tool.result_offloaded",
+    // ---- Model lifecycle ----
+    // `observability:token_usage` is reused as `model.completed` — the
+    // token-usage event already carries everything the trajectory needs
+    // for a model-completed record. `model:fallback_attempt` and the LKW
+    // variant both map to `model.fallback_attempt`; the LKW variant
+    // attaches `lkw: true`.
+    "observability:token_usage": "model.completed",
+    "model:fallback_attempt": "model.fallback_attempt",
+    "model:lkw_fallback_attempt": "model.fallback_attempt",
+    "model:fallback_exhausted": "model.fallback_exhausted",
+    "model:auth_cooldown": "model.auth_cooldown",
+    // ---- Skill observability ----
+    "skill:prompt_loaded": "skill.prompt_loaded",
+    "skill:prompt_invoked": "skill.prompt_invoked",
+    // IMP-3 / PD-OBS-1 (package-delivery-20260628): the per-turn used-skill attribution (ATTR-02) — the
+    // INLINE-surfaced reuse credit. Previously DB-only (outcome_events.used_skill_ids, allowlisted in
+    // EVENTS_NOT_TRAJECTORY_MAPPED), so explain.skillsUsed was [] for an inline reuse while skillsPromoted>0.
+    // Now bridged so the credit shows on a one-call `comis explain`. AGENT-emitted (postExecution) → it IS
+    // arch-scanned, so REMOVED from the arch allowlist (the disjoint invariant). Content-free: opaque skill
+    // ids + count ONLY (same id-class as skill.prompt_invoked.skillName; never a procedure body — SEC-01).
+    "memory:skill_used": "memory.skill_used",
+    // Finding A (obs-sweep package-delivery-20260628): the full per-turn topic-match reuse CENSUS,
+    // so a surfaced-but-uncredited NEAR-MISS is diagnosable (memory:skill_used only fires on a
+    // credit). Content-free: skill NAMES (id-class) + coverage/sharedCount NUMBERS + flags — never a
+    // procedure body (SEC-01). Mapped → REMOVED from the arch NOT-MAPPED allowlist (disjoint invariant).
+    "memory:skill_surfaced": "memory.skill_surfaced",
+    // ---- Session + prompt lifecycle ----
+    "prompt:submitted": "prompt.submitted",
+    "session:started": "session.started",
+    "session:ended": "session.ended",
+    // F2 (D5): per-session health rollup emitted once at agent-end.
+    "session:summary": "session.summary",
+    "memory:injected": "memory.injected",
+    // RECALL-01 (observability-excellence): the per-recall lane/candidate/final counts +
+    // rerank outcome — previously emitted but UNMAPPED (invisible to comis explain/trace,
+    // the #1 troubleshooting blind spot). Content-free (counts/booleans only — H1).
+    "memory:recalled": "memory.recalled",
+    "memory:reranked": "memory.reranked",
+    // GENQ-01 (observability-excellence): a memory-generation pass (consolidation /
+    // reasoning / user-representation) produced output whose quality diverged from
+    // its source — the F-ML1 class. Emitted only on an issue. Content-free (closed
+    // enums + booleans — H1); the source/generated body never crosses the bus.
+    "memory:generation_quality": "memory.generation_quality",
+    // PERSIST-01 (Phase 176 Plan 04, observability-excellence): a detected prompt-cache
+    // break (15 CacheBreakReason values) — emitted in packages/agent but previously
+    // UNMAPPED (allowlisted as a daemon-level rollup), invisible to `comis explain`. Now
+    // bridged so the cost-relevant break shows on the per-session timeline beside the
+    // obs_diagnostics category:'cache_break' row. Content-free (the closed reason + the
+    // tokenDrop/relative counts + a changed-dims DIGEST — H1/I3); the translator drops
+    // the toolsAdded/Removed/SchemaChanged tool-NAME arrays and the system text entirely.
+    "observability:cache_break": "cache.break",
+    // TELEM-01 (v2.27 P1, Phase 173): a `pipeline` tool invocation was authored —
+    // counts-only (action / capabilityClass tier / schemaValid / repaired). Mapped
+    // here for trajectory-type ARCH closure (every EventMap member is mapped-or-
+    // allowlisted) and to reserve the `pipeline.authored` trajectory type. The live
+    // per-session recordEvent emit is a DEFERRED follow-up: at P1 `getRecorder` is
+    // NOT reachable on the graph-handler deps (it rides the image-handler slice, not
+    // the createGraphHandlers spread) — the P1 path is the FLEET aggregate (Plan
+    // 03/04), which needs only eventBus. Content-free (closed enums + booleans —
+    // H1); no pipeline body / type_config value / node task crosses the bus.
+    "pipeline:authored": "pipeline.authored",
+    // AUTHOR-01/02 (v2.27 P2, Phase 174): the two authoring-AUDIT events Plans 03/04
+    // emit DAEMON-SIDE on a conservative repair / intent-synthesis (the repair +
+    // synthesis producers the P1 pipeline:authored.repaired flag documented as
+    // deferred). APPEND-ONLY beside pipeline:authored. Mapped here for trajectory-type
+    // ARCH closure (every EventMap member is mapped-or-allowlisted) + to reserve the
+    // graph.repaired / graph.synthesized_from_intent trajectory types. NOTE: these
+    // emit from @comis/daemon (graph-helpers.ts), so the trajectory-event-types-known
+    // arch gate — which walks only packages/agent + packages/orchestrator — does not
+    // require them; the registration is for consistency with pipeline:authored AND
+    // arch-test closure of the keyof TrajectoryBridgedEventName. Content-free (closed
+    // enums + numbers — H1); no graph body / type_config / node task / intent text
+    // crosses the bus.
+    "graph:repaired": "graph.repaired",
+    "graph:synthesized_from_intent": "graph.synthesized_from_intent",
+    // STEER-01 (v2.27 P3, Phase 175): a running sub-agent was steered IN-FLIGHT (a
+    // high-priority message injected at the child's next step boundary, transcript
+    // preserved) instead of kill+respawn. Emitted DAEMON-SIDE at the inject site
+    // (Plan 02, subagent-handlers.ts), so the trajectory-event-types-known arch gate
+    // — which walks only packages/agent + packages/orchestrator — does NOT require it
+    // (the unmapped subagent:budget_exceeded precedent); the registration here is
+    // purely for OPERATOR TRAJECTORY VISIBILITY (a steer is a meaningful per-session
+    // event in `comis explain`), mirroring the graph:repaired entry above. Content-free
+    // (runId + the closed-union mode steer|followup — H1); the steer MESSAGE BODY never
+    // crosses the bus.
+    "subagent:steered": "subagent.steered",
+    // ORCH-OBS (orchestration-observability): three previously-dark sub-agent-lifecycle
+    // events bridged for per-session `comis explain` visibility (the subagent:steered
+    // precedent). security:sandbox_downgrade_refused is agent-emitted (sub-agent-runner.ts)
+    // and fires WITHIN the spawning session → lands cleanly in that trajectory;
+    // subagent:delivery_deadlettered (orchestrator) + subagent:budget_exceeded (daemon
+    // coordinator) ride whichever session bridge is active. Content-free translators
+    // (translate-orchestration-payload.ts) forward closed labels/ids/numbers ONLY — never
+    // a path/host/uid value, an announcement body, or a task (§2.7 / H1). These ALSO feed
+    // the fleet lens via obs-persistence-wiring (the daemon-wide aggregate surface).
+    "security:sandbox_downgrade_refused": "security.sandbox_downgrade_refused",
+    "subagent:delivery_deadlettered": "subagent.delivery_deadlettered",
+    "subagent:budget_exceeded": "subagent.budget_exceeded",
+    // AUDIT-01 / TREE (v2.29 Phase 215 Plan 01): the per-capability authorization
+    // decision for a gated call (allow + deny) — the spawn-tree's per-node
+    // producer (Plan 03's TREE fold groups these by leaseId). DAEMON-emitted
+    // (rpc-dispatch.ts / setup-capability-endpoint.ts), so the trajectory-event-
+    // types-known arch gate — which walks only packages/agent + packages/
+    // orchestrator — does NOT require it (the subagent:budget_exceeded daemon-
+    // emitted precedent); the registration here is for OPERATOR TRAJECTORY
+    // VISIBILITY (`comis explain` spawn tree) + arch closure of the keyof
+    // TrajectoryBridgedEventName. Content-free (translate-orchestration-payload.ts):
+    // caps + tool NAME + decision + lease/root ids ONLY — NEVER the tool.invoke
+    // args, a message body, or a secret name (§2.7 / H1 / T-215-01).
+    "capability:audited": "capability.audited",
+    // TREE-01 (finding D, 30uc-20260624): a graph DAG node spawn — the spawn-tree's
+    // per-graph-node producer. A graph node spawns in-process (gatedSpawn) and never
+    // crosses the socket chokepoint that emits capability:audited, so without this the
+    // `comis explain` spawn-tree showed only the root. DAEMON-emitted (graph-node-
+    // lifecycle.ts), so the agent/orchestrator emit-scanner arch gate does not require
+    // it (the subagent:budget_exceeded / capability:audited daemon-emitted precedent).
+    // Content-free (translate-orchestration-payload.ts): graph/node ids + child agentId
+    // + rootRunId + the per-node token cap ONLY — NEVER a node task or output.
+    "graph:node_spawned": "graph.node_spawned",
+    // OUTCOME-08 (v2.26 Verified Learning WS1): a finished trajectory's resolved net
+    // task-outcome, emitted DAEMON-SIDE after OutcomeSignalPort.resolve (learningOutcome.
+    // enabled-gated, default OFF). DAEMON emit (NOT agent/orchestrator) so the arch
+    // emit-scanner does not require it; mapped here so OBS-02 `comis explain` can
+    // reconstruct it. Content-free: ids/counts/closed-enums ONLY (no body/alpha — SEC-01).
+    "learning:outcome_observed": "learning.outcome_observed",
+    // FORGET-06 (v2.26 Verified Learning WS4, Phase 200): the lifecycle-sweep soft-eviction
+    // telemetry. learning:memory_* are daemon emit (NOT arch-scanned). Counts/ids/closed-enums
+    // ONLY — never a memory body (SEC-01). Mapped here so OBS-02 `comis explain` can reconstruct
+    // them. (The RANK-06 memory:online_tuning_applied bandit event was removed in Phase 224 —
+    // the UCB online-tuning bandit was deleted; recall is fixed-RRF.)
+    "learning:memory_demoted": "learning.memory_demoted",
+    "learning:memory_evicted": "learning.memory_evicted",
+    "learning:memory_failure_attributed": "learning.memory_failure_attributed",
+    // REFLECT (v2.31, Phase 226 SIMPLIFY-04): the reflection-run funnel telemetry,
+    // RENAMED from the old synthesis-funnel events to reflect:admitted / reflect:funnel.
+    // Both DAEMON-emitted (the reflection cron
+    // handler, NOT agent/orchestrator) after runReflection → the arch emit-scanner does
+    // not require them; mapped here so OBS-02 `comis explain` can reconstruct a
+    // reflection run. The forget (learning:memory_*) + outcome (learning:outcome_observed)
+    // events KEEP their learning:* names (Pitfall 6). Content-free: counts (synthesized/
+    // validated/admitted) + maxClusterCardinality + the admissionOutcome closed-enum ONLY
+    // — NEVER a doc body, a script, or a finding (SEC-01 §7). The vestigial
+    // sandbox-validation event (0-emit, sandbox deleted in 223) was REMOVED here.
+    "reflect:admitted": "reflect.admitted",
+    "reflect:funnel": "reflect.funnel",
+    // SURFACE-06 (v2.26 Verified Learning WS2, Phase 202 Plan 03): the promote/demote
+    // telemetry. Both DAEMON-emitted (the promote/demote loop, Plan 05 — NOT agent/
+    // orchestrator) so the arch emit-scanner does not require them; mapped here so OBS-02
+    // `comis explain` can reconstruct a promotion/demotion. Content-free: the COUNT ONLY —
+    // NEVER an id-list, a procedure body, or a script (SEC-01 §7). They fold into the
+    // shared { count } translator case (translate-payload.ts).
+    "learning:skill_promoted": "learning.skill_promoted",
+    "learning:skill_demoted": "learning.skill_demoted",
+    // Phase 226 SIMPLIFY-04: the REVISE-/GENERAL- entries (the user-rep-revision +
+    // generalization events) were DELETED — both grep-confirmed 0-emit at HEAD (those paths
+    // were folded into the reflection engine in Phase 225). Their translator cases, type
+    // members, and obs folds/verdicts went with them in the same lockstep.
+    // ---- Background task lifecycle (T2.2 / F9) ----
+    // The promote/complete/fail transitions of a long-running tool detached past the
+    // execute() boundary — previously emitted but UNMAPPED (invisible to comis explain; a
+    // backgrounded wait's lifecycle could only be inferred from a rollup counter). Content-
+    // free: closed ids (taskId/toolName) + durationMs ONLY — never a result/error body;
+    // agentId/origin are envelope correlation ids (§2.7 / H1).
+    "background_task:promoted": "background_task.promoted",
+    "background_task:completed": "background_task.completed",
+    "background_task:failed": "background_task.failed",
+    // ---- Terminal drive lifecycle ----
+    // DRIVE-02: a long coding-CLI drive backgrounded at the inline→detached boundary
+    // (the unattended abandoned-drive blind spot — was daemon-log-only). Content-free
+    // (the reason enum only — see translate-payload). Emitted from packages/skills,
+    // which the trajectory-event arch test does NOT scan (it walks agent+orchestrator),
+    // so this was previously neither mapped nor allowlisted and the bridge dropped it.
+    "terminal:drive_promoted": "terminal.drive_promoted",
+    // ---- Delivery lifecycle ----
+    "delivery:enqueued": "delivery.queued",
+    "delivery:complete": "delivery.dispatched",
+    // ---- Context engine ----
+    // Context pipeline runs once per turn (pre-LLM context assembly).
+    // Mapping table entry: "(executor) prompt assembled (or context layer)
+    // → context.compiled". The post-LLM `context:pipeline:cache` patch
+    // event is NOT mapped here; its cache fields land in this initial
+    // pipeline snapshot at emit time (the producer reuses the same
+    // payload-fence semantics for both events).
+    "context:pipeline": "context.compiled",
+    // ---- Queue / Execution / Sender ----
+    // Queue lifecycle — events-channel.ts
+    "queue:enqueued": "queue.enqueued",
+    "queue:dequeued": "queue.dequeued",
+    "queue:overflow": "queue.overflow",
+    "queue:coalesced": "queue.coalesced",
+    // Execution control — events-messaging.ts
+    "execution:aborted": "execution.aborted",
+    "execution:budget_warning": "execution.budget_warning",
+    "execution:prompt_timeout": "execution.prompt_timeout",
+    "execution:output_escalated": "execution.output_escalated",
+    // Maps to "execution.replay_recovered" (NOT "execution.signed_replay_recovered")
+    // per canonical name.
+    "execution:signed_replay_recovered": "execution.replay_recovered",
+    // GBNF-02 strip-retry self-heal (Phase 175). Payload is already content-free
+    // (tool + keyword NAMES only, I7) — translator forwards all 4 data fields.
+    "execution:tool_schema_unsupported": "execution.tool_schema_unsupported",
+    // Security + Sender (scanned subset)
+    // patterns[] and senderId are intentionally omitted in translatePayload.
+    "security:injection_detected": "security.injection_detected",
+    "sender:blocked": "sender.blocked",
+    // Delivery retry (events-channel.ts; emitter packages/core/delivery — not arch-scanned)
+    // chatId (Telegram long-decimal ID) and channelId are intentionally omitted.
+    "retry:attempted": "delivery.retry",
+    "retry:exhausted": "delivery.retry_exhausted",
+    "retry:markdown_fallback": "delivery.markdown_fallback",
+    // MCP server reliability (events-infra.ts; emitter packages/skills — not arch-scanned)
+    "mcp:server:disconnected": "mcp.disconnected",
+    "mcp:server:reconnecting": "mcp.reconnecting",
+    "mcp:server:reconnect_failed": "mcp.reconnect_failed",
+    "mcp:server:reconnected": "mcp.reconnected",
+    "mcp:server:tools_changed": "mcp.tools_changed",
+    // Channel lifecycle + health (events-channel.ts; emitter packages/channels — not arch-scanned)
+    // Both channel:registered and channel:deregistered map to the same trajectory type.
+    // Translator adds a synthetic `event` discriminator: "registered" | "deregistered".
+    // Precedent: model:fallback_attempt + model:lkw_fallback_attempt share model.fallback_attempt.
+    "channel:health_changed": "channel.health_changed",
+    "channel:registered": "channel.lifecycle",
+    "channel:deregistered": "channel.lifecycle",
+    // Security (non-scanned emitters — packages/daemon + packages/core/security)
+    // SECURITY INVARIANT: patterns[] (verbatim taint strings) and message (may reference
+    // secret names/config paths) are intentionally NOT forwarded.
+    "security:memory_tainted": "security.memory_tainted",
+    "security:warn": "security.warn",
+    // Compaction signals (events-messaging.ts; emitters in packages/agent — arch-scanned)
+    // All 3 are in EVENTS_NOT_TRAJECTORY_MAPPED and must be removed when bridged.
+    "compaction:started": "compaction.started",
+    "compaction:flush": "compaction.flush",
+    "compaction:recommended": "compaction.recommended",
+    // Context engine internals (events-messaging.ts; emitters in packages/agent — arch-scanned)
+    // 5 of 6 are in EVENTS_NOT_TRAJECTORY_MAPPED and must be removed when bridged.
+    // context:integrity uses optional chaining (?.emit) — not in arch-test scope; no allowlist change needed.
+    // W2 (obs-llm-troubleshooting): per-LLM-call budget equation from the LCD
+    // pre-flight — lets obs.explain reconstruct a context_exhausted abort.
+    "context:budget_computed": "context.budget",
+    "context:evicted": "context.evicted",
+    "context:masked": "context.masked",
+    "context:reread": "context.reread",
+    "context:overflow": "context.overflow",
+    "context:integrity": "context.integrity",
+    "context:rehydrated": "context.rehydrated",
+    // OBS-01 (Phase 180): the two multilingual signals on the explain path. Not
+    // yet emitted (emit sites land in 180-08) — declared/mapped here so the
+    // trajectory bridge records them the moment they fire. NOT added to
+    // EVENTS_NOT_TRAJECTORY_MAPPED (these are mapping entries, not allowlist entries).
+    "context:script_zero_hit": "context.script_zero_hit",
+    "context:summary_language_mismatch": "context.summary_language_mismatch",
+    // Approval / human-in-the-loop (events-infra.ts; emitter packages/core/approval — not arch-scanned)
+    // SECURITY INVARIANT: approval:requested.params is raw unconstrained tool arguments
+    // (file paths, message bodies, credentials — HIGHEST risk field in the phase).
+    // Translator MUST omit params entirely — sanitizeForPersistence is defense-in-depth only.
+    "approval:requested": "approval.requested",
+    "approval:resolved": "approval.resolved",
+    // Duplicate inbound detection (events-channel.ts; emitter packages/orchestrator — arch-scanned)
+    // firstSeenAt and duplicateAt omitted by translator — envelope ts covers timing.
+    "dedup:duplicate_inbound": "dedup.duplicate_inbound",
+    // Health budget exceeded (events-infra.ts; emitter packages/observability/health-aggregator)
+    // timestamp is envelope-only — stripped from data.
+    "health:budget_exceeded": "health.budget_exceeded",
+    // ---- Image generation (OBS-04, Phase 186; events-media.ts) ----
+    // DIRECT-emitted by the daemon image RPC handler via the per-session recorder
+    // (the daemon RPC context has NO bus bridge — the comis-session-manager.ts:298
+    // precedent), NOT through an eventBus.emit in packages/agent/orchestrator. The
+    // mapping is declared here for trajectory-type ARCH closure (the arch test
+    // enumerates it) and so a future bus emitter is wired. The `observability:
+    // token_usage → model.completed` cost-carry precedent (:69) is mirrored here:
+    // image.generated carries `costUsd` (OBS-03 Route a). Content-free translators
+    // (translate-payload.ts) forward only ids/labels/numbers/booleans.
+    "image:requested": "image.requested",
+    "image:generated": "image.generated",
+    "image:delivered": "image.delivered",
+    "image:failed": "image.failed",
+    // ---- Vision analysis (VIS-04, Phase 187; events-media.ts) ----
+    // APPEND-ONLY alongside the image:* section above — never a rename (Pitfall 5;
+    // the v2.17-merge gate cascade). Like image.*, these are DIRECT-emitted by the
+    // daemon vision RPC handler (image.analyze / media.describe_video) via the
+    // per-session recorder (NO bus bridge in the daemon RPC context); declared here
+    // for trajectory-type ARCH closure + a future bus emitter. media.vision.completed
+    // carries `costUsd` (VIS-04 Route a — optional, absent on registry/gemini-video).
+    // Content-free translators (translate-payload.ts) forward only the
+    // ids/labels/path/numbers/outcome/errorKind.
+    "media.vision:requested": "media.vision.requested",
+    "media.vision:completed": "media.vision.completed",
+    "media.vision:failed": "media.vision.failed",
+    // ---- Video generation (OBS-04, Phase 192; events-media.ts) ----
+    // APPEND-ONLY alongside the image:*/media.vision:* sections above — never a
+    // rename (Pitfall 8; the v2.17-merge gate cascade). Like image.*/media.vision.*,
+    // these are DIRECT-emitted by the daemon video RPC handler (in-turn) AND the
+    // off-turn background poller via the per-session recorder (NO bus bridge in the
+    // daemon RPC/poller context); declared here for trajectory-type ARCH closure +
+    // a future bus emitter ONLY. video.generated carries `costUsd` (OBS-03 Route a —
+    // FAL/Veo estimate, Grok actual, optional). Content-free translators
+    // (translate-payload.ts) forward only the ids/labels/numbers/outcome/errorKind.
+    "video:requested": "video.requested",
+    "video:submitted": "video.submitted",
+    "video:generated": "video.generated",
+    "video:delivered": "video.delivered",
+    "video:failed": "video.failed",
+    // ---- Voice STT/TTS (OBS-02/03, Phase 196; events-media.ts) ----
+    // APPEND-ONLY alongside the image:*/media.vision:*/video:* sections above —
+    // never a rename (Pitfall 8). Like those, these are DIRECT-emitted by the
+    // daemon voice RPC handler (media.transcribe / tts.synthesize) via the
+    // per-session recorder (NO bus bridge in the daemon RPC context); declared here
+    // for trajectory-type ARCH closure + a future bus emitter ONLY.
+    // media.*.completed carries `costUsd` (keyless = 0 explicit — OBS-05 Route a);
+    // media.*.requested carries the `onSkip` reasons (OBS-03). Content-free
+    // translators (translate-voice-payload.ts) forward only the
+    // ids/labels/numbers/booleans/closed-enum-reasons. KEY is COLON, VALUE is DOT.
+    "media.stt:requested": "media.stt.requested",
+    "media.stt:completed": "media.stt.completed",
+    "media.stt:failed": "media.stt.failed",
+    "media.tts:requested": "media.tts.requested",
+    "media.tts:completed": "media.tts.completed",
+    "media.tts:failed": "media.tts.failed",
+    // WR-4 (177-obs-loop): the spend kill-switch's three signals. AGENT-emitted
+    // (pi-event-bridge.ts), so they ARE arch-scanned — previously allowlisted in
+    // EVENTS_NOT_TRAJECTORY_MAPPED as fleet-only rollups, which made a spend-killed
+    // session UNDIAGNOSABLE via `comis explain` (the security-review WR-4 blind spot
+    // — directly violating this milestone's thesis). Mapped here + REMOVED from the
+    // arch allowlist (the disjoint invariant). The terminal ABORT is ALSO on the
+    // trajectory via execution:aborted(reason:"spend_exceeded"); these carry the
+    // per-scope $ counts the verdict needs. Content-free translators forward the
+    // closed SpendScopeKind enum + dollar NUMBERS + provider/model config ids ONLY
+    // — never a message/prompt/query body (§2.7 / H1; the milestone invariant).
+    "observability:spend_warning": "spend.warning",
+    "observability:spend_exceeded": "spend.exceeded",
+    "observability:spend_unpriceable": "spend.unpriceable",
+};
+/**
+ * Subscribe the bridge to the given event bus. Returns a single
+ * `unsubscribe` function that removes every handler registered by
+ * this call.
+ *
+ * Per-session lifecycle: pi-executor calls this once after `formattedKey`
+ * materializes; the returned `unsubscribe()` runs in the `try/finally`
+ * covering the runner block.
+ */
+export function attachTrajectoryToEventBus(params) {
+    const { eventBus, recorder, filter } = params;
+    // Per-handler bag so unsubscribe can pop them all in one call.
+    const subscriptions = [];
+    // Type assertion narrowing: the as-const mapping makes Object.entries
+    // lose precision, so iterate over the typed keys instead.
+    for (const eventName of Object.keys(TRAJECTORY_BRIDGE_MAPPING)) {
+        if (filter !== undefined && !filter(eventName))
+            continue;
+        const handler = (payload) => {
+            const data = translatePayload(eventName, payload);
+            const trajectoryType = TRAJECTORY_BRIDGE_MAPPING[eventName];
+            recorder.recordEvent(trajectoryType, data);
+        };
+        // The `on` overload requires a typed handler per event key. Cast
+        // here at the trust boundary: handler is typed against `unknown`
+        // and translatePayload narrows internally.
+        eventBus.on(eventName, handler);
+        subscriptions.push({ eventName, handler });
+    }
+    return function unsubscribe() {
+        for (const sub of subscriptions) {
+            eventBus.off(sub.eventName, sub.handler);
+        }
+        subscriptions.length = 0;
+    };
+}