argus-scout 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. argus_scout-0.1.0/.copier-answers.yml +22 -0
  2. argus_scout-0.1.0/.dockerignore +19 -0
  3. argus_scout-0.1.0/.github/workflows/ci.yml +27 -0
  4. argus_scout-0.1.0/.github/workflows/docs.yml +25 -0
  5. argus_scout-0.1.0/.github/workflows/quickstart.yml +25 -0
  6. argus_scout-0.1.0/.github/workflows/release.yml +163 -0
  7. argus_scout-0.1.0/.github/workflows/suite.yml +14 -0
  8. argus_scout-0.1.0/.gitignore +12 -0
  9. argus_scout-0.1.0/.suite-rules-baseline.json +8 -0
  10. argus_scout-0.1.0/CLAUDE.md +179 -0
  11. argus_scout-0.1.0/Dockerfile +30 -0
  12. argus_scout-0.1.0/LICENSE +21 -0
  13. argus_scout-0.1.0/Makefile +33 -0
  14. argus_scout-0.1.0/PKG-INFO +181 -0
  15. argus_scout-0.1.0/README.md +134 -0
  16. argus_scout-0.1.0/deploy/quickstart/README.md +144 -0
  17. argus_scout-0.1.0/deploy/quickstart/compose.gpu.yaml +16 -0
  18. argus_scout-0.1.0/deploy/quickstart/compose.yaml +127 -0
  19. argus_scout-0.1.0/deploy/quickstart/config/.env.example +10 -0
  20. argus_scout-0.1.0/deploy/quickstart/config/.gitignore +6 -0
  21. argus_scout-0.1.0/deploy/quickstart/config/approvals.yaml +33 -0
  22. argus_scout-0.1.0/deploy/quickstart/config/heartbeat.yaml +51 -0
  23. argus_scout-0.1.0/deploy/quickstart/config/scout.yaml +67 -0
  24. argus_scout-0.1.0/deploy/quickstart/config/signals.yaml +328 -0
  25. argus_scout-0.1.0/deploy/quickstart/config/tariff.yaml +44 -0
  26. argus_scout-0.1.0/deploy/quickstart/prometheus.yml +21 -0
  27. argus_scout-0.1.0/docs/api.md +157 -0
  28. argus_scout-0.1.0/docs/channels.md +472 -0
  29. argus_scout-0.1.0/docs/cli.md +326 -0
  30. argus_scout-0.1.0/docs/config.md +443 -0
  31. argus_scout-0.1.0/docs/narrative.md +142 -0
  32. argus_scout-0.1.0/docs/operations.md +128 -0
  33. argus_scout-0.1.0/docs/signals.md +190 -0
  34. argus_scout-0.1.0/docs/sources.md +202 -0
  35. argus_scout-0.1.0/examples/approvals.yaml +33 -0
  36. argus_scout-0.1.0/examples/heartbeat.yaml +51 -0
  37. argus_scout-0.1.0/examples/persona.yaml +34 -0
  38. argus_scout-0.1.0/examples/signals.yaml +328 -0
  39. argus_scout-0.1.0/examples/tariff.yaml +44 -0
  40. argus_scout-0.1.0/gpu-tenant.yaml +33 -0
  41. argus_scout-0.1.0/pyproject.toml +80 -0
  42. argus_scout-0.1.0/src/argus_scout/__init__.py +16 -0
  43. argus_scout-0.1.0/src/argus_scout/_version.py +24 -0
  44. argus_scout-0.1.0/src/argus_scout/approvals.py +339 -0
  45. argus_scout-0.1.0/src/argus_scout/budget.py +315 -0
  46. argus_scout-0.1.0/src/argus_scout/channels/__init__.py +109 -0
  47. argus_scout-0.1.0/src/argus_scout/channels/audio.py +268 -0
  48. argus_scout-0.1.0/src/argus_scout/channels/base.py +252 -0
  49. argus_scout-0.1.0/src/argus_scout/channels/dispatcher.py +338 -0
  50. argus_scout-0.1.0/src/argus_scout/channels/echo.py +303 -0
  51. argus_scout-0.1.0/src/argus_scout/channels/mask.py +476 -0
  52. argus_scout-0.1.0/src/argus_scout/channels/redeliver.py +106 -0
  53. argus_scout-0.1.0/src/argus_scout/channels/registry.py +197 -0
  54. argus_scout-0.1.0/src/argus_scout/channels/snapcast.py +382 -0
  55. argus_scout-0.1.0/src/argus_scout/channels/text.py +120 -0
  56. argus_scout-0.1.0/src/argus_scout/channels/webhook.py +186 -0
  57. argus_scout-0.1.0/src/argus_scout/cli.py +466 -0
  58. argus_scout-0.1.0/src/argus_scout/config.py +802 -0
  59. argus_scout-0.1.0/src/argus_scout/configdoc.py +503 -0
  60. argus_scout-0.1.0/src/argus_scout/cycles.py +388 -0
  61. argus_scout-0.1.0/src/argus_scout/engine.py +309 -0
  62. argus_scout-0.1.0/src/argus_scout/events.py +113 -0
  63. argus_scout-0.1.0/src/argus_scout/examples/env.example +25 -0
  64. argus_scout-0.1.0/src/argus_scout/examples/scout.yaml +176 -0
  65. argus_scout-0.1.0/src/argus_scout/gpu.py +135 -0
  66. argus_scout-0.1.0/src/argus_scout/heartbeat.py +330 -0
  67. argus_scout-0.1.0/src/argus_scout/inbox.py +331 -0
  68. argus_scout-0.1.0/src/argus_scout/llm.py +355 -0
  69. argus_scout-0.1.0/src/argus_scout/memory.py +125 -0
  70. argus_scout-0.1.0/src/argus_scout/narrative.py +591 -0
  71. argus_scout-0.1.0/src/argus_scout/persona.py +154 -0
  72. argus_scout-0.1.0/src/argus_scout/prometheus.py +260 -0
  73. argus_scout-0.1.0/src/argus_scout/py.typed +0 -0
  74. argus_scout-0.1.0/src/argus_scout/recommendations.py +171 -0
  75. argus_scout-0.1.0/src/argus_scout/scheduler.py +323 -0
  76. argus_scout-0.1.0/src/argus_scout/server/__init__.py +0 -0
  77. argus_scout-0.1.0/src/argus_scout/server/app.py +195 -0
  78. argus_scout-0.1.0/src/argus_scout/server/deps.py +22 -0
  79. argus_scout-0.1.0/src/argus_scout/server/guards.py +394 -0
  80. argus_scout-0.1.0/src/argus_scout/server/metrics.py +173 -0
  81. argus_scout-0.1.0/src/argus_scout/server/routes/__init__.py +32 -0
  82. argus_scout-0.1.0/src/argus_scout/server/routes/events.py +116 -0
  83. argus_scout-0.1.0/src/argus_scout/server/routes/models.py +59 -0
  84. argus_scout-0.1.0/src/argus_scout/server/routes/reads.py +154 -0
  85. argus_scout-0.1.0/src/argus_scout/server/routes/recommendations.py +126 -0
  86. argus_scout-0.1.0/src/argus_scout/severity.py +29 -0
  87. argus_scout-0.1.0/src/argus_scout/signals.py +660 -0
  88. argus_scout-0.1.0/src/argus_scout/sources/__init__.py +30 -0
  89. argus_scout-0.1.0/src/argus_scout/sources/base.py +81 -0
  90. argus_scout-0.1.0/src/argus_scout/sources/json_poll.py +265 -0
  91. argus_scout-0.1.0/src/argus_scout/sources/registry.py +191 -0
  92. argus_scout-0.1.0/src/argus_scout/sources/webhook.py +114 -0
  93. argus_scout-0.1.0/src/argus_scout/store/__init__.py +31 -0
  94. argus_scout-0.1.0/src/argus_scout/store/base.py +303 -0
  95. argus_scout-0.1.0/src/argus_scout/store/sqlite.py +962 -0
  96. argus_scout-0.1.0/src/argus_scout/tariff.py +228 -0
  97. argus_scout-0.1.0/src/argus_scout/tariff_rules.py +565 -0
  98. argus_scout-0.1.0/tests/api_helpers.py +47 -0
  99. argus_scout-0.1.0/tests/conftest.py +20 -0
  100. argus_scout-0.1.0/tests/test_api.py +389 -0
  101. argus_scout-0.1.0/tests/test_api_guards.py +297 -0
  102. argus_scout-0.1.0/tests/test_api_hardening.py +474 -0
  103. argus_scout-0.1.0/tests/test_approvals.py +201 -0
  104. argus_scout-0.1.0/tests/test_budget.py +93 -0
  105. argus_scout-0.1.0/tests/test_budget_store.py +178 -0
  106. argus_scout-0.1.0/tests/test_channels.py +782 -0
  107. argus_scout-0.1.0/tests/test_cli.py +192 -0
  108. argus_scout-0.1.0/tests/test_config.py +270 -0
  109. argus_scout-0.1.0/tests/test_configdoc.py +29 -0
  110. argus_scout-0.1.0/tests/test_dockerfile.py +74 -0
  111. argus_scout-0.1.0/tests/test_docs_publishable.py +113 -0
  112. argus_scout-0.1.0/tests/test_echo.py +404 -0
  113. argus_scout-0.1.0/tests/test_engine.py +369 -0
  114. argus_scout-0.1.0/tests/test_gpu.py +233 -0
  115. argus_scout-0.1.0/tests/test_heartbeat.py +151 -0
  116. argus_scout-0.1.0/tests/test_inbox.py +166 -0
  117. argus_scout-0.1.0/tests/test_llm.py +172 -0
  118. argus_scout-0.1.0/tests/test_memory.py +86 -0
  119. argus_scout-0.1.0/tests/test_metrics.py +152 -0
  120. argus_scout-0.1.0/tests/test_narrative.py +278 -0
  121. argus_scout-0.1.0/tests/test_persona.py +46 -0
  122. argus_scout-0.1.0/tests/test_prometheus.py +279 -0
  123. argus_scout-0.1.0/tests/test_quickstart.py +89 -0
  124. argus_scout-0.1.0/tests/test_recommendation_races.py +222 -0
  125. argus_scout-0.1.0/tests/test_redeliver.py +262 -0
  126. argus_scout-0.1.0/tests/test_scheduler.py +543 -0
  127. argus_scout-0.1.0/tests/test_signals.py +303 -0
  128. argus_scout-0.1.0/tests/test_smoke.py +8 -0
  129. argus_scout-0.1.0/tests/test_sources.py +454 -0
  130. argus_scout-0.1.0/tests/test_status_reports.py +332 -0
  131. argus_scout-0.1.0/tests/test_store.py +441 -0
  132. argus_scout-0.1.0/tests/test_tariff.py +116 -0
  133. argus_scout-0.1.0/tests/test_tariff_rules.py +437 -0
  134. argus_scout-0.1.0/tests/test_voice_channels.py +793 -0
  135. argus_scout-0.1.0/tests/test_workflows.py +50 -0
