build(repo): add the one-command local stack

[systemfsoftware-maker]

Lake 1, U6 — stacked on #37.

pnpm dev (./bin/local-stack up) starts the local stack under process-compose with readiness probes and no cloud credentials (R63, without the site service that U7 adds):

Service	Ready probe
OpenTelemetry collector (otelcol-contrib 0.155.0), OTLP on :4318 HTTP and :4317 gRPC	:13133/
Tempo 3.0.3, monolithic, local storage under local-stack/data/tempo	:3200/ready
Grafana 13.1.6, anonymous admin, Tempo provisioned as the default data source	:3000/api/health

• The binaries come from the locked flake: nix/local-stack.nix is a writeShellApplication over process-compose and the three services. bin/local-stack copies the bin/dprint wrapper and adds cd to the repo root, since every path in process-compose.yaml is root-relative.
• Grafana's data, log, plugin and provisioning paths are passed as absolute cfg: overrides. Relative paths in grafana.ini resolve against Grafana's homepath in the Nix store; the first run showed can't read datasource provisioning files ... /nix/store/...-grafana-13.1.6/share/grafana/local-stack/grafana/datasources.
• local-stack/data/ is gitignored.

QA

$ ./bin/local-stack up -D -t=false && timeout 300 ./bin/local-stack project is-ready --wait
ready exit=0
$ ./bin/local-stack process list -o wide
NAME             STATUS    HEALTH
grafana          Running   Ready
otel-collector   Running   Ready
tempo            Running   Ready
$ curl -s :3000/api/datasources | jq -c '.[]|{uid,type}'
{"uid":"tempo","type":"tempo"}
# POST one OTLP/JSON span (service local-stack-qa, name qa.roundtrip) to :4318/v1/traces, read it back from Tempo
POST /v1/traces -> 200
GET :3200/api/v2/traces/fd0a6202e8a47d6d4a8f3691e13b7445 -> found, span "qa.roundtrip"
# Grafana Explore (Tempo, TraceQL = the trace id) renders "local-stack-qa: qa.roundtrip", 1 span, 5ms
$ ./bin/local-stack down
$ pnpm check:ci
check:ci exit=0

Screenshot: Grafana Explore showing the trace local-stack-qa: qa.roundtrip (taken with headless Chromium; the image is kept with the session evidence, not uploaded, since the GitHub CLI cannot attach images to PR bodies).

Fix commits after opening

• ed4b2cf build: local-stack down hung with Tempo stuck in Terminating. Once Tempo has taken spans, its live store loops in shutdown completing loop on SIGTERM, and process-compose escalates to SIGKILL only when shutdown.timeout_seconds is declared. Every process now declares 10 s. Reproduced first (stack up, spans sent, down still waiting after 5 min); after the fix, 20 OTLP spans then down → exit 0 in 10 s with Tempo killed. Tempo replays its WAL on the next start.

Review fixes (Kiro rulings, Lake 1 bottom review)

• Q1, pnpm dev with no terminal (ea247d9, CI leg 4f8ea78).
  • nix/local-stack.nix sets PC_DISABLE_TUI=1 when stdout is not a TTY.
  • bin/check-local-stack (pnpm check:ci-run) does the following:
    1. Starts ./bin/local-stack up with stdout redirected and TERM unset.
    2. Waits for project is-ready, then checks every readiness probe (13133, 3200 /ready, 3000 /api/health).
    3. Runs down, then waits until all eight ports are free.
  • check:ci runs it on Linux. Hosted Linux CI splits check:ci into legs, so it also has its own local-stack leg.
  • Red with the TUI block removed: pnpm dev exited before the stack was ready … FTL TUI startup error error="terminal entry not found: term not set", exit 1. Green: exit 0.
• Q3, Grafana downloads nothing at startup (c2767fa).
  • No Grafana plugin is needed: Explore and the Tempo datasource are built in. local-stack/grafana.ini sets [plugins] preinstall_disabled = true.
  • The check runs the whole stack in a network namespace with outbound traffic denied (unshare -rn, with bwrap --unshare-net as fallback). It proves the namespace is offline (curl: Could not resolve host: grafana.com) and fails if any log shows a plugin install.
  • Red with the [plugins] block removed: Grafana reached for a plugin with the network denied: Installing plugin, exit 1. Green: exit 0.

[systemfsoftware-maker]

Fix 4ce06fb (CI run 37400878461 root cause): Tempo 3 defaults its live-store marker/WAL, backend-scheduler and block-builder paths to /var/tempo, which only root can create. On the hosted runner the live store failed (mkdir /var/tempo: permission denied), the distributor followed, and Tempo stopped before ready; local runs as root hid it (/var/tempo exists on this host). All four now live under local-stack/data/tempo. Proof: Tempo run as uid 65534 with the old config stops with module failed module=live-store; with the new config it answers /ready and creates its marker dir under the repo. CI stack green on #42, #43, #45, #49.

[systemfsoftware-maker]

Dropped by the 2026-10-06 starter spec: pnpm dev runs alchemy dev, no local trace stack.