stemtrace 0.3.6__tar.gz → 0.3.8__tar.gz

{stemtrace-0.3.6 → stemtrace-0.3.8}/.bumpversion.toml

@@ -1,10 +1,10 @@
 [tool.bumpversion]
-current_version = "0.3.6"
+current_version = "0.3.8"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true
-tag = false  # Tag created via GitHub Release UI
-commit_message = "chore: release v{new_version}"
+tag = false  # Tagged after the release PR merges (make release-tag)
+message = "chore: release v{new_version}"
 
 # Python package version in pyproject.toml
 [[tool.bumpversion.files]]
@@ -24,6 +24,21 @@ filename = "src/stemtrace/server/ui/frontend/package.json"
 search = '"version": "{current_version}"'
 replace = '"version": "{new_version}"'
 
+# Frontend package-lock.json: root version and the root package entry
+[[tool.bumpversion.files]]
+filename = "src/stemtrace/server/ui/frontend/package-lock.json"
+search = """"name": "stemtrace-ui",
+  "version": "{current_version}\""""
+replace = """"name": "stemtrace-ui",
+  "version": "{new_version}\""""
+
+[[tool.bumpversion.files]]
+filename = "src/stemtrace/server/ui/frontend/package-lock.json"
+search = """"name": "stemtrace-ui",
+      "version": "{current_version}\""""
+replace = """"name": "stemtrace-ui",
+      "version": "{new_version}\""""
+
 # uv.lock - keep workspace lockfile in sync (uv stores the local project version)
 [[tool.bumpversion.files]]
 filename = "uv.lock"
