Add an emit-event skill helper and lifecycle event envelope v0

[williamthorsen]

Problem

Interactive skills write artifacts but emit no events, so there is no channel for live lifecycle status (#984). Spike #985 needs a production-track emit helper before skills can be instrumented.

Proposed solution

A bundled skill helper following the derive-session-context pattern: TS at packages/agents/src/emit-event/, a new BundleTarget producing content/skills/emit-event/emit-event.mjs (user-invocable: false), with a smoke test in the existing harness.

Envelope v0: {id, ts, type, repo, branch, session, cwd, harness, payload} — ULID id, nested per-family payload. cwd is included because #984 lists it among the fields (id, timestamp, branch ref, session, cwd) that must align across the lifecycle and KB-curated event stores. Session-lifecycle vocabulary v0: skill.started, skill.progress, skill.completed, artifact.written, input.requested, input.received, pr.created.

Context autofill draws on four sources: repo, branch, and session are each promoted into shared modules under packages/agents/src/shared/ (resolve-repo.ts, branch-helpers.ts, resolve-session.ts) that both capture-event and emit-event consume, rather than either helper duplicating the git-reading and environment-reading logic; cwd comes from the process; harness is not derived at runtime but template-injected at install time, the same way the installer fills capture-event's --harness flag. --session overrides the environment-derived id for the Rovo relay. A single O_APPEND write appends to ~/.codeassembly/events/{owner}/{name}/{sanitized-branch}/{session}.jsonl, with the branch name sanitized the way the branch manifest sanitizes branch names. Never-block contract: any failure warns on stderr and exits 0 — telemetry must not break the skill it observes.

Settled in design review: the payload arrives as --payload '<json>' (a JSON object, default {}); ts is millisecond-precision ISO-8601; an unknown --type warns on stderr but still appends, so the v0 vocabulary is convention rather than a gate; an unresolvable repo, branch, or session falls back to a placeholder path segment (_no-repo/_no-repo, _no-branch, _no-session) instead of dropping the event; the helper always prints a structured {ok, ...} result to stdout. The entrypoint is the skill helper, not an MCP tool (token analysis in comments).

Acceptance criteria

Must have

• A live Claude session appends valid envelopes with nothing supplied beyond --type and payload.
• --session overrides the environment-derived session id.
• Any emission failure warns on stderr and exits 0.
• An event with an unresolvable repo, branch, or session is appended under placeholder path segments rather than dropped.
• An unknown --type warns on stderr and the envelope is still appended.
• New behavior is covered by unit tests; the bundle has a smoke test.

Part of spike #985 (blocks its observation window).

[williamthorsen]

Entrypoint decision: skill helper, not MCP tool (token-cost analysis)

Considered exposing emit-event as an MCP tool instead of a bundled skill helper, with token use as the deciding criterion:

• Per emission, an MCP call saves roughly 25–30 tokens over the Bash invocation (~25–40 vs ~50–70 tokens). At 15–20 emissions per session that is ~400–600 tokens, about 0.2% of a typical session.
• Schema cost erodes the saving: Claude defers MCP tool schemas (~300–500 tokens on first use). Whether Rovo front-loads all MCP schemas into every session is unverified; if it does, the saving inverts on the harness that has no fallback channel.
• The dominant cost is channel-independent: the skill text saying when to emit and what payload to build. The channel-specific fragment differs by ~50–100 tokens per skill load, and a shared partial keeps the Bash template to one maintained copy.
• The Bash helper inherits the calling session's env and cwd by construction, so session, cwd, branch, and repo derive for free. An MCP server's env/cwd inheritance varies by harness and spawn model; anything it cannot derive server-side must be passed as arguments, spending back the saving.

Conclusion: savings are marginal at best and possibly negative under Rovo, so the skill helper stands as the entrypoint. The storage contract (append-only JSONL in the events root) is producer-agnostic, so an MCP producer can be added later without rework.