@@ -0,0 +1,22 @@
1
+ # Managed by Copier — do not edit by hand.
2
+ # Run `copier update` in this repo to pull template changes.
3
+ _commit: aec30cd
4
+ _src_path: gh:smk762/argus-pkg-template
5
+ author: smk762
6
+ brand_mark: false
7
+ cli_name: argus-scout
8
+ description: 'Homelab intelligence for the Argus suite: reads your telemetry, reasons
9
+ about it, and reports back with briefings and recommendations it never acts on'
10
+ dockerfile: Dockerfile
11
+ github_owner: smk762
12
+ has_cli: true
13
+ has_server: true
14
+ image_name: argus-scout
15
+ package_name: argus_scout
16
+ post_test: ''
17
+ project_name: argus-scout
18
+ python_min: '3.12'
19
+ ruff_pin: 0.15.16
20
+ test_extras: dev
21
+ version_build_arg: false
22
+
@@ -0,0 +1,19 @@
1
+ # NOTE: .git is deliberately *not* ignored -- hatch-vcs reads the version from
2
+ # git history at build time. Set `version_build_arg` if you want it excluded.
3
+ .github
4
+ .venv
5
+ venv
6
+ dist
7
+ build
8
+ *.egg-info
9
+ **/__pycache__
10
+ **/*.py[cod]
11
+ .pytest_cache
12
+ .ruff_cache
13
+ .mypy_cache
14
+ .coverage
15
+ htmlcov
16
+ # The quickstart's secrets and runtime state (deploy/quickstart/config) stay out of the image.
17
+ **/.env
18
+ deploy/quickstart/config/scout.db*
19
+ deploy/quickstart/config/scout-reports.log*
@@ -0,0 +1,27 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [dev, main]
6
+ pull_request:
7
+ branches: [dev, main]
8
+
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ ci:
18
+ uses: smk762/argus-ci/.github/workflows/python-ci.yml@v1
19
+ with:
20
+ ruff-version: "0.15.16"
21
+ test-extras: "dev"
22
+ python-versions: '["3.12", "3.13"]'
23
+
24
+ suite-rules:
25
+ # argus-ci suite rules: lint rules that each eliminate a finding class. New violations fail;
26
+ # existing ones are in .suite-rules-baseline.json, which may only shrink.
27
+ uses: smk762/argus-ci/.github/workflows/suite-rules.yml@v1
@@ -0,0 +1,25 @@
1
+ name: Docs
2
+
3
+ # Published docs (README.md + docs/**/*.md) are imported by the demo UIs at dev
4
+ # HEAD, so check them on every push to dev as well as on tags.
5
+ # docs/cli.md is generated: regenerate it with `make docs` after changing the CLI.
6
+
7
+ on:
8
+ push:
9
+ branches: [dev, main]
10
+ tags: ["v*"]
11
+ pull_request:
12
+ branches: [dev, main]
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ docs:
19
+ uses: smk762/argus-ci/.github/workflows/docs-check.yml@v1
20
+ with:
21
+ cli-module: argus_scout.cli
22
+ cli-name: argus-scout
23
+ install-extras: cli
24
+ secrets:
25
+ denylist: ${{ secrets.DOCS_DENYLIST }} # optional; unset = no private terms
@@ -0,0 +1,25 @@
1
+ name: Quickstart
2
+
3
+ # Not from argus-pkg-template: this repo's own check that deploy/quickstart still parses as compose.
4
+ # tests/test_quickstart.py (run by CI) checks the config and that its policy files match examples/.
5
+
6
+ on:
7
+ push:
8
+ branches: [dev, main]
9
+ pull_request:
10
+ branches: [dev, main]
11
+
12
+ permissions:
13
+ contents: read
14
+
15
+ jobs:
16
+ compose-config:
17
+ runs-on: ubuntu-latest
18
+ steps:
19
+ - uses: actions/checkout@v7
20
+ - name: docker compose config
21
+ working-directory: deploy/quickstart
22
+ run: |
23
+ docker compose version
24
+ docker compose -f compose.yaml config -q
25
+ docker compose -f compose.yaml -f compose.gpu.yaml config -q
@@ -0,0 +1,163 @@
1
+ name: Release to PyPI
2
+
3
+ # Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
4
+ # a reusable workflow. Keep this file in sync across the suite via `copier update`.
5
+
6
+ on:
7
+ push:
8
+ tags: ["v*"]
9
+ # Sent by argus-cortex's release workflow. The image installs argus-cortex
10
+ # from the pyproject range at build time, so rebuilding the newest release's
11
+ # image is how a new cortex reaches it. Only the image jobs run: PyPI and the
12
+ # GitHub Release for that tag already exist.
13
+ repository_dispatch:
14
+ types: [cortex-released]
15
+
16
+ permissions:
17
+ contents: read
18
+ id-token: write
19
+
20
+ jobs:
21
+ build:
22
+ # Not on a cortex dispatch, so the PyPI and Release jobs that chain off it
23
+ # skip too.
24
+ if: github.event_name == 'push'
25
+ runs-on: ubuntu-latest
26
+ steps:
27
+ - uses: actions/checkout@v7
28
+ with:
29
+ fetch-depth: 0
30
+ - uses: astral-sh/setup-uv@v7
31
+ with:
32
+ enable-cache: true
33
+ - run: uv build
34
+ - uses: actions/upload-artifact@v7
35
+ with:
36
+ name: dist
37
+ path: dist/
38
+
39
+ test-install:
40
+ runs-on: ubuntu-latest
41
+ needs: build
42
+ strategy:
43
+ matrix:
44
+ python-version: ["3.12", "3.13"]
45
+ steps:
46
+ - uses: actions/download-artifact@v8
47
+ with:
48
+ name: dist
49
+ path: dist/
50
+ - uses: astral-sh/setup-uv@v7
51
+ with:
52
+ enable-cache: true
53
+ - name: Install wheel and smoke-test import
54
+ run: |
55
+ uv venv --python ${{ matrix.python-version }}
56
+ uv pip install dist/*.whl
57
+ uv run --no-sync python -c "import argus_scout; print(f'argus-scout {argus_scout.__version__} OK')"
58
+
59
+ publish-testpypi:
60
+ runs-on: ubuntu-latest
61
+ needs: test-install
62
+ environment: testpypi
63
+ steps:
64
+ - uses: actions/download-artifact@v8
65
+ with:
66
+ name: dist
67
+ path: dist/
68
+ - uses: pypa/gh-action-pypi-publish@release/v1
69
+ with:
70
+ repository-url: https://test.pypi.org/legacy/
71
+
72
+ publish-pypi:
73
+ runs-on: ubuntu-latest
74
+ # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
75
+ # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
76
+ # publisher, an index outage — must not silently withhold the real release:
77
+ # that failure mode shipped argus-proof images for two tags with no wheel on
78
+ # PyPI, and nothing surfaced it because publish-image is independent.
79
+ # Only the build + install gate is required; a TestPyPI failure still marks
80
+ # the whole run failed, so the problem stays loud.
81
+ needs: [test-install, publish-testpypi]
82
+ if: "!cancelled() && needs.test-install.result == 'success'"
83
+ environment: pypi
84
+ steps:
85
+ - uses: actions/download-artifact@v8
86
+ with:
87
+ name: dist
88
+ path: dist/
89
+ - uses: pypa/gh-action-pypi-publish@release/v1
90
+
91
+ release-tag:
92
+ # The tag the image jobs build: the pushed one, or on a cortex dispatch the
93
+ # newest final release. A pre-release never moved `latest`, so a dispatch
94
+ # does not rebuild one.
95
+ runs-on: ubuntu-latest
96
+ outputs:
97
+ tag: ${{ steps.tag.outputs.tag }}
98
+ sha: ${{ steps.tag.outputs.sha }}
99
+ steps:
100
+ - uses: actions/checkout@v7
101
+ if: github.event_name == 'repository_dispatch'
102
+ - id: tag
103
+ env:
104
+ CORTEX_VERSION: ${{ github.event.client_payload.version }}
105
+ run: |
106
+ if [ "$GITHUB_EVENT_NAME" != repository_dispatch ]; then
107
+ echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
108
+ echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
109
+ exit 0
110
+ fi
111
+ refs=$(git ls-remote --tags origin 'refs/tags/v*')
112
+ tag=$(echo "$refs" | sed -n 's|.*refs/tags/\(v[0-9]*\.[0-9]*\.[0-9]*\)\(\^{}\)\{0,1\}$|\1|p' | sort -uV | tail -n1)
113
+ if [ -z "$tag" ]; then
114
+ echo "::notice::No release tag yet, so no image to rebuild for cortex $CORTEX_VERSION."
115
+ exit 0
116
+ fi
117
+ # An annotated tag lists its commit on the peeled ^{} line.
118
+ sha=$(echo "$refs" | awk -v t="refs/tags/$tag" '$2 == t {l = $1} $2 == t "^{}" {p = $1} END {print p ? p : l}')
119
+ echo "Rebuilding $tag ($sha) for cortex $CORTEX_VERSION."
120
+ echo "tag=$tag" >> "$GITHUB_OUTPUT"
121
+ echo "sha=$sha" >> "$GITHUB_OUTPUT"
122
+
123
+ publish-image:
124
+ runs-on: ubuntu-latest
125
+ needs: [release-tag, test-install]
126
+ # On a cortex dispatch test-install is skipped (nothing was built for PyPI),
127
+ # so the job runs on the tag alone.
128
+ if: "!cancelled() && needs.release-tag.outputs.tag != '' && (needs.test-install.result == 'success' || github.event_name == 'repository_dispatch')"
129
+ permissions:
130
+ contents: read
131
+ packages: write
132
+ steps:
133
+ - uses: actions/checkout@v7
134
+ with:
135
+ ref: ${{ needs.release-tag.outputs.tag }}
136
+ fetch-depth: 0 # hatch-vcs reads the tag from git history
137
+ - uses: docker/setup-buildx-action@v4
138
+ - uses: docker/login-action@v4
139
+ with:
140
+ registry: ghcr.io
141
+ username: ${{ github.actor }}
142
+ password: ${{ secrets.GITHUB_TOKEN }}
143
+ - id: meta
144
+ uses: docker/metadata-action@v6
145
+ with:
146
+ images: ghcr.io/${{ github.repository_owner }}/argus-scout
147
+ labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
148
+ tags: |
149
+ type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
150
+ type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
151
+ type=raw,value=latest
152
+ - uses: docker/build-push-action@v7
153
+ with:
154
+ context: .
155
+ file: ./Dockerfile
156
+ push: true
157
+ tags: ${{ steps.meta.outputs.tags }}
158
+ labels: ${{ steps.meta.outputs.labels }}
159
+ # A dispatch rebuilds an unchanged context, so a cached install layer
160
+ # would keep the old argus-cortex.
161
+ no-cache: ${{ github.event_name == 'repository_dispatch' }}
162
+ cache-from: type=gha
163
+ cache-to: type=gha,mode=max
@@ -0,0 +1,14 @@
1
+ name: Suite
2
+ on:
3
+ push:
4
+ branches: [dev, main]
5
+ tags: ["v*"]
6
+ pull_request:
7
+ branches: [dev, main]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ suite:
14
+ uses: smk762/argus-ci/.github/workflows/suite-check.yml@v1
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ # hatch-vcs writes this at build time (version derived from git tags)
10
+ src/argus_scout/_version.py
11
+ # secrets: init writes .env.example, the real .env stays local
12
+ .env
@@ -0,0 +1,8 @@
1
+ {
2
+ "version": 1,
3
+ "tools": {
4
+ "ruff": "0.15.16",
5
+ "semgrep": "1.180.0"
6
+ },
7
+ "entries": []
8
+ }
@@ -0,0 +1,179 @@
1
+ # CLAUDE.md — argus-scout
2
+
3
+ Guidance for AI agents working in this repo. Human-facing usage lives in [README.md](README.md); this file is the orientation an agent needs to change code safely.
4
+
5
+ > Scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template). Flesh out **Must never happen**, **Layout** and **Gotchas** below as the code grows — the suite conventions are already correct and shared.
6
+
7
+ ## What this is
8
+
9
+ Homelab intelligence for the Argus suite: reads your telemetry, reasons about it, and reports back with briefings and recommendations it never acts on.
10
+
11
+ **Advisory only.** Scout reads (Prometheus via PromQL, status events sent to it) and reports (briefings, recommendations). It never executes, deploys or dispatches anything, and never scrapes or connects to the hosts it reports on. A standing approval may move a recommendation to `approved`; nothing moves it further except a person.
12
+
13
+ Development runs in phases tracked by the epic issue in this repo. The policy core was ported from a private deployment (mithrandir) with its globals removed: every module takes its config explicitly.
14
+
15
+ Shared code — the target taxonomy, wire-schema versioning, and the local/remote model contract — lives in **argus-cortex**; import it rather than re-implementing.
16
+
17
+ ## Argus suite
18
+ <!-- argus-suite: keep this block; argus-ci checks for it -->
19
+ This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
20
+ building something a sibling may already do. **On every release, update this repo's row and capabilities in
21
+ argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
22
+
23
+ @../argus-core/SUITE.md
24
+
25
+ Not checked out? Read https://github.com/smk762/argus-cortex/blob/dev/SUITE.md
26
+
27
+ ## Must never happen
28
+
29
+ Each row names the test, CI job or lint that enforces it. Add a row for every rule this package must keep, and mark
30
+ it **UNENFORCED** until something checks it. When a rule bites, add a check rather than more prose.
31
+
32
+ | Never | Enforced by |
33
+ |---|---|
34
+ | A hand-edited version | `_version.py` is generated by hatch-vcs and gitignored |
35
+ | A new suite-rule violation (argus-ci's lint catalogue) | CI `suite-rules` job; `.suite-rules-baseline.json` may only shrink |
36
+ | A workflow testing a Python the package doesn't support | `tests/test_workflows.py` (every `python-version` in `.github/workflows/*.yml` satisfies `requires-python`) |
37
+ | A CLAUDE.md without the argus-suite block | CI `suite` job (argus-ci suite-check) |
38
+ | A state-changing route without the bearer token (failing closed), the read-only guard and the origin guard | `tests/test_api_guards.py`: `test_every_write_route_is_guarded` walks every route (through included routers) with `server.guards.unguarded_routes`, and `test_walker_flags_an_unguarded_route` proves it bites; the same walk drives real requests (`test_no_token_configured_refuses_every_write`, `test_missing_or_wrong_token_is_401`, `test_read_only_refuses_every_write_even_with_the_token`, `test_untrusted_origin_is_refused`, `test_oversized_bodies_are_413`) |
39
+ | A caller-supplied path outside a configured root | No route takes a filesystem path today. `tests/test_api_guards.py` (`test_no_route_touches_the_filesystem`: no mounts, no file APIs in `server/`); a route that needs one fences it under a root and adds a test |
40
+ | An unbounded request body | Write routes read through `argus_cortex.limits.read_body` (`server.guards.read_bounded` / `read_json`), never a FastAPI body parameter; `tests/test_api_guards.py` (`test_oversized_bodies_are_413`, `test_oversized_chunked_body_is_413`, `test_auth_runs_before_the_body_is_read`) |
41
+ | Scout moving a recommendation past `approved` | `tests/test_approvals.py` (`test_file_rule_auto_approves_and_audits`; `test_no_code_path_sets_deployed` walks `src/` and fails on any `Status.DEPLOYED` or `"deployed"` outside `recommendations.py`); `tests/test_engine.py` (`test_engine_never_moves_anything_past_approved`, `test_approved_is_never_retired_by_the_engine`) |
42
+ | A standing approval for a guarded proposal raised by the engine | `tests/test_engine.py` (`test_guardrails_refuse_auto_approval`) |
43
+ | A standing approval surviving escalation past a guardrail (it is retired and a fresh `proposed` one raised; a manual approval keeps its approval with a note) | `tests/test_engine.py` (`test_standing_approval_does_not_survive_escalation_past_a_guardrail`, `test_escalated_standing_approval_is_reproposed_despite_an_old_rejection`, `test_manual_approval_survives_escalation_with_a_note`) |
44
+ | A Prometheus outage read as "all clear" (retiring proposals as cleared) | `tests/test_engine.py` (`test_unknown_never_clears`, `test_analysis_cycle_raises_and_survives_an_outage`); `tests/test_signals.py` (`test_outage_is_unknown_and_keeps_pending_state`) |
45
+ | A rejected proposal re-raised without escalating or aging out | `tests/test_engine.py` (`test_rejected_key_is_not_reraised`, `test_escalation_beyond_the_rejected_severity_reraises`, `test_rejection_ttl_lets_a_key_back`) |
46
+ | A manual decision overwritten by a concurrent engine cycle | `SqliteStore.save_recommendation` checks `expected_status` and the lifecycle inside one `BEGIN IMMEDIATE` transaction (`StaleRecommendation` / `IllegalTransition`, nothing written); `tests/test_recommendation_races.py` (`test_manual_decision_survives_a_concurrent_engine_refresh`, `test_manual_approval_survives_a_concurrent_engine_retire`, `test_standing_approval_loses_to_a_person_who_decided_first`, `test_retire_first_then_stale_manual_approval_is_refused`, `test_store_refuses_an_illegal_transition`) |
47
+ | A read (or any route but `/health` and `/metrics`) served to a DNS-rebinding `Host` | `server.guards.HostGuard`, outermost: a `Host` that isn't an IP literal, `localhost` or a `server.trusted_hosts` name is a 400 (`server.guards.rebind_proof`, mirroring argus-cortex's same-host rule without importing its private helpers; `test_host_rule_matches_argus_cortex` checks parity); `unguarded_routes` fails if it is missing or not outermost. `tests/test_api_guards.py` (`test_the_host_guard_covers_every_route` walks every route and method, `test_walker_flags_a_host_guard_that_is_not_outermost`), `tests/test_api_hardening.py` (`test_a_rebinding_host_is_refused_on_every_route`, `test_ip_literals_and_localhost_pass`, `test_a_configured_trusted_host_passes_reads_and_same_origin_writes`) |
48
+ | A decision applied to content the person didn't see, or a decision (or engine write) reverting a newer save | every save bumps the recommendation's revision (migration 9, `recommendation_revisions`); `DecisionBody.revision` is required and `SqliteStore.update_recommendation` checks it and applies the decision to the stored row in one `BEGIN IMMEDIATE` transaction; the engine passes `expected_revision`. `tests/test_api_hardening.py` (`test_a_decision_on_content_the_person_never_saw_is_refused`, `test_a_decision_never_reverts_the_engines_escalation`, `test_the_revision_is_required`, `test_store_checks_and_bumps_the_revision`, `test_engine_save_is_refused_when_content_changed_since_its_load`) |
49
+ | An unauthenticated caller learning which sources exist (404/405 before the credential check) | `server.guards.source_auth` checks credentials first and answers a name that isn't a push source as a push source would (401, or 503); `tests/test_api_hardening.py` (`test_unauthenticated_pushes_get_the_same_401`, `test_no_server_token_closes_unknown_and_known_sources_alike`, `test_the_server_token_still_learns_what_is_wrong`) |
50
+ | The API schema and docs served without the bearer check when `read_auth` is on | `create_app` drops `/docs`, `/redoc` and `/openapi.json` under `read_auth`; `tests/test_api_hardening.py` (`test_docs_are_off_under_read_auth`) |
51
+ | Part of a push batch stored when a store error stops it (a retry then calling the stored part "refreshed") | `Inbox.ingest_many` stores the batch in one `SqliteStore.transaction()`; `tests/test_api_hardening.py` (`test_a_store_error_mid_batch_stores_nothing`) |
52
+ | A plugin's parse error leaking its internals or answering 500 | `tests/test_api_hardening.py` (`test_plugin_parse_errors_are_400_without_internals`) |
53
+ | A signal template reaching attributes, indexes or arbitrary format specs | `tests/test_signals.py` (`test_template_tricks_are_refused`) |
54
+ | A missing, bad or gappy tariff (or a Prometheus outage) crashing a tariff rule or reading as "all clear" | `tests/test_tariff_rules.py` (`test_shift_unknown_and_skipped`, `test_plan_comparison_unknown_paths`, `test_analysis_cycle_without_a_tariff_skips_only_tariff_rules`) |
55
+ | A plan comparison (a range query over weeks) running more than once a day, restarts included | `tests/test_tariff_rules.py` (`test_plan_comparison_runs_at_most_daily_even_across_restarts`; the schema refuses `every` under 1d in `test_bad_tariff_rules_are_skipped_with_reasons`) |
56
+ | A standing approval for a high-impact or critical proposal, whatever the rules say | `tests/test_approvals.py` (`test_guardrails_override_permissive_rules`, `test_runtime_rule_refused_for_guarded_proposal`); after approval too: `tests/test_engine.py` (`test_standing_approval_does_not_survive_escalation_past_a_guardrail`) |
57
+ | A bad edit to a policy or approvals file stopping status updates | `tests/test_heartbeat.py` (`test_bad_file_falls_back_to_defaults`), `tests/test_approvals.py` (`test_bad_rules_skipped_others_kept`), `tests/test_scheduler.py` (`test_bad_heartbeat_file_keeps_status_cycle_alive`) |
58
+ | A failing job (or source) stopping the scheduler or the other jobs | `tests/test_scheduler.py` (`test_failing_job_is_isolated_counted_and_retried`, `test_poll_jobs_ingest_and_one_failing_source_is_isolated`) |
59
+ | A restart repeating a briefing, or replaying missed ones in a burst | `tests/test_scheduler.py` (`test_no_double_fire_after_restart`, `test_no_catch_up_storm`) |
60
+ | A config change renaming a briefing job (losing its run history and re-firing it), or two briefings in one slot | job names are always `briefing:<kind>@HH:MM`; `tests/test_scheduler.py` (`test_briefing_job_names_do_not_depend_on_how_many_share_a_kind`), `tests/test_config.py` (`test_invalid_config_raises`: duplicate briefing) |
61
+ | LLM output parsed into an action (approving, rejecting or running anything) | `tests/test_narrative.py` (`test_model_output_is_never_parsed_into_an_action`: a model reply full of approve/deploy/JSON commands leaves every recommendation as it was and is stored verbatim as text); `llm.clean_output` strips control characters and `<think>` blocks (`tests/test_llm.py::test_output_is_cleaned_untrusted_text`) |
62
+ | A briefing silently skipped when the LLM is down, over its cap or not configured | `tests/test_narrative.py` (`test_budget_refusal_falls_back_to_template`, `test_llm_error_falls_back_to_template`, `test_no_model_and_no_llm_use_the_template`, `test_briefing_job_without_a_model_still_stores`): the template report is stored with `meta.path=template` and `meta.fallback_reason` |
63
+ | A model call over the daily `llm_calls` cap | `tests/test_llm.py` (`test_budget_charged_before_the_call_and_refused_over_cap`: charged before the call, refused calls never reach the model) |
64
+ | A memory path outside its root (`../`, absolute, or a symlink out), or scout writing an operator note | `tests/test_memory.py` (`test_traversal_is_refused`, `test_symlink_out_of_root_is_refused`, `test_scout_file_symlinked_out_is_never_written_through`, `test_scout_writes_only_its_own_file`) |
65
+ | A bad persona file stopping a briefing | `tests/test_persona.py` (`test_bad_file_degrades_to_default_and_recovers`, `test_missing_file_degrades_to_default`), `tests/test_narrative.py` (`test_bad_persona_degrades_and_is_recorded`) |
66
+ | A prompt that overflows a small model's context, or a cut that drops a severe fact before a minor one | `tests/test_narrative.py` (`test_truncation_drops_least_severe_first`, `test_selection_is_monotonic_by_tier`) |
67
+ | A crash loop resetting the daily usage caps | `tests/test_budget.py` (`test_counts_survive_restart`), `tests/test_budget_store.py` (`test_store_counts_survive_restart`) |
68
+ | The daily caps resetting at the host's midnight instead of `schedule.timezone`'s | `tests/test_budget_store.py` (`test_caps_reset_at_midnight_in_the_schedule_timezone`, `test_caps_follow_the_schedule_timezone_on_the_wall_clock`) |
69
+ | A CLI command that speaks or calls the model outside the daily caps | `tests/test_channels.py` (`test_cli_deliver_charges_the_speech_caps`); `brief` passes `budget_from_config` (`analyze` and `poll` charge nothing) |
70
+ | A URL in the config that passes `check config` and then fails at startup (bad port or no host) | `tests/test_config.py` (`test_invalid_config_raises`: `http://echo:80x`, `http://prom:99999`, and a source, channel and LLM URL) |
71
+ | Daily caps (`llm_calls`, `tts`, `speak`, any kind) exceeded, or counts lost, by concurrent processes (the server and a CLI `brief` sharing the store) | `SqliteStore.consume_usage`: one upsert whose `WHERE` is the limit check, inside `BEGIN IMMEDIATE`; `tests/test_budget_store.py` (`test_two_processes_lose_no_count_and_never_exceed_the_cap`, `test_four_connections_share_one_cap`, `test_server_and_cli_count_in_the_store`) |
72
+ | A briefing skipped because no GPU lease was granted | `tests/test_gpu.py` (`test_briefing_without_a_lease_falls_back_to_the_template`: stored from the template with `fallback_reason: gpu_unavailable`; `test_no_lease_is_gpu_unavailable_and_not_charged`) |
73
+ | Scout holding a GPU lease around echo synthesis (or anything but its own model call) | `tests/test_gpu.py` (`test_only_the_narrative_guard_takes_a_lease` walks `src/` for `.lease(`/`.alease(` outside `gpu.py`; `test_lease_is_released_before_generate_returns`); `tests/test_echo.py::test_no_gpu_lease_is_taken_around_synthesis` |
74
+ | A `gpu-tenant.yaml` that stops validating or drifts from the lease defaults | `tests/test_gpu.py` (`test_manifest_validates_and_matches_the_lease_defaults`) |
75
+ | Scout starting on an invalid top-level config (unlike the policy files, which degrade to defaults) | `tests/test_config.py` (`test_invalid_config_raises`, `test_serve_refuses_invalid_config`) |
76
+ | A list or mapping in `scout.yaml` whose entries are all commented out (null) failing the config | `config.NullAsEmptyList` / `NullAsEmptyDict` on every such field; `tests/test_config.py` (`test_entries_commented_out_at_any_depth_read_as_empty`) |
77
+ | The container image pointing at a missing entry point | `tests/test_dockerfile.py` (`test_image_command_targets_exist` resolves the CMD's console script and command, or a `module:attr`; `test_image_config_env_matches_the_serve_option`) |
78
+ | A secret value in the config model's repr or dumps (the YAML holds env-var names, not values) | `tests/test_config.py` (`test_secrets_resolve_from_dotenv_and_never_appear`); the model holds env-var names only, validated as names |
79
+ | Scout querying a host directly instead of Prometheus | `tests/test_prometheus.py`: `test_only_the_configured_prometheus_is_contacted` (real `afetch`, stubbed transport: every request goes to the configured host, GET, `/api/v1/query[_range]` only; a redirect elsewhere is refused) and `test_no_module_contacts_hosts_directly` (no module imports a network client; only `prometheus.py`, `sources/json_poll.py`, `channels/webhook.py`, `channels/mask.py`, `channels/snapcast.py` and `channels/echo.py` use `argus_cortex.net`'s fetch, only `channels/snapcast.py` opens a raw socket, to its configured snapserver's control port, and only `channels/mask.py` imports `websockets`, for argus-mask's source socket at its configured host, pinned by `check_url` with no redirects: `tests/test_voice_channels.py` `test_mask_ws_goes_only_to_the_configured_host`). Pollers fetch only their configured status URL (`tests/test_sources.py`: `test_poll_once_uses_the_guarded_fetch_with_config_host_allowed`, `test_poll_once_through_argus_cortex_net_reaches_a_lan_host`) |
80
+ | A webhook push accepted when no token is configured, or with another source's token | `tests/test_sources.py` (`test_webhook_token`, `test_webhook_token_falls_back_to_server_token_and_fails_closed`) |
81
+ | A webhook producer speaking as a different source, or half a malformed batch ingested | `tests/test_sources.py` (`test_webhook_rejects_malformed_bodies`), `tests/test_api_hardening.py` (`test_a_store_error_mid_batch_stores_nothing`) |
82
+ | A broken source or channel plugin, or bad `sources:`/`channels:` entry, stopping the others (a plugin model raising anything, not only a `ValidationError`) | `tests/test_sources.py` (`test_bad_source_entries_do_not_stop_the_others`, `test_a_plugin_model_raising_anything_fails_only_its_entry`), `tests/test_channels.py` (`test_bad_channel_entries_do_not_stop_the_others`, `test_a_plugin_model_raising_anything_fails_only_its_channel`), `tests/test_cli.py` (`test_poll_dry_run_reports_each_source`) |
83
+ | A polled source posting as another source (resetting its ack or announce state) | `sources/json_poll._envelope` forces `source = name` and skips an item naming another; config refuses `fields.source`. `tests/test_sources.py` (`test_a_polled_item_cannot_post_as_another_source`), `tests/test_config.py` (`test_invalid_config_raises`) |
84
+ | Two polled items collapsed into one event (an id derived from the summary alone) | `tests/test_sources.py` (`test_items_sharing_a_summary_get_distinct_stable_ids`, `test_configured_id_paths_identify_items_across_severity_changes`, `test_derived_id_ignores_volatile_fields_but_keeps_payload_identity`) |
85
+ | A cleared polled condition staying open, or a failed/partial poll clearing anything, or a system close faking a person's ack | `resolved_at` (migration 6), set by `Inbox.resolve_missing`, never `acked_by`. `tests/test_scheduler.py` (`test_poll_job_resolves_events_missing_from_a_successful_poll`, `test_poll_job_resolves_nothing_on_an_incomplete_poll_or_when_off`, `test_json_poll_cleared_item_resolves_end_to_end`), `tests/test_store.py` (`test_resolved_column_migration_keeps_open_events_open`), `tests/test_sources.py` (`test_poll_result_is_incomplete_when_an_item_was_skipped`) |
86
+ | A source setting inbox bookkeeping (ack, announce state) on the events it emits | `tests/test_inbox.py` (`test_ingest_normalises`) |
87
+ | Speech synthesised more than once per delivery, or a voice channel synthesising its own | `tests/test_channels.py` (`test_speech_is_synthesised_once_for_every_voice_channel`: one synthesis, the same audio object on every voice channel, `deliver()` never called on them; `test_third_party_voice_channel_from_an_entry_point`) |
88
+ | A failing, hanging or raising channel (or speech engine) blocking the others | `tests/test_channels.py` (`test_fan_out_and_a_failing_channel_never_blocks_the_others`, `test_a_failing_speaker_or_synthesiser_fails_voice_only`, `test_channels_run_concurrently`) |
89
+ | A duplicate delivery after a restart (the same report sent twice to one channel) | partial unique index `deliveries_sent` (one `ok` row per message and channel, migration 5); `tests/test_channels.py` (`test_no_duplicate_delivery_after_restart`, `test_concurrent_deliveries_of_one_message_send_once`, `test_a_briefing_job_writes_its_report_to_the_text_channel_once`, `test_cli_deliver_latest`) |
90
+ | A report spoken late (stale speech) by a retry | `channels/redeliver.py` sends a report older than `delivery.speak_max_age` (default 600 s) to text channels only; `tests/test_redeliver.py` (`test_no_stale_speech`: never synthesised or played; `test_speak_max_age_zero_never_respeaks`, `test_skips_do_not_count_toward_max_attempts_and_are_never_spoken_late`) |
91
+ | A cloned voice pushed to a face without disclosure | `SpeechAudio.cloned` (set by `EchoSynthesiser` whenever it asked for a `voice_clone_id`; echo's contract has no clone flag); over `transport: websocket` the `mask` channel pushes cloned audio only when the operator attests consent with `cloned_voice_consented: true` (default false: a permanent skip, before contacting mask, because mask's label asserts consent scout can't verify), and then the hello sets `disclose: true` exactly when the audio is cloned, so mask shows its disclosure label; over `transport: http` (the default) it skips cloned audio permanently, before contacting mask, unless `allow_cloned_voice: true` (default false, warned on every push), because `/push` can't carry the label. `tests/test_echo.py` (`test_speech_from_a_clone_is_marked_cloned`, `test_mask_refuses_a_cloned_voice_unless_allowed`, `test_a_refused_clone_is_reported_not_recorded_and_never_retried`), `tests/test_voice_channels.py` (`test_mask_ws_discloses_a_cloned_voice_and_not_a_synthetic_one`, `test_mask_ws_cloned_voice_needs_the_consent_attestation`, `test_mask_http_still_refuses_a_clone_whatever_the_attestation`). Snapcast (audio-only house playback) is deliberately not gated |
92
+ | A permanent failure retried forever, or any failure retried without bound | permanent refusals (a 4xx other than 408/429, from a webhook or from echo) are recorded in `delivery_refusals` (migration 8) and skipped by `undelivered_reports`; `tests/test_redeliver.py` (`test_permanent_failures_are_not_retried`, `test_a_webhook_4xx_is_permanent_and_a_429_is_not`, `test_retries_a_failed_channel_until_it_succeeds_and_stops_after_max_attempts`, `test_too_old_and_never_tried_channels_are_left_alone`, `test_a_channel_that_only_skipped_is_not_retried`) |
93
+ | A redelivery sending a report twice to a channel | the sweep goes through the dispatcher's store idempotency (`deliveries_sent`); `tests/test_redeliver.py` (`test_a_retry_that_succeeds_writes_one_ok_row_and_is_idempotent`) |
94
+ | Echo being down stopping text, or its failure going unrecorded | `EchoSynthesiser` raises `SynthesisError`, recorded on every voice channel; `tests/test_echo.py` (`test_echo_down_still_delivers_text_and_records_the_failure`, `test_unready_or_refusing_echo_raises_a_typed_error`) |
95
+ | Scout drifting from argus-echo's HTTP or resident contract | `tests/test_echo.py` (`test_request_and_response_follow_the_contract`, `test_a_cold_model_gets_the_load_timeout`, `test_build_request_and_stream_format`); the contract is re-implemented in `channels/echo.py` (argus-echo is not on PyPI), so a change to `argus_echo.contract` must be mirrored there by hand |
96
+ | A channel path outside its root (`../`, absolute, `{kind}` injection, a symlink out) | `tests/test_channels.py` (`test_text_channel_paths_outside_root_are_refused`) |
97
+ | Voice outside the heartbeat policy (quiet or rest hours), or the voice gate holding back text | `tests/test_channels.py` (`test_the_voice_gate_suppresses_voice_but_not_text`, `test_heartbeat_gates`); the dispatcher calls `heartbeat.broadcast_gate` / `voice_gate`, never a copy |
98
+ | A report delivered below the severity of its worst item (filtered off a `min_severity` channel, or held back in quiet hours when its item was let through) | `tests/test_status_reports.py` (`test_critical_status_report_reaches_a_critical_only_channel`, `test_briefing_severity_counts_items_and_open_recommendations`, `test_quiet_exempt_status_report_is_spoken_in_quiet_hours`, `test_critical_status_report_is_spoken_in_quiet_hours`) |
99
+ | A text-only, unspeakable or below-`voice.min_severity` item spoken inside a status report | `tests/test_status_reports.py` (`test_text_only_and_unspeakable_items_are_not_spoken`, `test_speech_holds_only_the_voice_eligible_items`, `test_unspeakable_report_skips_synthesis_whatever_the_gates_say`, `test_on_change_only_keeps_repeats_text_only`) |
100
+ | A recurred, new or escalated condition not reported, or an unchanged one repeated without `reannounce` | `tests/test_status_reports.py` (`test_a_condition_that_clears_and_recurs_is_reported_again`, `test_a_new_item_is_news_and_the_old_one_rides_along`, `test_an_item_clearing_is_not_news`, `test_an_item_clearing_reannounces_only_when_due`, `test_an_escalation_is_news`, `test_a_fresh_id_repeating_an_announced_item_is_not_news`, `test_an_item_held_back_by_quiet_hours_is_reported_after_them`) |
101
+ | A missing or stalled Snapcast FIFO reader hanging scout | `tests/test_voice_channels.py` (`test_snapcast_fifo_without_a_reader_fails_in_time_not_a_hang`, `test_snapcast_reader_that_stops_reading_fails_in_time`) |
102
+ | Scout creating or writing to a regular file in place of the Snapcast FIFO | `tests/test_voice_channels.py` (`test_snapcast_refuses_a_path_that_is_not_a_fifo`) |
103
+ | Snapcast group stream/volume left changed after speaking | `tests/test_voice_channels.py` (`test_snapcast_sets_volume_and_stream_then_restores_them`, `test_snapcast_restores_even_when_playback_fails`) |
104
+ | Speech pushed to an argus-mask face no screen can hear | `tests/test_voice_channels.py` (`test_mask_screen_not_ready_is_skipped_and_nothing_is_pushed`, `test_mask_push_refused_for_a_vanished_screen_is_skipped_and_errors_fail`; the push also sends `require_screen=true`; `test_mask_ws_not_ready_is_skipped_before_connecting`: the source socket has no `require_screen`, so `/health` is checked just before connecting) |
105
+ | The mask source socket hanging scout, or taking unbounded input | `tests/test_voice_channels.py` (`test_mask_ws_timeouts_and_early_close_fail_promptly`: connect, `ready` and push timeouts, a close before `done`; `test_mask_ws_caps_what_mask_may_send`; `test_mask_ws_pcm_arrives_intact_in_capped_frames`) |
106
+ | A missing voice extra (numpy) breaking any other channel | `tests/test_voice_channels.py` (`test_a_missing_extra_fails_only_that_channel`) |
107
+ | A channel POSTing anywhere but its configured URL, following a redirect, or sending without its configured credentials | `tests/test_prometheus.py` (`test_no_module_contacts_hosts_directly`); `tests/test_channels.py` (`test_webhook_payload_and_signature`, `test_webhook_refuses_to_send_without_its_secrets_or_to_another_host`) |
108
+ | A broken channel plugin or bad `channels:` entry stopping the other channels | `tests/test_channels.py` (`test_bad_channel_entries_do_not_stop_the_others`, `test_check_config_reports_a_bad_channel`) |
109
+ | The quickstart's config failing `check config`, its policy files drifting from `examples/`, an unpinned image, or a compose file that doesn't parse | `tests/test_quickstart.py`; CI `Quickstart` workflow (`docker compose config`) |
110
+ | A deployment's hostnames, IPs or persona in this repo | CI `docs` job (private IPs/paths/emails in published docs); examples use placeholders |
111
+ | `docs/config.md` drifting from the config schema | `tests/test_configdoc.py` (`test_config_reference_matches_the_schema`); regenerate with `make docs` |
112
+ | A published doc the handbook's import would refuse or mis-render (opsec hit, no `#` title, raw HTML, a broken relative link or anchor) | `tests/test_docs_publishable.py` |
113
+
114
+ ## Layout
115
+
116
+ `src/argus_scout/` — the package. Key modules:
117
+
118
+ - `__init__.py` — version shim (`__version__` from `hatch-vcs`).
119
+ - `cli.py` — Typer app; entry point `argus-scout` (`[project.scripts]`). `init` writes a starter config; `check` validates config files (`check config` covers scout.yaml, every file it names and every source and channel entry); `deliver --config --latest [--kind] [--channel] [--force]` (re-sends the newest report; idempotent unless `--force`); `poll --config [--source] [--ingest]` (one poll, dry run by default); `analyze --config [--dry-run]` (one signal evaluation + engine cycle; `--dry-run` works on `SqliteStore.copy_of`); `brief --config --kind morning|evening|status [--dry-run] [--no-llm]` (writes one report and prints it; `--dry-run` stores nothing and doesn't persist the usage count); `tariff now`; `serve --config`.
120
+ - `config.py` — `ScoutConfig`, the one config file (`scout.yaml`): `files`, `store`, `sources` (built-in kinds `webhook` / `json_poll` validated here; any other kind loads as `PluginSource`, keys kept, and is validated by its plugin's `config_model` in `sources.build_sources`; plugin models subclass `SourceSettings`), `channels` (built-in `text` / `webhook`, plugin kinds as `PluginChannel` validated by `channels.build_channels`; every channel has `enabled`, `min_severity`, `kinds`, `timeout` from `ChannelSettings`), `schedule` (briefing kinds are `morning` / `evening` / `status`), `services` (`llm`: `backend` ollama|openai, `base_url`, `model`, `api_key_env`, `timeout`, `max_tokens`, `context_tokens`, `temperature`, `gpu` (`LLMGpuConfig`: `min_vram_mb`, `model_mb`, `priority`, `target`; present means a lease per call; `target` required for openai)), `budget` (`limits: {llm_calls: N}`, `block_manual`), `server`. `files` also names `persona` and `memory`. Pydantic v2, `extra="forbid"`, frozen. `load_config` resolves relative paths against the config's directory, loads `.env` beside it (never overriding the real env) and raises `ConfigError` on anything invalid. Secrets are env-var *names* (`token_env`, `auth_env`, `api_key_env`), read with `resolve_secret` as `SecretStr`.
121
+ - `severity.py` — `Severity` (info < notice < warning < critical), `coerce_severity`, `rank`.
122
+ - `events.py` — `StatusEvent`, the envelope every source sends; `fingerprint` (content identity) and `group_duplicates`.
123
+ - `heartbeat.py` — `HeartbeatPolicy` (defaults + YAML overrides, `origin` per key), `PolicyFile` (mtime reload), the `broadcast_gate` / `report_gate` / `voice_gate` chain and `explain()`, `reannounce_due` (per group, from `last_broadcast_at`). `voice.on_change_only` is applied by the status cycle; `voice.backoff_max_seconds` was never implemented and is ignored with a warning.
124
+ - `recommendations.py` — `Recommendation` (`to_dict` / `from_dict`; `key`, `expires_at`, `last_seen_at`, `retired_reason` default empty so older stored rows load), `Status`, `TRANSITIONS` (`proposed → retired` withdraws a stale proposal); `approve()` / `reject()` / `retire()` take an optional `now` and keep the audit trail.
125
+ - `prometheus.py` — `PrometheusClient(base_url, fetcher=)`: read-only `query` / `query_range` via `argus_cortex.net.afetch`, configured host the only one allowlisted, no redirects. Typed results (`Sample`, `Series`) and errors (`PrometheusUnavailable`, `PrometheusQueryError`, `PrometheusResponseError`, all `PrometheusError`): a failure is unknown, never an empty result.
126
+ - `signals.py` — declarative rules (`SignalRule`: `name`, `query`, `op`, `threshold`, `for`, `severity`, `escalate`, `labels_key`, `labels`, `rejection_ttl`, `expires_after`, `recommendation`). `parse_rules` / `load_signal_rules` skip bad rules with an error; `SignalRulesFile` (mtime reload). `render` / `template_fields`: allowlisted plain-name placeholders, precision-only specs on numbers, no `format_map`. `SignalState` (pending `for` clocks, persisted via the store). `async evaluate(rules, client, now, state=)` → `Evaluation` (a `list[SignalHit]` plus `evaluated` / `unknown` / `pending`); `dedup_key`; `make_hit` and `Evaluation.merge` are the seam for other evaluators (tariff rules). `kind:` picks a rule's schema (`rule_kinds()`; missing means `threshold`); `evaluate` runs only threshold rules but keeps every rule's pending state; `RuleBase` is the shared base (name, query, severity, rejection_ttl, expires_after, recommendation, template check).
127
+ - `tariff_rules.py` — the tariff-aware kinds. `TariffShiftRule` (`kind: tariff_shift`: `unit` W/kW/kWh, `min_shiftable`, `duration`, `periods`, `horizon` ≤ 1d, `min_saving`, `for`, `labels_key`) and `TariffPlanRule` (`kind: tariff_plan`: `unit`, `window`, `step`, `every` ≥ 1d, `min_saving`, `min_coverage`). `async evaluate_tariff(rules, client, tariff, now, tz=, state=, tariff_error=)` → `Evaluation`; no tariff / gaps / non-kWh / unknown period → `unknown` with `skipped: ...`; a plan rule's last run is kept in `SignalState` under `last_run`. Maths: `energy_kwh`, `shift_saving`, `cheaper_ahead`, `usage_points`, `plan_cost`, `comparable_plans`, `format_money` (minor → major units).
128
+ - `engine.py` — `RecommendationEngine(store, approvals, clock=, clear_grace=1h, default_ttl=7d)`. `run_cycle(hits)` → `CycleReport` (new / refreshed / auto_approved / retired / suppressed / unknown): dedup by key onto an open recommendation, rejection memory (suppressed unless severity escalates past the rejected one, or the rule's `rejection_ttl` has passed), standing approvals on `proposed` (guardrails win), a standing-approved recommendation escalating past a guardrail retired and re-proposed (`_escalated_past_standing`; a manual approval keeps its approval and gets an evidence note), proposed-only expiry (cleared past grace for an evaluated rule, or past `expires_at`; unknown never clears). `recent_rejections(limit)` → `Rejection`.
129
+ - `approvals.py` — `StandingApprovals` (file rules + runtime rules, optionally persisted via a `RuntimeRuleStore`), `guardrail_block`, `briefing_lines`.
130
+ - `budget.py` — `DailyBudget` (per-kind daily caps; counts in a `counter=` (`UsageCounter`: the store, atomic across processes), a single-process `state_path` JSON file, or memory; `on_change` hook for gauges), `budget_from_config(config, counter=, persist=, clock=)` (limits from `budget:`; the day rolls over at midnight in `schedule.timezone`; with `counter` the counts live in the store's `usage_counts` table and an old `usage.json` beside the store is imported once (merged by max, renamed `usage.json.migrated`)), `ManualOriginMiddleware`. The server and the CLI pass their store.
131
+ - `llm.py` — text generation on `argus_cortex.backends.RemoteBackend` (cortex owns the HTTP client, bearer header, timeout and retry policy: POSTs retried only when they never reached the server). `TextBackend.complete(prompt, max_tokens=)`; `OllamaBackend` (`/api/chat`, `stream: false`, `options.num_predict`), `OpenAICompatBackend` (`{base_url}/chat/completions`, `base_url` includes `/v1`; hosted providers via `api_key_env`); `build_backend(LLMConfig)`. `TextGenerator(backend, budget, call_guard=)`: `await generate(prompt, *, max_tokens, kind="llm_calls")` checks the cap (`LLMBudgetExceeded`, no lease waited for), enters `call_guard()` (the GPU lease: an async context manager, default no-op, held only for the HTTP round-trip), charges the budget, then makes the blocking call in a thread, sent to the grant's `base_url` if it has one (`TextBackend.at(url)`); no lease granted is `LLMGpuUnavailable` (`reason` `gpu_unavailable`, not charged), any other failure `LLMUnavailable` (`reason` tag). `clean_output`: output is untrusted text, never parsed. `estimate_tokens` = chars/4.
132
+ - `persona.py` — `Persona` (name, voice, style, do, dont, sign_off, `SpeakableStyle`); the field defaults are the neutral default persona (`examples/persona.yaml` mirrors them, tested). `system_prompt()` always starts with scout's `RULES` (advisory only, facts only, don't re-argue rejections). `PersonaFile(path)` (mtime reload; a bad or missing file → default, `error` set, logged).
133
+ - `memory.py` — `Memory(root, max_chars=)`: operator notes (`*.md`, one level, read-only, capped per file) and scout's own `SCOUT_FILE` (`scout-recent-rejections.md`, rewritten atomically, never through a symlink). `resolve(name)` fences every path under the root's real path (`MemoryPathError`). `render_rejection` quotes a rejection's reason.
134
+ - `gpu.py` — GPU leases (argus-iris broker via `argus_cortex.gpu`). `narrative_guard(llm, coordinator=)` → the call guard (or `None` without `services.llm.gpu`): one preemptible lease, kind `narrative`, priority `background` by default, target `ollama:<model>` or `gpu.target`. Coordinator from the host-wide `ARGUS_GPU_*` env (`coordinator_from_env`), deliberately no scout.yaml knob. `routed_url` (grant's host, configured path kept), `LEASE_ERRORS`, `TENANT`/`KIND`/`DEFAULTS` (match `gpu-tenant.yaml` at the repo root). Never leases around echo: speech is echo's GPU work.
135
+ - `narrative.py` — `Narrator(store, generator=, persona=, memory=, tariff=, tz=, clock=, max_tokens=, context_tokens=)`: `gather(kind, groups=)` → `Facts` (open groups, proposed + approved recommendations, `recent_rejections`, `TariffFact`, notes); `build_prompt` → (`Prompt`, `Selection`): fact lines get a priority tier (critical 1, warning 2, rejections 3, notice 4, info 5, notes 6; header and tariff 0), and `select_lines` takes them in tier order until the next doesn't fit in `(context_tokens - max_tokens) * 4 * 0.9` chars minus the system prompt (monotonic cut; "N more not shown" per section; notes also capped at `memory.max_chars`). `compose()` asks the model, else `render_template` (deterministic, same facts); `report(kind, groups=, use_llm=, dry_run=, meta=)` stores a `Report` with meta (`severity`, `quiet_exempt` and `title` from `delivery_meta`: the worst item, plus for a briefing proposed/approved recommendations, `info` when nothing is open; `path` llm|template, `fallback_reason` budget|gpu_unavailable|error|disabled|no_llm, model, token counts, persona, `fingerprints`, `facts`: ids used and omitted counts). `build_narrator(config, store, budget, tariff=, coordinator=)` (wires `gpu.narrative_guard`).
136
+ - `tariff.py` — `Tariff` / `Plan` / `TariffPeriod` / `TariffTier`; `current_period`, `next_period_change`, `coverage_gaps`, `tiered_cost` (units above a capped last tier pay its rate); `TariffFile` (mtime reload, `None` on a bad file). Rates are in the currency's minor unit.
137
+ - `scheduler.py` — asyncio `Scheduler(store, clock=, sleep=)`: `add(name, async_fn, trigger, retry_delay=)`, `tick(wait=)`, `run_now`, `run_forever`, `start()` / `stop()`. Triggers: `Every(seconds)` and `DailyAt(time, tz, grace=)` (per-local-date slots, so DST fires once; a missed slot runs late only within `grace`, never a backlog). Last successful run per job persists in the store's `job_runs`, so restarts neither repeat nor reset. A raising job is logged, counted and retried after `retry_delay`; a job never overlaps itself. Clock and sleep are injected: tests never sleep.
138
+ - `cycles.py` — the jobs: `StatusCycle(store, policy_file, inbox=)` (reloads the heartbeat policy every run, so a bad edit degrades to defaults; skips rest hours; decides each `Inbox.open_grouped()` group with `explain`; with a `narrator`, writes a `status` report of the groups `report_gate` passed, capped at `report.max_items`, when at least one is news (`is_news`: no event in the group has been announced in its current form, which the store resets on first sight, a fingerprint change and a recurrence, or `reannounce_due`); it then marks the included groups announced (`mark_announced`) and sets `meta.speakable` from the groups whose `Decision.voice` is true (only the news ones under `voice.on_change_only`), or `False`), `AnalysisCycle(store, rules=, client=, approvals=, tariff=, tz=)` (reloads the signals file, evaluates threshold and tariff rules and merges them, runs the engine; skips without Prometheus or rules, and on an unparseable file; an outage makes rules unknown and never raises), `BriefingJob(kind, store, narrator=, deliver=)` (writes, stores and delivers one report; template when the model can't), `PollJob(bound_source, inbox)` (one per polling source, ingests via `Inbox.ingest`; with the config's `resolve_missing` and a complete `PollResult`, resolves the source's events the poll no longer lists). `deliver(report)` is the no-op delivery seam (phase 5 injects the channels dispatcher via the jobs' and `register_jobs`' `deliver=`). `register_jobs(scheduler, config, store, policy_file, tariff=, budget=, narrator=, deliver=, dispatcher=)` (the runtime passes its `TariffFile`, shared by the analysis cycle and the narrator, its `DailyBudget`, and its `Dispatcher`, which adds the `redeliver` sweep) names them `status`, `analysis`, `redeliver`, `briefing:<kind>@HH:MM`, `poll:<source>`; the name keys the persisted bookkeeping.
139
+ - `store/` — persistence (stdlib `sqlite3`, no ORM). `base.py`: the `Store` Protocol plus `InboxEntry`, `Transition`, `Report`, `JobRun`. `sqlite.py`: `SqliteStore(path)` (`":memory:"` for tests) — status events keyed by `(source, event_id)` with first/last seen, ack, fingerprint index and announce state; recommendations with a `recommendation_transitions` audit table (`save_recommendation(rec, by=, reason=, expected_status=, expected_revision=)`: pass the status and revision you loaded, `None` status for a new row; a mismatch raises `StaleRecommendation`, a non-lifecycle status change `IllegalTransition`, both `StoreConflict`, nothing written; every load-then-save in the engine and the routes passes it, the engine logs and skips a conflict, a route answers 409); runtime standing-approval rules (`StandingApprovals(store=...)` loads and writes through; file rules never stored); reports; scheduler `job_runs` (migration 2); recommendation `key` column + index (migration 3; `recommendations_by_key`, `recent_rejections`); signal rules' pending state `signal_pending` (migration 4); delivery records `deliveries` (migration 5: `record_delivery`, `delivered_channels`, `list_deliveries`, `delivery_counts`); events' `resolved_at` (migration 6: `resolve_missing(source, keep)`, a system-side close that open queries and `open_event_counts` exclude and the next sighting clears; never touches `acked_by`); daily usage counts `usage_counts` (migration 7: `usage_counts(day)`, `consume_usage(day, kind, limit, allow_over=)` atomic check-and-increment, `merge_usage` by max; `DailyBudget`'s `UsageCounter`); recommendation revisions `recommendation_revisions` (migration 9, a side table so a replay is harmless: every save bumps it and sets `rec.revision`; a row without one reads as 0; `update_recommendation(rec_id, change, expected_revision=)` checks it and applies `change` to the stored row in one transaction, for the decision routes); `transaction()` groups store calls into one commit (nested calls join it); permanent delivery refusals `delivery_refusals` (migration 8, a side table so a replay is harmless: `record_delivery(..., permanent=)`, `DeliveryRecord.permanent`, `undelivered_reports(since, max_failures=)` → `PendingDelivery` for the redelivery sweep); `copy_of(path)` for dry runs; scrape-time counts for `/metrics` (`recommendation_counts`, `approval_counts`, `open_event_counts`); `prune()`. Migrations are ordered scripts in `MIGRATIONS`, tracked by `PRAGMA user_version` and applied on open: append, never edit a shipped one. One connection behind an `RLock` (shared by the app and scheduler threads), WAL, foreign keys on. Datetimes are UTC ISO text with fixed microseconds, so they compare as strings.
140
+ - `inbox.py` — `Inbox(store, clock=)`: `ingest()` / `ingest_many()` (one store transaction for a batch) → `IngestResult` (`Outcome`: new / duplicate / escalated / updated / refreshed / recurred), `ack()`, `resolve_missing(source, present)`, `open()`, `open_grouped()` (→ `EventGroup` by fingerprint, which includes the source). `parse_envelope` is the strict validator for envelopes arriving as data (`InvalidEvent` names the field); `normalise` clips, coerces and strips bookkeeping. Records only: never moves a recommendation or sends anything.
141
+ - `sources/` — status sources as plugins. `base.py`: `Source` / `PollingSource` (`async poll`) / `PushSource` (`parse`, `authorize`) protocols, `SourceError`, `SourceAuthError(status)`, `PollResult` (a list with `complete`). `registry.py`: kinds from the `argus_scout.sources` entry-point group (built-ins always present and can't be overridden); `build_sources(config)` → `Sources` (bound sources + per-entry errors). `webhook.py`: `parse_webhook`, `check_token` (argus-cortex `auth.check_bearer`, fails closed), no route. `json_poll.py`: `poll_once` via `argus_cortex.net.afetch`, `map_response` (dotted `items` / `fields`; ids from `id:` paths, else the item's `event_id`, else a hash of summary + payload + link, never severity or timestamps; colliding derived ids fall back to the raw item's hash with a warning; an item naming another source is skipped).
142
+ - `channels/` — delivery channels as plugins. `base.py`: `Delivery` (`from_report` / `from_event`; `key` is the idempotency key, `report:<id>` or `event:<source>/<id>:<hash>:<announce count>`; `speakable` is `meta.speakable` or the text through `plain_speech`), `DeliveryResult`, `SpeechAudio`, the `Channel` (`kind`, `config_model`, `async deliver`) / `VoiceChannel` (+ `async play(audio, message)`) / `Synthesiser` protocols, `NullSynthesiser`, `ChannelError(msg, permanent=)` and its `SynthesisError` (`DeliveryResult.permanent` too: a failure the sweep never retries). `registry.py`: kinds from the `argus_scout.channels` entry-point group (a class built with its validated config; built-ins can't be overridden); `build_channels(config)` → `Channels` (bound channels + per-entry errors). `dispatcher.py`: `Dispatcher(channels, synthesiser=, gates=, store=, budget=)`; `deliver(message, force=, only=)` → `DispatchReport` (filters, idempotency via the store, concurrent fan-out with per-channel timeouts, speech synthesised once for all voice channels when the message has a `speakable` and `gates.voice` allows); `HeartbeatGates(policy_file, tz=)` (rest hours, `broadcast_gate`, `voice_gate` for items, `sources.scout` routing for reports); `OpenGates` for tests. `text.py` (append, fenced with `argus_cortex.fs.safe_join` + `O_NOFOLLOW`, rotation), `webhook.py` (`build_payload` schema `argus-scout.delivery` v1, `sign` HMAC, bounded retry via `afetch`; documented in `docs/channels.md`). Voice kinds (built-ins whose numpy is imported only when a channel is built; the constructor raises `MissingExtra` naming the extra): `audio.py` (`decode` wav / `pcm_s16le` / `pcm_f32le` to `Pcm`, `remix`, `resample` linear, `encode` to a `SampleFormat` `rate:bits:channels`, 24-bit in 4 bytes as Snapcast does; `AudioFormatError` for anything else); `snapcast.py` (`SnapcastConfig`; FIFO fenced by `open_fifo`: must exist and be a FIFO, `O_NONBLOCK`, `ENXIO` retried to `open_timeout`; `write_fifo` select + deadline; `SnapcastRpc` JSON-RPC over raw TCP or HTTP to the `control` host only; `plan` = setup calls with their undo, restored in reverse in a `finally`); `mask.py` (`MaskConfig`; `readiness` from `GET /health`; `POST /push?require_screen=true` raw s16le with `X-Sample-Rate` / `X-Audio-Format` / `X-Channels`; not ready or a 409 returns `DeliveryResult(ok=True, status="skipped")`, which the dispatcher neither records nor counts as failed; `transport: websocket` uses mask's `WS /session/<face>/source` instead: JSON hello `{sample_rate, channels, format: s16le, seed, disclose}`, `ready`, binary PCM frames of at most `WS_FRAME_BYTES` paced at real time + 1 s, `{"type":"end"}`, `done`; a face "already has a source" is skipped; `websockets` imported lazily, connection pinned via `pin()` = one resolve + `argus_cortex.net.check_url`, `process_redirect` refuses every redirect, `proxy=None`, `compression=None`, `max_size` capped). `echo.py`: `EchoSynthesiser(EchoConfig)`, argus-echo's shared HTTP contract re-implemented (`POST /synthesise/stream`, PCM layout from `X-Sample-Rate`/`X-Audio-Format`/`X-Channels`, float32 converted to `pcm_s16le` or WAV) plus the resident contract (`GET /health` as cortex `ResidentHealth`: down or `error` fails fast, `unloaded`/`loading` gets `load_timeout`); bounded body, echo host only, never a GPU lease, failures raise `SynthesisError` (permanent for a 4xx other than 408/429). No `echo` voice channel: echo has no speaker. `redeliver.py`: `RedeliveryJob(store, dispatcher, DeliveryConfig)`, the `redeliver` job (`delivery: {retry_interval, retry_max_age, max_attempts, speak_max_age}`): reports only, failed channels only, never past `max_attempts` or a permanent refusal, text only once older than `speak_max_age`; a `skipped` result writes no row, so it never counts toward `max_attempts`. `build_dispatcher(config, store=, policy_file=, ...)` wires them for the server and the CLI.
143
+ - `server/app.py` — `create_app(config, *, store=, budget=, inbox=, sources=, clock=, sleep=, run_scheduler=)` (`[server]` extra). The lifespan builds a `Runtime` (store, policy file, inbox, tariff, usage caps counted in the store, scheduler, metrics registry) on `app.state.runtime`, starts the scheduler and stops it on shutdown; building the app opens nothing. `Runtime.sources` holds the bound sources; `Runtime.channels` / `Runtime.dispatcher` the channels, and `await Runtime.deliver(report)` sends a stored report through them (inbox items reach channels only inside status reports; `Delivery.from_event` and the `event` type are interface for a later single-item path). `deliver_reports(dispatcher)` is the `deliver=` callable passed to `register_jobs`, so briefings and status reports go out as they are stored. Routes: `/health`, `/metrics` (always open, to any `Host`), FastAPI's docs and schema (off under `read_auth`) and the API (`server/routes/`). `install_guards` + `include_routes` are the only API wiring here.
144
+ - `server/guards.py` — the security boundary. `install_guards(app, server)`: `HostGuard(trusted_hosts)` outermost (every request but `HOST_OPEN_PATHS` = `/health`, `/metrics`: a `Host` that isn't an IP, `localhost` or a `server.trusted_hosts` name is a 400, against DNS rebinding), then `WriteGuard(constant_refuse)` when `read_only` (the default), then `WriteGuard(cross_site_refuse(allowed_origins, trusted_hosts))`. `write_auth(server)` = `argus_cortex.auth.bearer(token_env)` (no `token_env` → always 503); `source_auth(server)` for the push route = the source plugin's `authorize` (webhook: its own `token_env`, else the server token), credentials first: a name that isn't a push source is 404/405 only to the server token, else the same 401/503 a push source gives; `read_auth(server)` when `server.read_auth`. Auth dependencies carry `AUTH_MARK`; `iter_routes(app)` flattens FastAPI 0.16x's lazily included routers and `unguarded_routes(app)` reports any write route without guards, and a missing or non-outermost `HostGuard`. `read_bounded` / `read_json` (caps `EVENTS_MAX_BYTES` 256 KiB, `ACTION_MAX_BYTES` 8 KiB): write routes take `Request` and read the body after auth.
145
+ - `server/routes/` — `events.py` (`POST /api/events/{source}`, all-or-nothing batch, per-event inbox outcome; `POST /api/events/{source}/{event_id}/ack`; `GET /api/events` grouped), `recommendations.py` (manual `approve` / `reject` with `{by, reason, revision}`, proposed only and at the viewed revision, 409 otherwise, applied to the stored row through `store.update_recommendation` with the app clock; `GET /api/recommendations?status=&limit=`, `GET /api/recommendations/{id}` with history; no route past `approved`), `reads.py` (`GET /api/reports/latest?kind=`, `GET /api/policy/explain`, `GET /wall` as text/plain with control characters stripped), `models.py` (request bodies, unknown keys refused).
146
+ - `server/deps.py` — `get_runtime(conn)` (503 when the app isn't running).
147
+ - `server/metrics.py` — `ScoutCollector`, a custom collector on its own `CollectorRegistry` (never the global one) that reads the store, usage caps, tariff file and scheduler at scrape time, so values survive restarts. Families: `scout_usage_used` / `scout_usage_limit{kind}`, `scout_tariff_loaded`, `scout_tariff_period{plan,period}`, `scout_tariff_rate{plan,period,currency,unit}`, `scout_tariff_next_change_seconds{next_period}`, `scout_recommendations{status}`, `scout_approvals_total{source}`, `scout_inbox_open_events{severity}`, `scout_job_runs_total` / `scout_job_errors_total` / `scout_job_last_success_timestamp_seconds` / `scout_job_running{job}`, `scout_deliveries_total{channel,result}`.
148
+ - `examples/` (repo root) — commented config for each policy file scout reads; tests load them, so they must stay valid.
149
+ - `configdoc.py` — generates `docs/config.md` from the config models (types, defaults, constraints, and each field's `description=` or the docstring under it). Each section's example is validated when it renders. Improve a key's docs in `config.py`, never in `docs/config.md`.
150
+ - `docs/` — the guides (`sources`, `signals`, `narrative`, `channels`, `api`, `operations`) plus the generated `cli.md` and `config.md`. argus-handbook imports README.md and `docs/*.md` from `dev`: keep a `#` title first, placeholders in backticks (raw HTML is dropped there), relative links, and no private addresses or paths.
151
+ - `src/argus_scout/examples/` — packaged templates `argus-scout init` writes (`scout.yaml`, `env.example` → `.env.example`); tests validate them.
152
+ - `deploy/quickstart/` — compose (scout, Prometheus, node exporter, Ollama), its `prometheus.yml` and `config/`. The policy files in `config/` are copies of `examples/`: change both (`tests/test_quickstart.py` fails on drift). `.github/workflows/quickstart.yml` is this repo's own (not copier-managed).
153
+
154
+ ## Commands
155
+
156
+ ```bash
157
+ make install # uv venv + editable install with the "dev" extras
158
+ make test # pytest --tb=short -q
159
+ make lint # ruff check + format --check (pinned ruff 0.15.16)
160
+ make format # ruff format + --fix
161
+ make docs # regenerate docs/cli.md (Typer) and docs/config.md (python -m argus_scout.configdoc)
162
+ ```
163
+
164
+ Run one test: `uv run --no-sync pytest tests/test_x.py::test_name -q`.
165
+
166
+ ## Conventions & gotchas
167
+
168
+ - **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_scout/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
169
+ - **`src/` layout, `py.typed`, Pydantic v2, `structlog`.** Ruff line-length 120; keep it clean (`make lint`) before committing.
170
+ - **Any endpoint that does something is a boundary.** There's no auth by default — treat reaching the port as host access. Gate state-changing routes behind the shared read-only / origin guards, and fence any caller-supplied path under a configured root.
171
+ - Wire schemas (if any) are checked in and verified in CI — regenerate and commit when the types change, don't let the committed copy drift.
172
+
173
+ ## Branches
174
+
175
+ `dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never push work to `main` or open a PR against it, except the release PR from `dev`: `main` must never be ahead of `dev`, with one exception. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected, the release is a reviewed PR from `dev` into `main`, and merging it leaves a merge commit on `main` alone. That merge commit is the one exception to the rule: it leaves `main` one commit ahead of `dev` with an identical tree. Leave it there and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty). Once `main` carries such a commit it can't be fast-forwarded, so later releases are PRs too.
176
+
177
+ ## CI / release
178
+
179
+ CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow. `docs.yml` runs its `docs-check` on every push: published docs (`README.md`, `docs/**/*.md`) must hold no private IPs, home/server paths or personal emails (use placeholders like `<GPU_HOST>`), and `docs/cli.md` must match the CLI — run `make docs` after changing a command or a config model (`docs/config.md` is checked by a test, not by CI's docs job). Release publishes to PyPI (OIDC trusted publishing) + GHCR on `v*` tags. Run `copier update` to pull template (CI/release/tooling) changes.
@@ -0,0 +1,30 @@
1
+ # syntax=docker/dockerfile:1
2
+ FROM python:3.12-slim
3
+
4
+ COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
5
+
6
+ WORKDIR /app
7
+
8
+ # hatch-vcs derives the version from git history, so the build context must
9
+ # include .git (keep it out of .dockerignore for this image) and the image must
10
+ # have the git binary -- python:*-slim does not ship one, and without it the
11
+ # install below fails with "unable to detect version".
12
+ RUN apt-get update \
13
+ && apt-get install -y --no-install-recommends git \
14
+ && rm -rf /var/lib/apt/lists/*
15
+
16
+ COPY . .
17
+
18
+ RUN uv pip install --system --no-cache ".[server]"
19
+
20
+ # Mount a config directory at /config (scout.yaml, its .env, and the files it names). Relative paths in
21
+ # scout.yaml resolve against it, so the default store (scout.db) lands there too and survives restarts.
22
+ # Point SCOUT_CONFIG elsewhere to use another file. `serve` refuses to start without a valid config.
23
+ ENV SCOUT_CONFIG=/config/scout.yaml
24
+ VOLUME ["/config"]
25
+
26
+ EXPOSE 8400
27
+ # Bound off loopback inside the container: set server.read_auth: true unless only trusted hosts reach the port
28
+ # (serve warns when it is off).
29
+ CMD ["argus-scout", "serve", "--host", "0.0.0.0", "--port", "8400"]
30
+