@@ -45,3 +60,10 @@ replace = """## [Unreleased]
 filename = "README.md"
 search = "[![PyPI version](https://img.shields.io/badge/pypi-v{current_version}-darklime)](https://pypi.org/project/stemtrace)"
 replace = "[![PyPI version](https://img.shields.io/badge/pypi-v{new_version}-darklime)](https://pypi.org/project/stemtrace)"
+
+# CHANGELOG compare links: advance [unreleased], add the new version's link
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v{current_version}...HEAD"
+replace = """[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v{new_version}...HEAD
+[{new_version}]: https://github.com/iansokolskyi/stemtrace/compare/v{current_version}...v{new_version}"""

{stemtrace-0.3.6 → stemtrace-0.3.8}/.dockerignore

@@ -2,9 +2,9 @@
 .git
 .gitignore
 
-# Python
-__pycache__
-*.py[cod]
+# Python (patterns without **/ only match at the context root)
+**/__pycache__
+**/*.py[cod]
 *$py.class
 *.so
 .Python
@@ -37,13 +37,23 @@ ENV/
 
 # Testing
 .pytest_cache/
+.mypy_cache/
+.ruff_cache/
 .coverage
 htmlcov/
 .tox/
 .nox/
 
 # Node (rebuilt in container)
-node_modules/
+**/node_modules/
+
+# Frontend build output and test artifacts (the UI is built in the
+# frontend stage; a local dist/ would be merged into the image's copy)
+src/stemtrace/server/ui/frontend/dist/
+src/stemtrace/server/ui/frontend/test-results/
+src/stemtrace/server/ui/frontend/playwright-report/
+src/stemtrace/server/ui/frontend/.tanstack/
+src/stemtrace/server/ui/frontend/tsconfig.tsbuildinfo
 
 # Documentation
 docs/_build/
@@ -53,9 +63,10 @@ docs/_build/
 .env.local
 *.log
 
-# Cursor/Editor
+# Cursor/Editor/agent tooling
 .cursor/
 .context/
+.claude/
 
 # Keep these (they're built in Dockerfile)
 !src/stemtrace/server/ui/frontend/package*.json

{stemtrace-0.3.6 → stemtrace-0.3.8}/.github/dependabot.yml

@@ -7,6 +7,10 @@ updates:
       interval: weekly
     commit-message:
       prefix: "chore(deps)"
+    ignore:
+      # Dependabot's uv updater fails on the build backend; updated by the
+      # weekly maintenance routine
+      - dependency-name: "hatchling"
 
   - package-ecosystem: npm
     directory: /src/stemtrace/server/ui/frontend
@@ -14,6 +18,10 @@ updates:
       interval: weekly
     commit-message:
       prefix: "chore(deps)"
+    ignore:
+      # Pinned to ^22: types must match the Node 22 runtime used in CI and Docker
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: github-actions
     directory: /
@@ -29,3 +37,10 @@ updates:
       interval: weekly
     commit-message:
       prefix: "chore(deps)"
+    ignore:
+      # The shipped Python runtime is deliberate: stay on 3.12.x patch updates
+      - dependency-name: "python"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+      # UI is built with Node 22 LTS: allow minor/patch updates only
+      - dependency-name: "node"
+        update-types: ["version-update:semver-major"]

{stemtrace-0.3.6 → stemtrace-0.3.8}/.github/workflows/ci.yml

@@ -135,7 +135,7 @@ jobs:
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Node.js
-        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "22"
           cache: "npm"
@@ -170,7 +170,7 @@ jobs:
           enable-cache: true
 
       - name: Set up Node.js
-        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "22"
           cache: "npm"

{stemtrace-0.3.6 → stemtrace-0.3.8}/.github/workflows/e2e.yml

@@ -153,7 +153,7 @@ jobs:
           sleep 5
 
       - name: Set up Node.js
-        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "22"
           cache: "npm"

{stemtrace-0.3.6 → stemtrace-0.3.8}/.github/workflows/release.yml

@@ -1,19 +1,9 @@
 name: Release
 
 on:
+  # Releases are tagged on main after the release PR merges (make release-tag).
   push:
     tags: ["v*"]
-  # Manual trigger from Actions tab
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Version to release (e.g., 0.1.0) - must match version in pyproject.toml"
-        required: true
-        type: string
-
-env:
-  # Determine version from tag or manual input
-  VERSION: ${{ github.event.inputs.version || github.ref_name }}
 
 jobs:
   build:
@@ -25,17 +15,14 @@ jobs:
       tag: ${{ steps.version.outputs.tag }}
     steps:
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          fetch-depth: 0  # full history for the "tag is on main" check
 
       - name: Determine version
         id: version
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
-            echo "tag=v${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
-          else
-            echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
-            echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
-          fi
+          echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+          echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
 
       - name: Verify version matches pyproject.toml
         run: |
@@ -50,13 +37,26 @@ jobs:
           fi
           echo "✅ Version $PYPROJECT_VERSION matches"
 
+      - name: Verify the tagged commit is on main
+        run: |
+          # Releases are tagged after the release PR merges; never from a branch.
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || {
+            echo "❌ ${GITHUB_REF_NAME} points at a commit that isn't on main"; exit 1; }
+
+      - name: Check release notes exist in CHANGELOG.md
+        run: |
+          # Fail before anything is published: every release needs notes.
+          python3 scripts/changelog_section.py "$VERSION"
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+
       - name: Set up Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
 
       - name: Set up Node.js
-        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "22"
           cache: "npm"
@@ -112,7 +112,7 @@ jobs:
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
@@ -158,17 +158,17 @@ jobs:
           name: dist
           path: dist/
 
-      - name: Create tag (for manual dispatch)
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "${{ needs.build.outputs.tag }}" -m "Release ${{ needs.build.outputs.tag }}"
-          git push origin "${{ needs.build.outputs.tag }}"
+      - name: Extract release notes from CHANGELOG.md
+        run: python3 scripts/changelog_section.py "$VERSION" > "$RUNNER_TEMP/release_notes.md"
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           tag_name: ${{ needs.build.outputs.tag }}
+          # CHANGELOG.md section first; GitHub appends contributors, PR list
+          # and the compare link.
+          body_path: ${{ runner.temp }}/release_notes.md
           generate_release_notes: true
           files: dist/*

{stemtrace-0.3.6 → stemtrace-0.3.8}/.gitignore

@@ -33,3 +33,4 @@ src/stemtrace/server/ui/frontend/src/routeTree.gen.ts
 src/stemtrace/server/ui/frontend/playwright-report/
 src/stemtrace/server/ui/frontend/test-results/
 src/stemtrace/server/ui/frontend/playwright/.cache/
+.release-notes.md

{stemtrace-0.3.6 → stemtrace-0.3.8}/.pre-commit-config.yaml

@@ -11,13 +11,15 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.0
+    rev: v0.16.10
     hooks:
       # Linter (auto-fix enabled)
-      - id: ruff
+      - id: ruff-check
         args: [--fix]
-      # Formatter
+      # Formatter (Python only: the hook also formats Markdown code blocks,
+      # which would undo the hand-aligned comments in the README examples)
       - id: ruff-format
+        types_or: [python, pyi]
 
   # Local hooks use project environment (uv) for proper dependency access
   - repo: local

{stemtrace-0.3.6 → stemtrace-0.3.8}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.8] - 2026-10-10
+
+### Fixed
+- `node_alias_from_arguments` can now be set on the standalone server and Docker image: `stemtrace server --node-alias-from-arguments <key>` or `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS=<key>` (a kwarg name or a positional index). `init_app()` reads the same env var when the argument isn't passed (#69).
+- RabbitMQ: publishing from workers no longer blocks tasks while the broker is down, stalled or in a memory/disk alarm. Each publish tries every host of the URL once with a 2s timeout; repeated or slow failures open a circuit breaker that drops events (instead of queueing them) until the broker answers again, and the worker logs at most four warnings a minute with counts of dropped events. The README's broker section has the details and limits.
+- RabbitMQ: the server's consumer now reconnects after the broker restarts or drops the connection; it used to retry forever on a dead channel.
+- RabbitMQ: a broker outage no longer floods the server log with one ERROR traceback per second; reconnects back off from 1s to 30s and log one line per attempt, plus one when the connection is back (thanks @ohadmata — #70, #71).
+- RabbitMQ: a message the consumer can't decode is dropped with a warning instead of blocking the queue forever.
+- RabbitMQ: stopping the server no longer waits out the reconnect delay or hangs on a frozen broker.
+
+### Added
+- Health endpoint: `consumer_connected` is now reported for RabbitMQ, so `/api/health` shows `degraded` while the server can't read from the broker.
+
+### Deprecated
+- `init_worker(node_alias_from_arguments=...)` has no effect (node names are resolved by the server) and now logs a deprecation warning; it will be removed in a future major release.
+
+## [0.3.7] - 2026-10-10
+
+### Changed
+- Docker: the image's `HEALTHCHECK` now calls the new `<prefix>/api/health/live` endpoint instead of `/stemtrace/api/health`, which returns 401 under form login (so containers with login enabled reported unhealthy). The liveness endpoint needs no session and checks only that the process is serving: it always answers 200, with an informational `{"status": "ok"}`, or `{"status": "degraded"}` by the same rule as `/api/health` (the event consumer stopped unexpectedly or can't read from the broker; a consumer stopped on purpose or whose event source finished is not degraded).
+- Docker image: updated the locked runtime dependencies `fastapi` 0.141.1 → 0.142.2 (which now pulls in `opentelemetry-api` 1.45.1; stemtrace doesn't configure tracing, so it stays a no-op), `pydantic` 2.12.5 → 2.13.5 (`pydantic-core` 2.41.5 → 2.46.5), `celery` 5.6.0 → 5.6.3, `typer` 0.21.0 → 0.27.3, `typing-extensions` 4.15.0 → 4.16.0 and `websockets` 15.0.1 → 16.1.1 (used by uvicorn's WebSocket support). Only the lockfile changed: the package's dependency ranges are the same, so pip installs are unaffected. With typer 0.27, `--help` shows option types as `<str>`/`<int>` instead of `TEXT`/`INTEGER`.
+- Docker image: building the image from a local checkout no longer copies the frontend's `node_modules/`, `dist/` or test artifacts into the build context, so stale local UI assets can't end up in the image.
+- UI: updated `@tanstack/react-query` 5.94.5 → 5.104.1 in the bundled frontend.
+
+### Fixed
+- Form login: clear warnings and an in-app explanation when sessions are rejected because workers/replicas don't share `STEMTRACE_LOGIN_SECRET`. Without an explicit secret each process signs cookies with its own random secret, so under `uvicorn --workers N`, gunicorn or several replicas a cookie issued by one process is rejected by the others (random 401s, unstyled UI, login loops). stemtrace now logs a startup warning when form login runs without a secret (mentioning `WEB_CONCURRENCY` > 1 or gunicorn when detected). In that mode, when a well-formed, unexpired session cookie fails signature verification and the issue time it carries (`iat`, now included in the signed session payload; unverified in this case and used only to classify the rejection, never to grant access) is after the process started (so it most likely came from a sibling worker or replica), it also logs a rate-limited warning (also for rejected WebSocket handshakes) and returns `"reason": "session_secret_mismatch"` in API 401 responses, and HTML routes redirect to the login page with `reason=session_mismatch`, which shows an explanation. Cookies from before a restart, and any badly signed cookie when a secret is configured, get a plain 401 / login redirect.
+- Form login: the static UI bundle under `/assets/` (the public open-source JS/CSS build, no data) is now served without a session, so the UI always loads and is styled instead of rendering a blank or unstyled page when a bundle request is rejected. The UI routes, API and WebSocket stay protected, and paths containing `.` or `..` segments (including percent-encoded variants), or an encoded `?` or `#` (`%3F`, `%23`), are rejected with 404 before any exemption applies. Exemptions are decided on the decoded path that routing matches, so e.g. `/api/health/live%3Fx` can't pass as the liveness probe. Paths under `assets/` that aren't real bundle files return 404 instead of the app shell.
+- UI: the Logout control is now a button in the header instead of a floating overlay injected by the server, which covered the connection status. On narrow screens the header wraps onto extra rows instead of overflowing, and the status tooltip stays inside the viewport.
+- UI: a 401 from the API (missing or expired session) now redirects to the login page with `next` set to the current page, instead of showing "Failed to load ..." errors. A 401 with `reason: "session_secret_mismatch"` shows an explanation instead, since signing in again wouldn't help. Redirects happen at most once per page and not again within a few seconds of the last one, which prevents redirect loops. The WebSocket reconnect now backs off exponentially (3s up to 60s) instead of retrying every 3s forever.
+- Task state no longer regresses when events arrive out of order. The sender-side `PENDING` event (from `task_sent`, which fires after publish) could reach the stream after the worker's `STARTED`/`SUCCESS`, and the task showed as `PENDING` again. Node state now comes from the most advanced event, and the result is the same for every arrival order. A terminal state (`SUCCESS`/`FAILURE`/`REVOKED`/`REJECTED`) always beats a non-terminal one, and between terminals the later one wins. Among other states, a newer attempt (higher `retries`) wins, then lifecycle order (`PENDING` < `RECEIVED` < `STARTED`/`RETRY`), with `STARTED` vs `RETRY` in the same attempt decided by time (a redelivered run after a connection-loss retry shows as `STARTED`). A task's events are kept in lifecycle order: the first attempt's `PENDING` then `RECEIVED` first (even when stamped after the task was received or finished), then everything else by timestamp, with a fixed order for identical timestamps. `first_seen`, `last_updated`, `duration_ms`, date filters, sorting and eviction follow that order instead of arrival order. Node aliases from task arguments (`node_alias_from_arguments`) are read from the first event that carries arguments, so a leading `RECEIVED` (which has none) no longer hides them. Task lists, task details and graphs are read from a single snapshot taken under the store lock, so a concurrent event can't make a response mix old and new data (e.g. a `?state=STARTED` filter returning a task that just finished). Naive event timestamps are treated as UTC. Exact duplicate events are ignored and not re-broadcast over the WebSocket.
+- UI: the task timeline and event history follow the same order as the API. They used to sort by retry count first, so a failure raised in the worker main process (hard time limit, lost worker), which Celery reports with `retries=0`, appeared before later attempts and produced negative durations. A late-stamped `PENDING` is shown first, with its time clamped to the first run.
+- The signal handler no longer raises `TypeError` when Celery cancels a running task (lost broker connection, cold shutdown): Celery sends `task_retry` without a `reason` on that path. The `RETRY` event is now created, with the exception text "cancelled by Celery". During a broker outage it still can't be delivered if stemtrace publishes through that same broker.
+
 ## [0.3.6] - 2026-10-10
 
 ### Security
@@ -148,7 +181,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **E2E test suite**: Docker API tests + Playwright browser tests
 - **Comprehensive test suite**: 350+ Python tests, 90%+ coverage
 
-[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.5...HEAD
+[unreleased]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.8...HEAD
+[0.3.8]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.7...v0.3.8
+[0.3.7]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.6...v0.3.7
+[0.3.6]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/iansokolskyi/stemtrace/compare/v0.3.2...v0.3.3

{stemtrace-0.3.6 → stemtrace-0.3.8}/CONTRIBUTING.md

@@ -136,6 +136,18 @@ uv lock --upgrade
 - Fire-and-forget pattern for publishers (never block)
 - Fakes over mocks in tests
 
+## Releasing (maintainers)
+
+Every release goes through a pull request into `main` and is published by CI from a tag on `main`.
+
+1. Add user-facing entries under `## [Unreleased]` in `CHANGELOG.md`.
+2. `make release-pr BUMP=patch|minor|major` runs the checks, creates `release/vX.Y.Z`, bumps the
+   version and opens a PR whose description is the changelog section.
+3. When CI is green, merge the PR with a merge commit (not squash or rebase).
+4. `make release-tag` tags the merge on `main`. The tag triggers the Release workflow, which
+   publishes to PyPI and GHCR and creates the GitHub Release from the changelog section. It
+   refuses to publish if the section is empty or the tag isn't on `main`.
+
 ## Questions?
 
 - Open an issue for bugs or feature requests

{stemtrace-0.3.6 → stemtrace-0.3.8}/Dockerfile

@@ -60,9 +60,10 @@ ENV PORT="8000"
 
 EXPOSE 8000
 
-# Health check (CLI server mounts API at /stemtrace prefix)
+# Health check (CLI server mounts API at /stemtrace prefix). The liveness
+# endpoint needs no login session and answers 200 while the process serves.
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD python -c "import httpx; httpx.get('http://localhost:8000/stemtrace/api/health').raise_for_status()"
+    CMD python -c "import httpx; httpx.get('http://localhost:8000/stemtrace/api/health/live').raise_for_status()"
 
 # Default command: run server
 ENTRYPOINT ["stemtrace"]

{stemtrace-0.3.6 → stemtrace-0.3.8}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install check types lint format test coverage clean ui-install ui-dev ui-build e2e e2e-api e2e-playwright build release-check version bump-dry bump-patch bump-minor bump-major release
+.PHONY: install check types lint format test coverage clean ui-install ui-dev ui-build e2e e2e-api e2e-playwright build release-check version bump-dry bump-patch bump-minor bump-major release release-pr release-tag
 
 # Install all dependencies
 install:
@@ -99,6 +99,8 @@ build:
 # Full pre-release checklist
 release-check:
 	@echo "=== Pre-release Checklist ==="
+	@echo "0. Checking CHANGELOG.md has [Unreleased] entries..."
+	@uv run python scripts/changelog_section.py Unreleased > /dev/null
 	@echo "1. Running all checks..."
 	$(MAKE) check
 	@echo ""
@@ -107,7 +109,6 @@ release-check:
 	@echo ""
 	@echo "✅ Ready to release!"
 	@echo ""
-	@echo "Next: make release"
 
 # =============================================================================
 # Versioning (bump-my-version)
@@ -126,7 +127,7 @@ bump-patch:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Bump minor version (0.1.0 -> 0.2.0)
 bump-minor:
@@ -134,7 +135,7 @@ bump-minor:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Bump major version (0.1.0 -> 1.0.0)
 bump-major:
@@ -142,20 +143,54 @@ bump-major:
 	@NEW_VER=$$(uv run bump-my-version show current_version); \
 	echo "✅ Version bumped to $$NEW_VER"; \
 	echo ""; \
-	echo "Next: make release"
+	echo "Note: releases use make release-pr, which runs the bump itself; this target is for manual use only"
 
 # Tag and push to trigger release workflow
 release:
-	@VERSION=$$(uv run bump-my-version show current_version); \
+	@echo "Releases go through a PR: make release-pr BUMP=patch|minor|major, then make release-tag."
+	@exit 1
+
+# Open a release PR: preflight, checks, release/vX.Y.Z branch, version bump, PR with notes.
+# Usage: make release-pr BUMP=patch|minor|major
+release-pr:
+	@set -e; \
+	case "$(BUMP)" in patch|minor|major) ;; *) echo "Usage: make release-pr BUMP=patch|minor|major"; exit 1;; esac; \
+	test "$$(git rev-parse --abbrev-ref HEAD)" = main || { echo "❌ Run from main"; exit 1; }; \
+	test -z "$$(git status --porcelain)" || { echo "❌ Working tree not clean"; exit 1; }; \
+	gh auth status >/dev/null 2>&1 || { echo "❌ gh is not authenticated (gh auth login)"; exit 1; }; \
+	git fetch -q --tags origin main; \
+	test -z "$$(git log HEAD..origin/main --oneline)" || { echo "❌ main is behind origin/main"; exit 1; }; \
+	NEW=$$(uv run bump-my-version show new_version --increment $(BUMP)); \
+	! git rev-parse -q --verify "refs/heads/release/v$$NEW" >/dev/null || { echo "❌ Local branch release/v$$NEW exists"; exit 1; }; \
+	test -z "$$(git ls-remote --heads origin "release/v$$NEW")" || { echo "❌ Remote branch release/v$$NEW exists"; exit 1; }; \
+	! git rev-parse -q --verify "refs/tags/v$$NEW" >/dev/null || { echo "❌ Tag v$$NEW exists"; exit 1; }; \
+	$(MAKE) release-check; \
+	git switch -c "release/v$$NEW"; \
+	uv run bump-my-version bump $(BUMP); \
+	NOTES=$$(mktemp); trap 'rm -f "$$NOTES"' EXIT; \
+	uv run python scripts/changelog_section.py "$$NEW" > "$$NOTES"; \
+	git push -u origin "release/v$$NEW" || { echo "❌ Push failed; local branch release/v$$NEW holds the bump commit"; exit 1; }; \
+	gh pr create --base main --head "release/v$$NEW" --title "chore: release v$$NEW" --body-file "$$NOTES" \
+		|| { echo "❌ PR creation failed; release/v$$NEW is pushed, open the PR manually"; exit 1; }; \
+	echo ""; \
+	echo "✅ Release PR opened for v$$NEW"; \
+	echo "Next: gh pr checks --watch, merge with a merge commit, then make release-tag"
+
+# Tag the merged release on main; the tag push triggers the Release workflow.
+release-tag:
+	@set -e; \
+	git switch -q main; \
+	git pull -q --ff-only origin main; \
+	VERSION=$$(uv run bump-my-version show current_version); \
 	TAG="v$$VERSION"; \
-	echo "Tagging $$TAG..."; \
+	SUBJECT=$$(git log -1 --format=%s); \
+	test "$$(git rev-list --parents -n 1 HEAD | wc -w)" -eq 3 || { echo "❌ HEAD of main is not a merge commit (merge the release PR with a merge commit)"; exit 1; }; \
+	case "$$SUBJECT" in *"/release/$$TAG"|*"release $$TAG"|*"release $$TAG "*) ;; *) echo "❌ HEAD of main is not the $$TAG release PR merge: $$SUBJECT"; exit 1;; esac; \
+	git fetch -q --tags origin; \
+	! git rev-parse -q --verify "refs/tags/$$TAG" >/dev/null || { echo "❌ $$TAG already exists"; exit 1; }; \
 	git tag -a "$$TAG" -m "Release $$TAG"; \
-	echo "Pushing to origin..."; \
-	git push origin main; \
 	git push origin "$$TAG"; \
-	echo ""; \
-	echo "✅ Released $$TAG"; \
-	echo "   → GitHub Actions will publish to PyPI and Docker"
+	echo "✅ Tagged $$TAG → Release workflow publishes PyPI, GHCR and the GitHub Release"
 
 # =============================================================================
 # E2E Testing

{stemtrace-0.3.6 → stemtrace-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stemtrace
-Version: 0.3.6
+Version: 0.3.8
 Summary: A lightweight Celery task flow visualizer
 Project-URL: Homepage, https://github.com/iansokolskyi/stemtrace
 Project-URL: Documentation, https://github.com/iansokolskyi/stemtrace#readme
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 
 **Zero-infrastructure Celery task flow visualizer**
 
-[![PyPI version](https://img.shields.io/badge/pypi-v0.3.6-darklime)](https://pypi.org/project/stemtrace)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.3.8-darklime)](https://pypi.org/project/stemtrace)
 [![Python](https://img.shields.io/pypi/pyversions/stemtrace.svg)](https://pypi.org/project/stemtrace/)
 [![CI](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml/badge.svg)](https://github.com/iansokolskyi/stemtrace/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/iansokolskyi/stemtrace/graph/badge.svg)](https://codecov.io/gh/iansokolskyi/stemtrace)
@@ -253,10 +253,6 @@ stemtrace.init_worker(
     scrub_sensitive_data=True,                 # Scrub passwords, API keys, etc.
     additional_sensitive_keys=frozenset({"my_secret"}),  # Add custom keys
     safe_keys=frozenset({"public_key"}),       # Never scrub these keys
-
-    # UI display
-    node_alias_from_arguments="operator_type", # Use kwargs["operator_type"] as node name
-    # node_alias_from_arguments="0",           # Or use args[0] (digit string = positional index)
 )
 
 # Introspection (after init)
@@ -336,6 +332,7 @@ stemtrace.init_app(
 |----------|-------------|---------|
 | `STEMTRACE_BROKER_URL` | Celery broker URL (used for on-demand worker/registry inspection). Also used as the default for `STEMTRACE_TRANSPORT_URL`. | `redis://localhost:6379/0` |
 | `STEMTRACE_TRANSPORT_URL` | Event transport URL (where stemtrace publishes/consumes events).  | Defaults to `STEMTRACE_BROKER_URL`. |
+| `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS` | Server only: show a task argument as the graph node name (see [Node Names from Task Arguments](#node-names-from-task-arguments)). Same as `--node-alias-from-arguments` / `init_app(node_alias_from_arguments=...)`. | Unset (task names are shown). |
 
 ### Supported Brokers
 
@@ -356,6 +353,36 @@ again once events are re-consumed.
   - Events already consumed/acked by the server are **gone**.
   - Events published while the server is down are only visible after restart if the server’s
     durable per-consumer queue still exists and the messages are still within TTL.
+  - Events that can't be published to RabbitMQ are dropped, not buffered on the worker, and a
+    broker outage doesn't slow tasks down. Each publish tries every host of the broker URL once
+    (2s connect timeout, 2s per read or write after that). A single quick failure, such as a
+    refused connection, drops only that event; a failure that took 0.5s or more (a timeout) or
+    three quick failures in a row make the worker skip publishing for a cooldown that grows from
+    1s to 30s and resets on the next successful publish.
+  - During a RabbitMQ memory or disk alarm, the broker accepts connections but stops reading
+    from publishers, so a publish is sent but never confirmed. The worker counts such events as
+    "sent but unconfirmed" (RabbitMQ may still deliver them once the alarm clears); after two
+    unconfirmed attempts in a row it retries only every 30s. Each attempt leaves one blocked
+    connection on the broker until the alarm clears, so expect 2 to 3 connections per worker
+    process in the first minute of an alarm and about 2 per minute after that, all released
+    when the alarm ends. Each retry also logs `Received method (10, 60) during closing channel 0`
+    from py-amqp's `amqp` logger (not stemtrace's): that's RabbitMQ's "connection blocked"
+    notice arriving while the connection closes.
+  - Logging is bounded: at most four warnings a minute however the broker behaves (failures,
+    an outage starting, an outage ending, and a summary). Each reports the number of events
+    dropped, and sent but unconfirmed, since the previous one, and losses are reported within
+    about 1.5 minutes even when the broker flaps.
+  - Limitation: a broker that answers but slowly (say, close to the 2s timeout for each step)
+    still costs every event several seconds, because publishes that eventually succeed don't
+    open the breaker.
+  - A failover broker URL (`amqp://h1//;amqp://h2//`) must list nodes of the same RabbitMQ
+    cluster: workers keep publishing to whichever host last worked, so the server must be able to
+    consume those events from any of them. Entries resolve as in kombu: a bare host (`;h2`)
+    takes user, password, port, virtual host and TLS options from the first entry, while a
+    URL-form entry (`;amqp://h2`) gets guest/guest unless it names credentials, and takes port
+    and virtual host from the previous entry only when it omits them (`//` means `/`). A host
+    that refuses the login ends that publish attempt without trying the later hosts, as in
+    kombu.
 - **Workers + Registry tabs**: stemtrace uses **Celery inspect** on demand to populate workers
   and registered tasks, so those pages work even if the server missed `worker_ready` events.
 - **If you need durable history across restarts**: point stemtrace events at Redis even if your
@@ -387,6 +414,15 @@ docker run -p 8000:8000 \
     ghcr.io/iansokolskyi/stemtrace
 ```
 
+Show a task argument as the graph node name (here `kwargs["operator_type"]`):
+
+```bash
+docker run -p 8000:8000 \
+    -e STEMTRACE_BROKER_URL=redis://host.docker.internal:6379/0 \
+    -e STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS=operator_type \
+    ghcr.io/iansokolskyi/stemtrace
+```
+
 Or with Docker Compose:
 
 ```yaml
@@ -430,9 +466,26 @@ stemtrace server \
     --transport-url redis://myredis:6379/0 \
     --host 0.0.0.0 \
     --port 8000 \
+    --node-alias-from-arguments operator_type \
     --reload  # For development
 ```
 
+#### Node Names from Task Arguments
+
+By default, graph nodes are labeled with the task name. Generic tasks (e.g. one `run_operator`
+task that does different things depending on its arguments) are easier to tell apart when the
+graph shows an argument instead:
+
+- `--node-alias-from-arguments operator_type` uses `kwargs["operator_type"]`
+- `--node-alias-from-arguments 0` uses `args[0]` (a digit string is a positional index)
+
+If the argument is missing, the task name is shown. This is a **server** setting: set it on
+`stemtrace server` (flag or `STEMTRACE_NODE_ALIAS_FROM_ARGUMENTS`, e.g. in Docker) or pass
+`node_alias_from_arguments` to `stemtrace.init_app(...)`. Surrounding whitespace is ignored, and
+`stemtrace server` prints `Node alias: <key>` at startup when it is set. Workers need
+`capture_args=True` (the default) so the arguments are available. Passing it to
+`stemtrace.init_worker(...)` has no effect and is deprecated.
+
 #### Protecting the Server (Built-in Login Page)
 
 ```bash
@@ -443,6 +496,10 @@ stemtrace server \
     --login-secret change-me
 ```
 
+Set `--login-secret` (or `STEMTRACE_LOGIN_SECRET`) to a long random value, and use the same
+value on every replica. Without it, each process generates its own random secret, so sessions
+only work within a single process and are lost on restart.
+
 #### High-Scale Production Setup
 
 Note: `stemtrace server` includes an embedded consumer today (single-process). A multi-process deployment mode is planned.
@@ -482,6 +539,7 @@ extension = stemtrace.init_app(
     embedded_consumer=True,     # Run consumer in FastAPI process
     serve_ui=True,              # Serve React dashboard
     auth_dependency=None,       # Optional auth (see below)
+    node_alias_from_arguments=None,  # e.g. "operator_type" or "0"; see Node Names from Task Arguments
 )
 ```
 
@@ -512,7 +570,19 @@ stemtrace.init_app(
 )
 ```
 
-This serves a sign-in page at `/stemtrace/login` and protects everything under `/stemtrace`.
+This serves a sign-in page at `/stemtrace/login` and protects the UI, API and WebSocket under
+`/stemtrace`. The static JS/CSS bundle under `/stemtrace/assets/` is the public UI build and is
+served without a session. So is `/stemtrace/api/health/live`, a liveness probe for load
+balancers and container health checks: it always answers 200 while the process is serving,
+with only `{"status": "ok"}`, or `{"status": "degraded"}` when the embedded consumer stopped
+unexpectedly or can't read from the broker (the same rule as `/stemtrace/api/health`).
+
+For any multi-process deployment (`uvicorn --workers N`, gunicorn, or several replicas behind
+a load balancer), set `login_secret` (or the `STEMTRACE_LOGIN_SECRET` env var) to the same long
+random value everywhere, e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`.
+Without it, each process signs sessions with its own random secret, and users get logged out
+at random. stemtrace logs a warning at startup in that case, and the login page and UI explain
+the problem when a session signed by another process is rejected.
 
 #### Built-in Auth Helpers (Basic / API key)
 
@@ -551,7 +621,7 @@ Because the status code stays 200, check `status` in the body if you want monito
 What is detected depends on the transport:
 
 - **Redis:** refused or reset connections, connect timeouts, repeated read timeouts, and consumer loop failures. On redis-py < 8 the default socket timeout is unbounded, so a half-open or hung broker connection may go unnoticed; add `?socket_timeout=…` or `?health_check_interval=…` to the broker URL if you need that.
-- **RabbitMQ:** connectivity isn't reported (`consumer_connected` is `null`), so `"degraded"` only reflects consumer loop failures.
+- **RabbitMQ:** refused or dropped connections and channel errors while connecting or draining, and consumer loop failures. The consumer connection is read about once a second and a read that times out counts as connected, so a half-open connection, or a broker that is frozen but keeps the socket open, may go unnoticed. Messages the consumer can't decode (not JSON) are dropped with a warning and don't count as failures.
 
 ## 🗺️ Roadmap