Add @codeassembly/lifecycle with the canonical envelope, vocabulary, and lane fold

[williamthorsen]

Problem

The canonical envelope and vocabulary live on the write side (packages/agents/src/emit-event/types.ts), and the only fold from events to lane state is throwaway spike code. The app needs both, and the repo's history shows what hand-copied schemas do: run-log-schema and event-folder drifted into duplicate copies in run-core and factory.

Context

• The Spike: can skill-emitted events drive a trustworthy live fleet view? #985 findings confirmed the envelope as-is: {id, ts, type, repo, branch, session, cwd, harness, payload}.
• The emit helper ships as an esbuild bundle inside installed skills, so a workspace dependency on the new library compiles in without changing the installed footprint.
• Settled lane model: lane = repo × sanitized branch name; sessions are sub-attributions with a harness attribute; lane state is a fold over the lane's event group, never a mutation.

Proposed solution

New package packages/lifecycle. Move the envelope schema and event vocabulary out of agents (which becomes an importer); add the production fold: events → lane state, covering session status derivation (working/waiting from turn.*, work narration from skill.*), session end, lane closure (merge/cleanup events or staleness), and ticket-ref parsing from branch names as a lane attribute — per the shared ticket-id-extraction contract (Jira-style key anywhere in the name, else numeric prefix), extended with .N revisit capture. The pattern contract is defined once here; session-context extraction in agents composes it with its config-dependent formatting. The fold is pure; server-side probes (e.g. worktree existence) feed it as inputs and are not part of this package.

The fold consumes parsed envelopes with caller-supplied lane and session identity; tolerant line and lane-path parsers ship as separate helpers, so file discovery and reading stay with the caller. The package is dependency-free: envelope checking is hand-rolled and tolerant, not a schema library — the envelope is deliberately loose telemetry, so validation would have nothing to reject. All exports are browser-bundle-safe; Node-only helpers, if any, live behind a separate subpath entry.

Acceptance criteria

Must have

• The envelope schema and vocabulary are defined once, in this package; the emit helper and hook relay import them, and the installed skill footprint is unchanged.
• The fold derives lane and session state (status, waiting, work narration, closure) from a lane's parsed events; file discovery and reading stay with the caller.
• A branch name encoding a ticket id — a Jira-style key anywhere in the name, or a numeric prefix, each with an optional .N revisit suffix — yields a ticket-ref lane attribute; other names yield a lane without one. The branch-name pattern contract is defined once, composed by session-context extraction.
• The package carries no runtime dependencies.
• The schema and fold entries import cleanly in a browser bundle (no Node builtins).
• New behavior is covered by tests.

[williamthorsen]

Implementation context (handoff for a cold session)

Everything below is verified against main as of 2026-07-19; the ticket body is the contract, this comment is the map.

Design record

• D1–D4 settlement comment on #984 — package homes, lane key, stack.
• Spike: can skill-emitted events drive a trustworthy live fleet view? #985 findings comment — envelope confirmation, vocabulary ratification, two-channel partition.

Source map

• Envelope and vocabulary (the move source): packages/agents/src/emit-event/types.ts. Sibling modules compose-envelope.ts, resolve-event-path.ts, write-event.ts become importers of the new package.
• Hook relay (second importer): packages/agents/src/relay-hook-event/, event mapping in hook-mappings.ts.
• Reference fold: spikes/fleet-view/serve.mjs — the spike's incremental fold, correct in shape but throwaway by charter. Supersede it here; its deletion belongs to Add the Foreman client shell with the lane view #1037.

Declared vocabulary (from types.ts)

Hook channel: session.started, session.ended, turn.started, turn.completed. Skill channel: skill.started, skill.completed, artifact.written, input.requested, pr.created. skill.progress stays declared as optional step-level detail. input.received is retired (#1027) and must not reappear.

Event store layout

{home}/.codeassembly/events/{owner}/{name}/{sanitized-branch}/{session}.jsonl (per resolve-event-path.ts). Note the repo key is two directory levels (owner, then name); the lane key is the sanitized-branch level beneath them.

Fold semantics

• Lane = repo × sanitized branch; sessions are sub-attributions keyed by session file, each carrying its harness.
• Working/waiting derives from turn.*: a turn.completed with no later turn.started means waiting. skill.* supplies work narration; input.requested carries the current ask payload.
• session.ended closes a session. Lanes close on merge/cleanup signals or staleness. The abnormal-end backstop (does the envelope's cwd still exist?) is a server-side probe arriving with Add the git adapter for working-tree and base-branch ground truth #1038: design the fold to accept probe results as inputs; do not implement probing here.
• Ticket-ref attribute: a branch of the form 984 or 984.2 (ticket id plus optional .N revisit suffix) parses to a ticket ref; any other branch leaves the attribute unset. Synthetic PR-123 attribution is Add the forge adapter for PR, CI, and ticket state #1039's concern.

Boundaries

Out of scope here: spike deletion (#1037), filesystem probing (#1038), PR resolution (#1039). In scope and easy to miss: the emit helper is esbuild-bundled into installed skills, so after the move, confirm the installed bundles carry no new runtime dependency (the "installed footprint unchanged" AC). Subpath-entry precedent for keeping Node-only code out of the browser path: run-core's . / ./parsers / ./scanners split.