# HiveOS Trace CLI Quickstart

`hiveos-trace` is a standalone CLI wedge extracted from HiveOS tracing concepts.
It is built for operators and developers who want execution visibility, replay, and diagnosis without adopting the full HiveOS platform runtime.

## Install

```powershell
pipx install hiveos-trace
```

Alternative:

```powershell
python -m pip install -U hiveos-trace
```

From source:

```powershell
python -m pip install -e .
```

If `hive` is not recognized in your shell, use module form:

```powershell
python -m hiveos.hive --help
python -m hiveos.hive trace ls
```

Windows command shim note:
- `trace run` launches commands directly.
- If a shimmed executable fails direct launch, Hive retries with `cmd /c`.
- Manual explicit form remains valid:
```powershell
hive trace run --no-open -- cmd /c openclaw agent --session-id main --message "hello"
```

Verbose help mode:

```powershell
hive trace replay-plan --help-verbose
```

## Zero-to-One

```powershell
hive doctor
hive quickstart --no-open
hive trace ls --limit 5
```

## CLI Surface (v0.3.2)

Single source of truth:
- `docs/hiveos_trace_source_of_truth.md`

Authoritative command/flag reference:
- `docs/releases/hiveos-trace-command-reference-v0.3.2.md`

Use this quickstart doc for workflow guidance and examples, not full command-surface maintenance.

## Open Behavior

- `quickstart`, `trace run`, and `trace replay` default to no-open.
- Use `--open` to explicitly open UI for a run.
- `--no-open` always forces no-open.
- If `--open` is requested and the UI target is unavailable, Hive serves a local fallback run page.
- Set `HIVE_TRACE_OPEN_ON_RUN=true` if you want default-open behavior globally.

## Branding Stamp

- Footer stamp is shown only on screenshot-prone summary commands:
  - `hive trace ls`
  - `hive trace summary`
  - `hive trace diff`
  - `hive trace diagnose`
- Stamp format:
  - `- hiveos-trace v<version>`
- JSON outputs remain unchanged (no branding line is added).
- Disable stamp if needed:
  - `HIVE_TRACE_BRANDING_DISABLE=true`

## Terminal UX + Color

- Text output keeps stable `key=value` shape for easy parsing/scanning.
- JSON outputs are unchanged and never colorized.
- Color mode is global:
  - `--color auto` (default)
  - `--color always`
  - `--color never`
- Environment overrides:
  - `HIVE_TRACE_COLOR=auto|always|never`
  - `NO_COLOR=1` to force disable color
- Examples:
```powershell
hive --color always trace ls --limit 10
hive --color never trace replay-plan <run_id> --recommended --explain
```

## What This Gives You

- Run-level event lineage (`observe_run_started`, `observe_run_finished`)
- Step/output event capture from wrapped commands
- Checkpoint/rerun intent events for SDK-based flows
- Fast operator loop:
  - run (`trace run`)
  - summarize (`trace summary`)
  - tail (`trace tail`)
  - inspect (`trace show`)
  - compare (`trace diff`)
  - replay (`trace replay`)
  - replay preview (`trace replay-plan`)
  - diagnose (`trace diagnose`)
- Lifecycle hygiene (`trace ops archive|unarchive|prune|reconcile`)
- Liveness visibility on active runs (`trace ls` / `trace summary` show runtime state + last output activity age + heartbeat age)
- Team handoff path (`trace ops export`, `trace ops import`)
- Agentic lineage path (`trace flow ls/show/steps/diff`)

Run records are stored under `~/.hiveos-trace/runs`.
Default trace log path is `~/.hiveos-trace/logs/trace_events.log` unless overridden.

## SDK Integration (Optional)

```python
from hiveos.observe import observe_run, observe_step

def my_pipeline():
    with observe_run("daily-sync", metadata={"team": "platform"}) as run_id:
        observe_step(run_id, "extract.start", payload={"source": "s3"})
        observe_step(run_id, "extract.finish", payload={"rows": 1203})
```

Structured agent/tool helper events:

```python
from hiveos.observe import (
    observe_agent_step_start,
    observe_agent_step_end,
    observe_tool_call_start,
    observe_tool_call_end,
    observe_step_retry,
    observe_branch_decision,
)

observe_agent_step_start(run_id, "step:plan", flow_id="flow:42", step_name="planner")
observe_tool_call_start(run_id, "tool:web.search:1", flow_id="flow:42", step_id="step:search", parent_step_id="step:plan")
observe_tool_call_end(run_id, "tool:web.search:1", flow_id="flow:42", step_id="step:search", outcome="success")
observe_step_retry(run_id, "step:search", flow_id="flow:42", attempt=2, reason="low confidence")
observe_branch_decision(run_id, "step:branch.next", flow_id="flow:42", selected_branch="summarize", branches=["summarize", "retry"])
observe_agent_step_end(run_id, "step:plan", flow_id="flow:42", outcome="success")
```

