Event Types

All event types are defined in foundry-sdk/src/event.rs as the EventType enum. The string representation uses snake_case.

Every event carries these common fields:

Hello-World (engine validation)

greet_requested payload

greeting_composed payload

Vulnerability Remediation

vulnerability_detected payload

release_tag_audited payload

main_branch_audited payload

remediation_completed payload

Release Lifecycle

release_completed payload

release_pipeline_completed payload

Project Lifecycle

project_validation_completed payload

project_iteration_completed payload

project_maintenance_completed payload

project_changes_committed payload

project_changes_pushed payload

Local Install

Maintenance Workflow

Task Lifecycle

task_run_completed payload

Verdict-specific fields are gaps[], diagnosis, finding plus options[], or detail.

Campaign Formation

campaign_cancelled payload

Flattens the shared terminal payload (campaign, project, reason, cycles_completed, cycles_landed) so generic terminal observers parse it unchanged, and adds the operator's disposition choices.

An aborted run never reaches trace persistence, so aborted_event_id is the only handle onto its partial events in the JSONL log — foundry trace has nothing to show for it. aborted_trace_id is what correlates the cancellation with the work-item ledger: the killed cycle's item was recorded running under that trace, and a --now cancellation settles it cancelled (see The work queue).

Work-Item Ledger

The six events of the work-item ledger. They report the same durable record at different points in its life, so all six share one payload shape; the event type says which point, and state says where the item stands.

work_item_started pairs with work_item_settled rather than a work_item_completed: an item does not complete, it settles, into a state that may still hold an obligation. work_item_cancelled is emitted by foundry queue close and foundry queue cancel on the exact item's trace, and by foundry campaign cancel --now on the aborted cycle's trace.

Shared payload

disposition fields

Pacing

Both are emitted for the project system, durable and on Watch, after the pause state is saved.

Payload

campaign_advance_requested payload

campaign_advance_completed payload

stood_down means the advance applied nothing because the campaign was stopped before its cycle result arrived or while it formed. It dispatches nothing, changes no status and counts no cycle. Its work item settles landed.

Gate Orchestration

gate_resolution_completed payload

preflight_completed payload

Each results[] entry includes an optional duration_ms field (unsigned integer) recording how long the gate command took in milliseconds. This field is absent when loading results from events persisted before timing instrumentation was added.

A results[] entry also carries an optional fix_applied boolean: true when the gate initially failed but its fix_command repaired the working tree and the re-check then passed (a self-healed gate). The field is omitted when false, so it is absent for gates that passed clean and for events persisted before self-healing gates were added.

The output field is a bounded view: at most 200 lines per command run, with stdout and stderr tailed separately and a --- stderr --- line between them. A failed gate also carries an optional logs array: the absolute paths of the files under ~/.foundry/evidence/gate-logs/ that hold the complete stdout and stderr of each command the gate ran. The field is omitted when empty, so it is absent for passing gates and for events persisted before gate logs were added. See Gate output and full logs.

gate_verification_completed payload

Each results[] entry includes an optional duration_ms field (unsigned integer) recording how long the gate command took in milliseconds. This field is absent when loading results from events persisted before timing instrumentation was added.

A results[] entry also carries an optional fix_applied boolean: true when the gate initially failed but its fix_command repaired the working tree and the re-check then passed (a self-healed gate). The field is omitted when false, so it is absent for gates that passed clean and for events persisted before self-healing gates were added.

The output field is a bounded view: at most 200 lines per command run, with stdout and stderr tailed separately and a --- stderr --- line between them. A failed gate also carries an optional logs array: the absolute paths of the files under ~/.foundry/evidence/gate-logs/ that hold the complete stdout and stderr of each command the gate ran. The field is omitted when empty, so it is absent for passing gates and for events persisted before gate logs were added. See Gate output and full logs.

retry_requested payload

Validation

validation_requested payload

validation_completed payload

Maintenance Run Lifecycle

maintenance_run_started payload

maintenance_run_completed payload

Dependency Update Policy

dependency_updates_classified payload

In the before phase the payload also carries the gate-resolution fields (gates, actions and the rest of the chain context) forward to Execute Maintain.

major_upgrades_planned payload

In the nightly run the payload also carries the maintenance_summary_requested fields (project_trace_ids, skipped_projects, total_duration_ms, root_event_id).

Release Tag Audit

Agent Session Lifecycle

Emitted by foundryd whenever a Foundry-launched Claude Code agent session begins or ends. Used by visualisation tools (e.g. ops-visualizer) to show in-flight and historical agent activity, and to locate the per-session stream-json transcript on disk.

agent_session_started payload

agent_session_ended payload

interrupted sessions. An agent session is a child process of foundryd, so it dies when the daemon stops, and nothing records its end at that moment. On the next start, before it accepts work, foundryd reads the last 7 days of the event log (the same lookback as the interrupted maintenance-cycle recovery) for agent_session_started events with no agent_session_ended for the same session_id. Nothing can be running then, so each such session is dead. For each one, foundryd records an agent_session_ended with status interrupted, error daemon restarted, the original session's project and trace_id, and ended_at set to the daemon start time. The event is persisted to the event log and published on the Watch stream like any other. Because the end is in the log, a later start does not end the same session again. Unparseable lines in the log are skipped and do not stop the daemon from starting. usage and cost are absent: nothing measured the session's last moments.

Initiatives and findings

Lifecycle and finding facts belong to the existing span. Steering requests open an admitted workflow; the decision fact and action request retain its causation and initiative source.

Initiative lifecycle payloads include initiative, outcome, projects, intent_refs, members, status, authorized_by and budget. Owner actions also retain reason, decision or applicable_members as applicable. Readers can render the initiative and its member references directly.

finding_recorded retains id, finding_id, initiative, from, to, kind, text, refs, consumed_by and recorded_at. The source records its kind and ID. Automatic reviewer gaps and defect diagnoses identify the cycle and the result event. The source envelope names the initiative.

finding_consumed includes initiative, finding_id, member, work_item_id and the updated finding with its consumption records. Consumption follows an actual landing. Forming or preserving a cycle emits no consumption fact.

initiative_advance_requested carries initiative, an optional pinned member, operator_origin and trigger_id. A follow-up request also carries follow_up_of, with steer_id (the steer whose step caused it) and step (that steer's decision, such as relay). Foundry requests one only after an applied hold, relay, ask, escalate or stage while a member stays eligible, and never after a follow-up. Roots are paced on the campaign lane and deduplicated per initiative. A distinct trigger during assessment is retained for a subsequent assessment.

initiative_steered carries success, outcome, error, initiative, steer_id, prompt, decision, provider and the optional durable action. It also carries reason when nothing changed, eligible_members when the precheck found members that can advance, and follow_up_of when the assessment was a follow-up. Its decision is exactly one of advance, dispatch, hold, relay, ask, escalate, stage, done or wait. Only applied requests an action; every other outcome admits no work.

initiative_action_requested carries the persisted action, including its identity, initiative, typed decision, provider pairing and context fingerprint. The admission boundary compares current state before dispatch. Replay uses that identity to acknowledge the same work rather than dispatch it again. Audit findings also retain audit with the intent reference, classification, registered project, checked paths and explanation. Tracker close proposals remain on the initiative; slice 1 does not write Tracker state.

initiative_owner_action_recorded carries initiative, action_id, operator_origin and a typed action (hold, milestone or member_override). It is emitted after persistence and does not activate steering. The event envelope records its timestamp and identity.