Company Ops Overview API

GET /api/company/companies/:company_id/ops/overview

This endpoint is the first unified operations surface for the Company OS. It is meant to close the gap between the existing low-level pieces:

• Company OS tasks / goals / agents / governance / spend in Postgres
• operations.yaml under each company hsmii_home
• task-trail telemetry under memory/task_trail.jsonl
• the company console operator UI

What it returns

• company Basic company record from Postgres.
• ops_config Whether config/operations.yaml was found and validated for this company.
• overview Counts for goals, tasks, human-escalation load, agents, and spend.
• budgets Configured monthly budgets with current usage when computable.
• heartbeats Heartbeat schedule from operations.yaml plus persisted runtime state from memory/heartbeat_state.json.
• tickets Ticket list from operations.yaml.
• ticket_sync Result of mirroring configured operations.yaml tickets into Company OS tasks.
• org Org chart / role model from operations.yaml.
• governance_recent Recent governance events from Postgres.
• spend Spend totals grouped by kind and by agent_ref.
• audit Aggregated task-trail telemetry from memory/task_trail.jsonl.
• integration_status Simple booleans summarizing which orchestration features are configured or already implemented.

Context resilience

The overview endpoint is also the primary context recovery surface. When an agent loses session state — crash, restart, context window flush — it re-enters the system by calling this endpoint before doing anything else.

GET .../ops/overview returns:

• audit.task_trail — recent task-level execution history so a re-entering agent can reconstruct what was done and what was not
• governance_recent — open flags and unresolved approvals the agent must be aware of
• heartbeats — current heartbeat state so the agent knows whether scheduled work is overdue
• overview.tasks — counts by status so the agent can triage before acting

Context is not stored in agent memory or session. It lives in Postgres. Every agent entry should start with this call, not with assumptions about what was previously loaded. This is the answer to context decay: durable storage queried on demand, not fragile in-process state.

Repair visibility

Repair events — failures at any loop phase — appear in two places in the overview response:

• audit.failures — task trail entries with outcome: failure or event_type: phase_failure
• governance_recent — governance events of type phase_failure or escalation

Repair events are not filtered out of the overview. An operator or agent reading the overview always sees the current failure state. Suppressing failures is not an option the API offers.

When audit.failures is non-empty, the standard repair path is:

1. Read the failure entry to identify which phase failed and why
2. Re-hydrate task context: GET .../tasks/{task_id}/llm-context
3. Re-enter the failed phase with repair: true on the task
4. If two consecutive cycles fail, the task auto-escalates to approvals with escalation_reason set; this appears in governance_recent

Current limitations

• Hard-stop budgets are now enforced on task checkout.
• Role-scoped budget usage is only available when spend_events.agent_ref matches the configured role id used at checkout/runtime.
• Heartbeats are surfaced from config and runtime exists separately, but this endpoint only reflects lightweight persisted status, not full job telemetry.
• Ticket mirroring currently happens when this overview endpoint is fetched; it upserts Company OS tasks using capability_refs: [{kind: "ticket", ref: ...}].

Why this exists

The repo already had partial implementations of:

• budgets
• heartbeats
• tasks / handoffs
• org chart / workforce
• governance log
• spend ledger
• multi-company isolation
• operator UI
• bundle import/export
• audit trail telemetry

But they were spread across separate APIs and config files. This endpoint gives the UI and future orchestration code one integration point to build on.