Monitoring

NightShift exposes its full internal state through plain files. Any tool — a shell script, a dashboard, a CI runner — reads status.json and events.jsonl without a server or API key.

The Four Files

Every run creates a .nightshift/ directory in the current project folder. Four files drive all monitoring and control:

status.json

.nightshift/status.json

Complete state snapshot: all pipeline nodes, their statuses (pending/running/done/failed), cost breakdown, current phase, accumulated output, and audit log. Updated after every significant state change. This is the single source of truth for dashboards.

events.jsonl

.nightshift/events.jsonl

Append-only event stream. Each line is a JSON object. Captures node start, node done, node fail, attempt start, replan, evaluator score, cost checkpoint, and system messages. Use tail -f to stream live.

inbox.jsonl

.nightshift/inbox.jsonl

Inbound message queue. Messages written here flow to the Auditor and then to the Coordinator at the next replan. Used by nightshift inject and by the Investor when pushing pressure signals. Never delete this file during a run.

control

.nightshift/control

Control signal file. Writing stop triggers a graceful shutdown after the current node finishes. Writing output-now forces immediate output assembly from whatever has been completed so far.

status.json Schema

The file is human-readable. Key fields:

Field	Type	Description
`run_id`	string	Unique run identifier (UUID)
`phase`	string	`planning` \| `executing` \| `evaluating` \| `learning` \| `done` \| `failed`
`nodes`	object[]	Each pipeline node with `id`, `archetype`, `status`, `cost_usd`, `attempts`, `output_preview`
`cost_usd`	float	Total spend so far across all nodes and attempts
`quality`	int \| null	Evaluator quality score (1–5), null until evaluation completes
`output`	string \| null	Final assembled output, null until done
`started_at`	ISO 8601	Run start timestamp
`updated_at`	ISO 8601	Last state change timestamp
`investor_signal`	string \| null	Latest Investor pressure: `explore` \| `exploit` \| `deliver` \| `reboot`

events.jsonl Schema

Each line is a JSON object. Common event types:

events.jsonl — sample entries

// node lifecycle
{"type":"node_start","node_id":"researcher_0","archetype":"researcher","ts":"2026-03-24T14:22:01Z"}
{"type":"node_done","node_id":"researcher_0","cost_usd":0.042,"ts":"2026-03-24T14:22:38Z"}
{"type":"node_fail","node_id":"coder_1","error":"SyntaxError line 42","attempt":1,"ts":"..."}

// evaluation
{"type":"evaluation","quality":4,"can_improve":true,"ts":"2026-03-24T14:25:11Z"}

// investor signal
{"type":"investor_signal","signal":"explore","rationale":"3 failed attempts, same pattern","ts":"..."}

// cost checkpoint
{"type":"cost_checkpoint","total_usd":0.71,"budget_usd":2.0,"ts":"..."}

// replan
{"type":"replan","reason":"node_fail","new_nodes":["coder_1_retry"],"ts":"..."}
        

Watching a Live Run

Three ways to observe a run in progress:

CLI status command

terminal

# Snapshot — prints current status.json in readable form
nightshift status

# Watch mode — refreshes every 2s
nightshift status --watch

# Tail the event stream
tail -f .nightshift/events.jsonl | jq .
        

HTML dashboard

The repo includes a standalone dashboard at dashboard/index.html. Open it in any browser while a run is active — it reads status.json directly from disk via the File System Access API and auto-refreshes.

ⓘ

The dashboard works with zero server setup. Open dashboard/index.html in Chrome or Edge, click "Open Run Directory", select the .nightshift/ folder, and watch the live state.

Shell one-liner

watch.sh

# Print phase, quality, and cost every 3 seconds
watch -n 3 'jq -r "[.phase, (.quality|tostring), (.cost_usd|tostring)] | join(\" | \")" .nightshift/status.json'
        

Sending Control Signals

Three control signals are supported. They take effect at the next safe checkpoint — NightShift never kills a running node mid-execution.

Command	Effect
`nightshift stop`	Writes `stop` to the control file. The run finishes its current node, assembles any completed output, and exits cleanly. KB and AR are updated before exit.
`nightshift inject "message"`	Appends a message to `inbox.jsonl`. The Auditor picks it up at the next replan and delivers it to the Coordinator. Use this to redirect the run mid-flight.
`echo "output-now" > .nightshift/control`	Forces immediate output assembly. The run assembles whatever has been completed so far and writes it as the final output, then exits.

CI/CD Integration

Because the interface is plain files, NightShift integrates naturally into any CI pipeline:

ci.sh — wait for run and check quality

#!/bin/bash

# Start run in background
nightshift solve problem.yaml --bg

# Poll until done (max 10 minutes)
for i in $(seq 1 120); do
  phase=$(jq -r .phase .nightshift/status.json)
  if [[ "$phase" == "done" || "$phase" == "failed" ]]; then
    break
  fi
  sleep 5
done

# Check quality
quality=$(jq -r .quality .nightshift/status.json)
if [[ "$quality" -ge 3 ]]; then
  echo "Run passed with quality $quality"
  exit 0
else
  echo "Run failed or quality too low: $quality"
  exit 1
fi
        

Run History

NightShift keeps a history of completed runs under ~/.nightshift/history/ (global) and .nightshift/history/ (project-local). Each run is a directory named by run ID containing the final status.json and events.jsonl.

terminal

# List recent runs
nightshift history

# Show a specific run
nightshift history --run <run-id>

# Show last run's output
nightshift history --last --output
        

✨

History entries feed the Learning System. The Evaluator's quality scores and the Investor's valuations from past runs are what make future runs smarter. See Learning System for how this connects.

Production Monitoring

When running NightShift as a server-mode service (multi-user), the file-based protocol extends naturally to a database backend. The monitoring surface stays identical — only the storage layer changes.

Key metrics to track in production:

Run success rate — quality ≥ 3 as a percentage of all runs. This is the primary product KPI.
Cost per run — track p50/p95. Alert if a run exceeds 3x the rolling average (likely a stuck loop).
KB query latency — p50/p95/p99. LanceDB target: under 10ms at 99th percentile.
Evaluator calibration — average quality score over time. A declining trend means KB noise is rising; trigger a manual consolidation.
Investor signal distribution — if explore is dominant, the KB is sparse. If deliver is dominant, problems may be too complex for the budget.

← Previous Learning System Next → Contributing