Runtime And Operations

Runtime entrypoints

• main.py and agentic_trader.cli:app expose the same command surface
• no-argument agentic-trader opens the operator launcher and asks before starting Web GUI, daemon, Ink, Rich, setup, or model-service paths
• agentic_trader/workflows/run_once.py owns one strict cycle
• agentic_trader/workflows/service.py owns continuous and background orchestration
• observer and UI surfaces should read shared runtime state instead of inferring it

Runtime modes

The project already distinguishes different intents:

• operation: strict, paper-first, and readiness-sensitive
• training: replay and evaluation oriented, with more diagnostic latitude

The exact implementation can evolve, but docs and UI copy should respect those operational differences.

What operators need to see

If a surface claims to show runtime state, it should be able to surface:

• process identity or service status
• heartbeat truth
• current symbol or task
• stage or cycle count
• recent stdout and stderr logs
• model or provider readiness evidence
• stop and failure state when applicable

Use agentic-trader provider-diagnostics --json for a network-free view of the configured model routing, source ladder, degraded Yahoo fallback warning, and API-key readiness. Use agentic-trader v1-readiness --json before longer paper operation or Alpaca paper checks, and add --provider-check when the evidence bundle should actively call the configured model service. The default backend remains local paper; alpaca_paper is the external paper rehearsal path and requires credentials, the paper endpoint, and explicit enablement. V1 active trading must still pass the supported broker, manual approval, audit, risk, and kill-switch gates; there is no hidden live brokerage path.

The same network-free readiness truth is also part of dashboard-snapshot, the observer API (/provider-diagnostics and /v1-readiness), Rich runtime menu, Ink overview/runtime pages, and the Web GUI overview. For product-readiness QA, dashboard-snapshot --provider-check and evidence-bundle --provider-check --json include the active provider gate.

Continuous research loop direction

The research sidecar is moving toward a safe loop: pre-flight, monitor, analyze, propose, digest, then sleep. The loop can keep a watchlist fresh, explain source health, and score or queue broker-free proposal candidates; an explicit operator promotion step is still required before a candidate becomes a pending proposal.

It must not approve proposals, place orders, mutate policy, weaken runtime gates, or treat raw web text as instructions. Research output remains evidence; the strict runtime and explicit operator approval keep authority.

Daemon supervision truth is available through agentic-trader supervisor-status --json and the observer /supervisor endpoint. That payload includes runtime state, heartbeat/staleness, persisted service state, and stdout/stderr log tails without starting a second orchestrator.

App-managed local services

agentic-trader model-service status/start/stop/pull is the first app-managed Ollama slice. It binds loopback only, writes owner-only state/logs under runtime/model_service/, and never stops external Ollama processes. If another Ollama already owns the default port, the app-owned service can pick a nearby loopback port and reports whether the runtime base URL matches it.

agentic-trader webgui-service status/start/stop applies the same pattern to the local Web GUI: loopback bind, recorded app-owned state under runtime/webgui_service/, log tails, and no attempt to kill unrelated PIDs.

The remaining direction is broader parity:

• visible distinction between “idle”, “busy”, and “broken”
• model/profile selection for different agent roles from operator surfaces
• setup flows that can recommend provider/model choices without hidden installs

What not to infer from model traffic

Repeated requests to Ollama do not automatically mean the runtime is healthy. If a cycle looks stuck, inspect:

• runtime status
• stop request state
• recent service events
• model health
• actual errors recorded in the runtime layer

Incident checklist

When operator behavior looks wrong:

1. inspect runtime artifacts first
2. compare UI state with runtime state
3. inspect the latest error and recent log tail
4. only then decide whether the bug is UI, orchestration, or provider related