Checkpoint + rerun intent:

```python
from hiveos.observe import observe_checkpoint, observe_rerun_request

observe_checkpoint(run_id, "ckpt-42", step_name="extract.finish", state_ref="state://pipeline/extract/42")
observe_rerun_request(run_id, from_checkpoint_id="ckpt-42", reason="retry with override")
```

## Proxy Capture Mode (Optional)

```powershell
hive trace run --proxy -- python agent.py
hive trace run --proxy --proxy-upstream https://api.openai.com/v1 -- python agent.py
```

## Insight Macros

Macros are composed from primitives and include provenance:

```powershell
hive trace insight explain <run_id>
hive trace insight drift <run_id_a> <run_id_b>
hive trace insight health --window 24h
```

Useful flags:
- `--json`
- `--show-source`
- `--emit-primitive`

## Share Runs Across Machines

Export a run:

```powershell
hive trace ops export <run_id> --bundle .\trace-bundles\run.bundle.json
```

Import on another machine:

```powershell
hive trace ops import --bundle .\trace-bundles\run.bundle.json
```

If the same run id already exists, remap during import:

```powershell
hive trace ops import --bundle .\trace-bundles\run.bundle.json --as-run-id observe-run:shared-001
```

## Flow Lineage Views

Flow-level commands let you inspect agentic execution structure when events include lineage fields.

```powershell
hive trace flow ls --limit 10
hive trace flow show <flow_id>
hive trace flow steps <flow_id> --json
hive trace flow diff <flow_id_a> <flow_id_b> --json
```

Lineage fields used by flow views:
- `flow_id`
- `step_id`
- `parent_step_id`
- `tool_call_id`
- `attempt`
- `step_type`

Notes:
- Flow commands ignore events that do not include `flow_id`.
- Existing non-lineage traces remain fully supported by run-level commands.

## Replay Controls

Replay stability principle:
- replay is stateful resume from validated protocol boundaries, not prompt reconstruction.
- canonical reference: `docs/hiveos_trace_replay_resume_contract_v1.md`
- replay execution requires resume admission (`resume_envelope.admission.allowed=true`).

Preview replay intent without execution:

```powershell
hive trace replay-plan <run_id> --from-step-id <step_id> --json
hive trace replay-plan <run_id> --recommended --json
hive trace replay-plan <run_id> --recommended --explain
```

Persist a replay-plan artifact for downstream tooling:

```powershell
hive trace replay-plan <run_id> --from-step-id <step_id> --emit-artifact --json
hive trace replay-plan <run_id> --from-step-id <step_id> --artifact-path .\tmp\replay-plan.json --json
```

Inspect persisted artifacts:

```powershell
hive trace artifacts ls --type replay_plan --json
hive trace artifacts show <artifact_id> --json
hive trace artifacts replay <artifact_id> --no-open
```

Execute directly from the validated plan:

```powershell
hive trace replay-plan <run_id> --from-checkpoint-id <checkpoint_id> --apply --no-open
```

List available anchors on a run:

```powershell
hive trace anchors <run_id>
hive trace anchors <run_id> --json
```

Emit a checkpoint marker from CLI (no SDK wiring required):

```powershell
hive trace checkpoint <run_id> <checkpoint_id> --step-name <step_name> --state-ref <state_ref>
hive trace checkpoint <run_id> --auto-id --from-step-id <step_id>
```

`trace anchors --json` includes `recommended_replay_anchors` with:
- ranked stability and replay admission hints
- boundary strength / idempotency risk
- failure proximity scoring around first failed boundary
- continuation utility scoring:
  - `replay_utility_score`
  - `continuation_viability`
  - `replay_utility_rationale`
- recommendation rationale used for ordering

Optional payload hints (when emitted by runtime/shims) that improve replay safety:
- `idempotency_hint` (`low|medium|high|unknown`)
- `side_effect` (`true|false`)
- `external_write` (`true|false`)

The core CLI wrapper now emits these hints on command lifecycle events by default.

## Release Validation

Before public release:
1. Run `.github/workflows/hive-trace-publish-testpypi.yml` (manual dispatch).
2. Validate clean install from TestPyPI.

```powershell
pipx install --pip-args="--index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" hiveos-trace
hive doctor
hive quickstart --no-open
```

Production release:
- Push tag format `hiveos-trace-v<version>` (example: `hiveos-trace-v0.3.2`) to trigger `.github/workflows/hive-trace-publish-pypi.yml`.
