Rescue the work-PC wizard and kiosk-link edits

Two tracked files had been edited directly in the work-PC relay clone, which
only fetches bundles and pushes them to GitHub. Nothing there reaches gitea, and
the next bundle pull would have overwritten both silently. Brought across here,
with three changes to what was written.

Kiosk links now need the route AND the plugin. The edit swapped hasRoute for
isPluginEnabled, which trades one wrong answer for another: a full build stages
every route, so a site that turns printedparts or usb OFF still saw a link to a
kiosk its backend refuses - the symptom being fixed - but isPluginEnabled fails
OPEN when it cannot reach the plugin list, and a copied registry can report a
plugin that was never staged into this build. That is what the comment above
those lines was already warning about. Both tests together answer both states.

The wizard shows the filename it is uploading. The browser puts it in chrome the
full-screen wizard hides, so an operator picking a file got no confirmation it
was the one being sent.

Image previews get a cache-buster. The stored path does not change between
uploads, so the preview showed the PREVIOUS logo or blueprint and the upload
read as having silently failed. Display only - saveStep persists form values,
never these, so no cache-busted URL is ever written to a setting.

The wizard also loads the current site logo on mount, so re-running it does not
present an empty slot as though branding had never been set. The shipped-asset
fallback stays a root-absolute path: the template applies withBase, and prefixing
it here as well produced /shopdb/shopdb/ge-aerospace-logo.svg on a subpath mount.

Frontend 391 passing.

Scope: product

.dockerignore

@@ -0,0 +1,23 @@
+# Keep the build context lean and prevent host artifacts from clobbering
+# in-image installs. node_modules is platform-specific: copying the host's
+# (Windows) tree over the container's `npm ci` breaks rollup's native binary.
+**/node_modules
+frontend/dist
+frontend/src/.plugins-staged
+frontend/src/router/routes.gen.js
+
+# Python caches and virtualenvs
+**/__pycache__
+**/*.pyc
+.venv
+venv
+
+# Local dev and VCS noise
+.git
+.gitignore
+*.log
+.env.local
+
+# Installer build artifacts (not part of the app image)
+installer-arch-dev/build
+installer-arch-dev/dist

.env.example

@@ -4,7 +4,7 @@
 # refuses to boot when SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, or
 # CORS_ORIGINS are missing or use the dev defaults.
 #
-# See docs/DEPLOY.md for the full per-site deployment runbook.
+# See the DEPLOY wiki page for the full per-site deployment runbook.
 
 # ---- Flask ----
 FLASK_APP=wsgi.py
@@ -25,7 +25,7 @@ JWT_SECRET_KEY=change-this-to-another-secure-random-string
 # Format: mysql+pymysql://<user>:<password>@<host>:<port>/<database>?charset=utf8mb4
 # In docker-compose, host is `db` (the service name).
 # The ?charset=utf8mb4 keeps the connection on utf8mb4; create the database as
-# utf8mb4 too (see docs/DEPLOY.md). Both must be utf8mb4 to match the schema.
+# utf8mb4 too (see the DEPLOY wiki page). Both must be utf8mb4 to match the schema.
 DATABASE_URL=mysql+pymysql://shopdb:CHANGE_ME@db:3306/shopdb_flask?charset=utf8mb4
 
 # ---- CORS (required, no wildcards in production) ----
@@ -36,6 +36,18 @@ DATABASE_URL=mysql+pymysql://shopdb:CHANGE_ME@db:3306/shopdb_flask?charset=utf8m
 # Wildcard '*' is rejected by ProductionConfig.validate().
 CORS_ORIGINS=http://localhost:5173
 
+# ---- Reverse proxy (optional, default 0 = no proxy) ----
+# Set to the number of proxies actually in front of this instance - 1 when IIS
+# or nginx serves it under a subpath such as /shopdb. Without it the app sees
+# the proxy's connection instead of the browser's (scheme http, the proxy's
+# host and IP), so any absolute URL it builds is wrong at the browser. That is
+# what made a redirect on the endpoints list unfollowable behind IIS.
+#
+# Leave it at 0 when nothing fronts the app. It makes X-Forwarded-* trusted,
+# and a client can send those headers itself - the login rate limit and the
+# account lockout are keyed on the client address.
+TRUSTED_PROXY_COUNT=0
+
 # ---- JWT lifecycle (optional, defaults shown) ----
 JWT_ACCESS_TOKEN_EXPIRES=3600
 JWT_REFRESH_TOKEN_EXPIRES=2592000
@@ -49,6 +61,10 @@ MYSQL_ROOT_PASSWORD=CHANGE_ME_ROOT_PASSWORD
 MYSQL_PASSWORD=CHANGE_ME_APP_PASSWORD
 MYSQL_PORT=3306
 API_PORT=5001
+# Air-gapped deploy only (docker-compose.airgap.yml): the loaded image tag,
+# which MUST match what build-offline-bundle.ps1 -Version produced. Ignored by
+# the connected build template (docker-compose.yml builds from source).
+IMAGE_TAG=0.7.0
 
 # ---- Zabbix integration (optional, for printer supply monitoring) ----
 ZABBIX_URL=
@@ -60,6 +76,26 @@ ZABBIX_TOKEN=
 # COLLECTOR_API_KEY_<PLUGINNAME> first, then COLLECTOR_API_KEY as fallback.
 # COLLECTOR_API_KEY=
 # COLLECTOR_API_KEY_COMPUTERS=
+# COLLECTOR_API_KEY_ENDPOINTS=
+
+# ---- Trusted plugin publisher keys (ADR-013, optional) ----
+# Public-key PEM paths (OS path separator: ':' on Linux, ';' on Windows) used
+# to verify signed plugin artifacts. Delivered with this config, NEVER from the
+# plugin shelf. Empty on a site that does not adopt marketplace plugins.
+# PLUGIN_TRUSTED_KEYS=/etc/shopdb/keys/curator.pub
+#
+# Enforce signatures: a plugin only loads/migrates if its tree matches a
+# trusted signature. Default off. Turn on only after stamping plugins
+# (flask plugin stamp-bundled) and pinning keys above.
+# PLUGIN_REQUIRE_SIGNED=false
+#
+# Dev-only: directories whose UNSIGNED plugins are trusted, honored ONLY under
+# DEBUG/TESTING (external-repo/symlink dev). Production ignores this.
+# PLUGIN_DEV_TRUST_DIRS=/home/dev/my-plugin-repo
+#
+# Read-only folder the app pulls plugin artifacts from (a SharePoint-synced or
+# copied shelf). The app reads this folder; it never speaks any network.
+# PLUGIN_SHELF_DIR=/srv/shopdb/plugin-shelf
 
 # ---- Employee directory database (optional, read-only) ----
 # Separate HR/employee lookup DB consumed by the notifications plugin and the
@@ -79,3 +115,10 @@ ZABBIX_TOKEN=
 # CMMC_USB_DB_USER=
 # CMMC_USB_DB_PASSWORD=
 # CMMC_USB_DB_NAME=cmmc_usb
+
+# ---- Subpath deployment (optional) ----
+# Serve the app under a URL prefix instead of the server root, e.g. as an IIS
+# Application at /ops under an existing site. The frontend must be rebuilt with
+# the matching base: VITE_BASE_PATH=/ops/ npm run build. Leave unset when the
+# app owns its own site/port (the default). See the INSTALL-WINDOWS-IIS wiki page.
+# MOUNT_PATH=/ops

.gitattributes

@@ -1 +1,12 @@
 .env filter=git-crypt diff=git-crypt
+
+# Shell scripts must stay LF so Git Bash on Windows can run them
+*.sh text eol=lf
+scripts/check-naming-and-style.sh text eol=lf
+.githooks/pre-commit text eol=lf
+
+# Batch files must be CRLF. cmd.exe parses a lone LF inconsistently around
+# labels and goto, so an LF-only .cmd can run its happy path and then jump
+# nowhere on the error path - which is the path that matters in a promote
+# script.
+*.cmd text eol=crlf

.gitea/workflows/ci.yml

@@ -1,20 +1,33 @@
 # CI for shopdb-flask.
 #
-# NOTE: this is a best-effort configuration. Gitea Actions availability on
-# the host is UNVERIFIED - no runner has been confirmed. Until a runner is
-# registered and this workflow is observed passing, treat it as config-only.
+# The Gitea runner executes jobs on the host (act host executor), so
+# actions/setup-python cannot provision interpreters (no prebuilt binaries
+# for the host distro). The backend job uses the system python3 in a venv
+# instead. setup-node works because node is resolved differently.
 #
-# Three jobs run on push and pull_request:
-#   backend  - pytest (tests use in-memory SQLite via TestingConfig, so no
-#              database service is needed).
-#   naming   - the CONTRIBUTING.md naming/style gate.
-#   frontend - Vue build.
+# Jobs run on push and pull_request:
+#   backend        - pytest (tests use in-memory SQLite via TestingConfig, so no
+#                    database service is needed).
+#   naming         - the CONTRIBUTING.md naming/style gate.
+#   frontend       - Vue build.
+#   migrations-mysql - proves the REAL multi-site deploy path: a fresh
+#                    `flask db upgrade` + per-plugin install on utf8mb4 MySQL
+#                    from empty, idempotent on a second run. The pytest suite
+#                    only exercises SQLite create_all(), so without this a
+#                    regression in the Alembic chain on MySQL would ship
+#                    undetected. Needs a runner that supports service
+#                    containers; if yours does not, run these steps against a
+#                    host MySQL instead.
 
 name: CI
 
 on:
   push:
   pull_request:
+  # Lets a run be retried from the Actions page without inventing a commit.
+  # Gitea's API exposes no rerun endpoint, so without this the only way to
+  # re-test a runner-side change is to push something.
+  workflow_dispatch:
 
 jobs:
   backend:
@@ -23,15 +36,24 @@ jobs:
       - name: Check out
         uses: actions/checkout@v4
       - name: Set up Python
+        # Pin the interpreter instead of inheriting the runner image's default.
+        # requirements.txt is hash-pinned and was compiled on 3.14; on an older
+        # Python, alembic additionally requires tomli, which has no hash in the
+        # lock file and pip then refuses the whole install.
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: '3.14'
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          python3 --version
+          python3 -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -r requirements.txt
+          # pytest lives in requirements-dev.txt, not requirements.txt. Without
+          # this the test step dies with "No module named pytest".
+          .venv/bin/pip install -r requirements-dev.txt
       - name: Run backend tests
-        run: python -m pytest
+        run: .venv/bin/python -m pytest
 
   naming:
     runs-on: ubuntu-latest
@@ -55,3 +77,87 @@ jobs:
           npm ci
           npm run build
         working-directory: frontend
+
+  migrations-mysql:
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: shopdb_ci
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h localhost -uroot -proot"
+          --health-interval=5s --health-timeout=5s --health-retries=20
+    env:
+      # 'mysql' is the service name, not 127.0.0.1. Under a container-mode
+      # runner the job is itself a container on the services network, so the
+      # service is reached by name. Published ports land on the runner host,
+      # not on the job's localhost the way they do on GitHub-hosted runners.
+      DATABASE_URL: mysql+pymysql://root:root@mysql:3306/shopdb_ci?charset=utf8mb4
+      SECRET_KEY: ci-secret
+      JWT_SECRET_KEY: ci-jwt-secret
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+      - name: Set up Python
+        # Pin the interpreter instead of inheriting the runner image's default.
+        # requirements.txt is hash-pinned and was compiled on 3.14; on an older
+        # Python, alembic additionally requires tomli, which has no hash in the
+        # lock file and pip then refuses the whole install.
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Install dependencies
+        run: |
+          python3 -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -r requirements.txt
+      - name: Drop the git-crypt .env
+        # .env is committed git-crypt encrypted. CI has no key, so the checked
+        # out file is the raw encrypted blob and python-dotenv dies reading it
+        # as UTF-8. This job supplies DATABASE_URL, SECRET_KEY and
+        # JWT_SECRET_KEY through env: already, so the file is not needed.
+        run: rm -f .env
+
+      - name: Force utf8mb4 on the CI database
+        # Uses pymysql, already a runtime dependency, rather than the mysql CLI,
+        # which is not present in every runner image.
+        run: |
+          .venv/bin/python - <<'PY'
+          import pymysql
+          c = pymysql.connect(host="mysql", port=3306, user="root", password="root")
+          with c.cursor() as cur:
+              cur.execute("ALTER DATABASE shopdb_ci CHARACTER SET utf8mb4 "
+                          "COLLATE utf8mb4_unicode_ci")
+          c.close()
+          PY
+      - name: Fresh core upgrade from empty
+        run: .venv/bin/flask db upgrade
+      - name: Install every bundled plugin (runs its chain)
+        run: |
+          for p in computers employees geenforce knowledgebase machines \
+                   measuringtools network notifications printers slides usb warranty; do
+            .venv/bin/flask plugin install "$p"
+          done
+      - name: Assert schema built + utf8mb4, and a second upgrade is a no-op
+        run: |
+          .venv/bin/python - <<'PY'
+          from shopdb import create_app
+          from shopdb.extensions import db
+          from sqlalchemy import text
+          app = create_app()
+          with app.app_context():
+              insp = db.inspect(db.engine)
+              tables = insp.get_table_names()
+              assert len(tables) >= 70, f'only {len(tables)} tables built'
+              row = db.session.execute(text(
+                  "SELECT default_character_set_name FROM information_schema.schemata "
+                  "WHERE schema_name = 'shopdb_ci'")).first()
+              assert row[0] == 'utf8mb4', f'charset is {row[0]}, not utf8mb4'
+              print(f'OK: {len(tables)} tables, charset {row[0]}')
+          PY
+      - name: Second core upgrade must be a clean no-op
+        run: .venv/bin/flask db upgrade

.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Committed pre-commit hook. Activate per clone with:
+#   git config core.hooksPath .githooks
+# Runs the naming/style gate; blocks the commit on failure.
+exec bash "$(git rev-parse --show-toplevel)/scripts/check-naming-and-style.sh"

.github/agent-workflow.md

@@ -0,0 +1,86 @@
+# Agent workflow rules
+
+Companion to `copilot-instructions.md` (which owns naming/style/architecture).
+These cut wasted turns. All are lessons from real sessions.
+
+## Environment - know these, do not rediscover
+
+- Shell is **PowerShell**: use `;` not `&&`, `2>$null` not `2>/dev/null`.
+- API container `shopdb-flask-wilm-api-1` (Flask, port `5001`).
+- DB container `shopdb-flask-wilm-db-1` (MySQL 8, root pw `root_password_123`).
+- SPA is **baked into the image** (not bind-mounted). Plugin code is
+  **bind-mounted read-only**.
+- `docs/` is stripped to a public wiki mirror - keep working docs out of it.
+- `requirements.txt` is hash-checked - never hand-edit.
+
+## Verify, don't react
+
+- The terminal "Command failed" banner fires on any non-zero exit or stderr
+  output and is **usually a false negative** (`curl --fail` on a 400,
+  pytest/npm/git writing to stderr). Judge success from real output.
+- Read container health via
+  `docker inspect --format '{{.State.Health.Status}}'` plus a probe **without**
+  `--fail` - never eyeball the exit code.
+
+## Container runs the image, not your edits
+
+Before running anything in the container that must reflect a change:
+
+1. Frontend: `npm run build`, then
+   `docker cp frontend/dist/. shopdb-flask-wilm-api-1:/app/frontend/dist`.
+2. Backend/scripts/templates: `docker cp` the files (or rebuild) first.
+
+If a result contradicts a change you just made, suspect stale container code
+before re-deriving the fix.
+
+## Testing
+
+- Confirm the working directory once, up front.
+- Run the smallest test that proves the point; find the minimal polluter for
+  isolation bugs. Run the full suite only at the end.
+- Clear stale local state before plugin/migration tests:
+  `if (Test-Path instance/plugins.json) { Remove-Item instance/plugins.json -Force }`.
+- Naming-gate hits inside local venvs (`.ci-venv/`, `env/`) are not repo code -
+  do not "fix" vendored libraries.
+- Final gates, exactly as CI: `python -m pytest tests/ -q`;
+  `cd frontend; npx vitest run; npm run build; cd ..`;
+  `bash scripts/check-naming-and-style.sh`.
+
+## Migrations and imports
+
+- Every migration: idempotent guard + real downgrade; must run clean on strict
+  MySQL 8. If you rename indexes in `upgrade()`, update `downgrade()` to match.
+- Avoid duplicate indexes: `index=True` plus an explicit `db.Index` on the same
+  column creates two.
+- Importers/seeders match by natural key and must be idempotent - prove it by
+  running twice (expect `updated`, not `created`). Watch all-or-nothing writes.
+
+## Don't offer rollbacks you don't need
+
+State current state plainly; surface a rollback path only for a real regression.
+
+## Wilmington (wilm) local-run known failures - do not re-investigate
+
+Running the full `python -m pytest tests/ -q` on a Windows dev box (not CI)
+produces a stable set of environmental failures that are NOT code regressions.
+Treat these as expected locally; judge your change against CI/Linux instead:
+
+- `test_core/test_security_headers.py::test_a_served_upload_is_sandboxed` -
+  `PermissionError [WinError 32]` (served upload file still locked by another
+  process). Windows file-lock timing, not a headers bug.
+- `test_plugin_contract.py::test_import_scan_covers_symlinked_plugins` -
+  `OSError [WinError 1314]` (symlink privilege not held). Needs admin/Developer
+  Mode to create symlinks; irrelevant to plugin logic.
+- `test_plugin_importguard.py::test_verified_source_signed_ok_tampered_raises` -
+  CRLF vs LF (`b'# plugin\r\n' == b'# plugin\n'`). Git autocrlf checkout, not a
+  signing bug.
+- `test_docs_publishable.py` and `test_docs_versions.py` - the local `docs/`
+  tree is not the stripped public wiki mirror, so doc-count / PROJECT-MAP
+  assertions fail. Expected off-CI.
+- `test_core/test_public_read_surface.py::test_every_get_route_is_gated_or_named_public`
+  - pre-existing ungated-GET inventory drift; only act on it if YOUR change
+  added a new GET route.
+
+If a run shows ONLY these, the suite is green for our purposes. Anything outside
+this list is real - investigate it.
+

.github/copilot-instructions.md

@@ -0,0 +1,103 @@
+# Copilot instructions for shopdb-flask
+
+Follow these when suggesting code. They are enforced by a naming/style hook and
+by CI (`.github/workflows/ci.yml`) - suggestions that break them fail the build.
+`CONTRIBUTING.md` is the full authority; this is the short version.
+
+## General Guidelines
+- Finish the in-flight task before starting new workstreams.
+- When asked to "take notes" on a future idea, capture it in the notes file only - do not implement it, and do not expand on it at length in replies.
+- Use a temp file for multi-line git commit messages instead of heredoc syntax: `git commit -F <file>`.
+- Avoid using `powershell.exe -File` for launching scripts, as it fails if the script file is missing or quarantined.
+
+## Installer Logic
+- The endpoint agent installer shipped to endpoints is generated by `_install_script()` in `plugins/endpoints/api/siteagent.py`, NOT `agent/installer/install-shopdbagent.ps1`. Any installer logic change must be made in `siteagent.py`, followed by rolling the containers.
+- The user's workflow: the agent hands over only the built EXEs (`shopdbagent.exe`, `shopdb-endpoint-tray.exe`); the user uploads them via the "Upload New/Legacy Agents" field in the Build Site Agent UI and builds the package with the newest version selected at the top.
+
+## Naming (LOCKED - the hook rejects violations)
+
+- **DB tables**: lowercase, concatenated, plural. No underscores, no dashes.
+  `machines`, `networkdevices`, `businessunits` - NOT `machine_types`, `BusinessUnits`.
+- **DB columns**: lowercase, concatenated, singular. No underscores.
+  `machineid`, `lastzabbixsync`, `isactive` - NOT `machine_id`, `last_zabbix_sync`.
+- **Foreign keys**: referenced table (singular) + `id`: `locationid`, `vendorid`.
+- **Booleans**: `is`/`has` prefix: `isactive`, `isshopfloor`.
+- **Index names**: `idx_<table>_<column>` (underscores allowed here only).
+
+### Python
+
+- A variable, attribute, function, or dict key that holds a DB value MUST match
+  the column name exactly - do NOT convert to snake_case.
+  Column `machineid` -> `Machine.machineid`, `{"machineid": 1}`, local `machineid`.
+- Pure code that does NOT mirror a DB field uses normal snake_case (PEP 8):
+  `loop_count`, `current_user`, `validate_input()`.
+- Classes: PascalCase, spelled out (`NetworkDevice`, `AssetType`).
+
+### JavaScript / Vue
+
+- A JS variable holding an API field value matches the API key exactly - do NOT
+  camelCase it. API `{"machineid": 1}` -> `response.machineid`, never `machineId`.
+- Components: PascalCase (`AssetDetail.vue`). CSS classes: lowercase-with-dashes.
+
+### API
+
+- Endpoints: lowercase plural nouns, no underscores/dashes: `/api/networkdevices`.
+- Query params + response keys match column names: `?locationid=5`,
+  `{"machineid": 1, "lastzabbixsync": "..."}`.
+
+### Allowed acronyms only
+
+Universal: id url api http https json jwt sql os ip dns csv pdf cors ttl uuid
+html css orm. Domain: cmm cnc pc usb vnc winrm ssh ssl tls tcp udp smtp ldap
+vlan sso dnc focas clm mtconnect. Anything else: spell it out.
+
+### Banned shorthand
+
+Never use `cfg ctx mgr req res env util helper` or `db` as a standalone variable
+name. Spell out: `config context manager request response environment utilities`.
+`_bp` is fine only as a suffix with a meaningful prefix (`printers_bp`).
+
+## Style (ASCII only)
+
+- NO emojis anywhere - code, comments, strings, UI.
+- NO em-dashes, en-dashes, Unicode arrows, or smart quotes. Plain ASCII only.
+- Comments default to NONE. Add one only when the WHY is non-obvious; keep inline
+  `#`/`//` comments terse. Docstrings stay normal English.
+- Dark theme is the default; keep UI functional and professional.
+
+## Architecture (do not violate)
+
+- **Plugins are the product.** Plugin code lives in `plugins/<name>/{models,api,services,schemas}/`
+  with a `manifest.json` (single source of truth: name, version, dependencies,
+  api_prefix) and a `BasePlugin` subclass in `plugin.py`.
+- **Plugins never import core internals.** Use the contract surface `shopdb.api`
+  (e.g. `from shopdb.api import db, Asset, success_response`). Adding to that
+  surface is a contract-version bump + a `docs/PLUGIN-HOOKS` update in the same PR.
+- **Migrations, never `db.create_all()`.** The core Alembic chain is in
+  `migrations/versions/`; each plugin owns its own chain under
+  `plugins/<name>/migrations/`. New schema = a new migration with an idempotent
+  guard and a real downgrade. Migrations must run clean on strict MySQL 8.
+  Any model column/table change ships WITH its migration in the SAME change, and
+  bringing up a new image MUST run `flask db upgrade` then
+  `flask plugin upgrade-all` before serving traffic. A model that references a
+  column its migration has not applied yet 500s every query on that table
+  (`1054 Unknown column`), so code and schema must never be deployed out of step.
+- **Asset model is the platform contract.** Physical things are an `Asset` plus a
+  plugin subtype row linked by `assetid` (FK, `ON DELETE CASCADE`). Consumables
+  with quantities are standalone tables, not assets.
+- **Ledger pattern**: a cached `quantityonhand` moves in the SAME commit as the
+  signed transaction row it reflects.
+- **Configuration for endpoint agent**: The endpoint agent's live collector key and base URL are provisioned in the Windows registry `HKLM\SOFTWARE\GE\ShopDB` (values `CollectorKey`, `BaseUrl`), not committed in `appsettings.json`; `appsettings.json` holds only non-secret runtime settings.
+
+## Before you finish a change
+
+Run the three gates (CI runs the same):
+
+```
+python -m pytest tests/ -q
+cd frontend && npx vitest run && npm run build && cd ..
+bash scripts/check-naming-and-style.sh
+```
+
+Commits: short present-tense subject, body says WHY. No AI/tool attribution in
+commit messages, code comments, or docs.

.github/workflows/ci.yml

@@ -0,0 +1,137 @@
+# CI for shopdb-flask on GitHub Actions.
+#
+# Mirrors the internal CI pipeline. Jobs on push + pull_request:
+#   backend          - pytest (SQLite via TestingConfig, no DB service needed)
+#   naming           - the CONTRIBUTING.md naming/style gate
+#   gates            - proves those checks actually RAN rather than skipping
+#   frontend         - vitest + Vue build
+#   lean-build       - ADR-013: a per-site build carries only its plugins
+#   migrations-mysql - the REAL multi-site deploy path: fresh flask db upgrade
+#                      + every plugin's chain on utf8mb4 MySQL 8, idempotent on
+#                      a second run. The pytest suite only exercises SQLite
+#                      create_all(), so this is what catches an Alembic
+#                      regression on MySQL before it ships.
+
+name: CI
+
+# Action versions are the Node 24 native releases (checkout@v5, setup-node@v5,
+# setup-python@v6). The v4/v5 generation targets Node 20, which the runners now
+# force onto Node 24 with a deprecation warning on every job - working today,
+# a hard failure whenever GitHub drops the shim.
+#
+# Jobs run on the org's self-hosted "arc-runner-set" (enterprise
+# ge-aerospace-runner-group, Linux). GitHub-hosted runners are blocked by the
+# org IP allow list (hosted Azure runner IPs are not allow-listed -> checkout
+# 403), so ubuntu-latest cannot be used here. arc-runner-set checks out from an
+# internal allow-listed IP and, being Linux, still supports service containers.
+
+on:
+  push:
+  pull_request:
+
+# A second push supersedes the first: the older run answers a question nobody is
+# asking any more, and it holds a self-hosted runner while doing it.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend:
+    runs-on: arc-runner-set
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+          cache: pip
+      - run: pip install -r requirements-dev.txt
+      - run: python -m pytest -q
+
+  naming:
+    runs-on: arc-runner-set
+    steps:
+      - uses: actions/checkout@v5
+      - run: bash scripts/check-naming-and-style.sh
+
+  gates:
+    # Prove the gates RAN. Several skip themselves when the file they read is
+    # absent, which is correct in this checkout (docs/ becomes the wiki) and was
+    # silently wrong here for months: the modules skipped, CI went green, and an
+    # outside branch added nine routes documented nowhere and passed.
+    #
+    # A gate that stops running is worse than no gate, because nobody looks at
+    # it again.
+    runs-on: arc-runner-set
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+          cache: pip
+      - run: pip install -r requirements-dev.txt
+      - run: bash scripts/check-gates-ran.sh
+
+  frontend:
+    runs-on: arc-runner-set
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npx vitest run
+      - run: npm run build
+
+  lean-build:
+    # ADR-013 Phase 5: prove a per-site build carries only its chosen plugins.
+    # Builds a lean site (machines + printers) and asserts an omitted plugin's
+    # code is absent from the bundle - the delete-a-plugin guarantee in CI.
+    runs-on: arc-runner-set
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: cd frontend && npm ci
+      - name: Build lean site (machines + printers)
+        run: |
+          printf '{ "site": "ci-lean", "plugins": ["machines", "printers"] }' \
+            > /tmp/lean-profile.json
+          bash scripts/build-site.sh /tmp/lean-profile.json /tmp/leansite
+      - name: Assert omitted plugin code is absent, chosen present
+        run: |
+          assets=/tmp/leansite/frontend-dist/assets
+          for code in PartsKiosk ManifestEditor USBLabelBatch KnowledgeBaseDetail; do
+            if grep -rqoh "$code" "$assets"/*.js; then
+              echo "FAIL: omitted-plugin code '$code' leaked into the lean bundle"
+              exit 1
+            fi
+          done
+          for code in MachineDetail PrinterDetail; do
+            grep -rqoh "$code" "$assets"/*.js || {
+              echo "FAIL: chosen-plugin code '$code' missing from the lean bundle"
+              exit 1; }
+          done
+          # Core frontends (no manifest, e.g. applications) must ship in EVERY
+          # build regardless of SITE_PLUGINS, or a lean site loses a core page.
+          grep -rqoh "ApplicationsList" "$assets"/*.js || {
+            echo "FAIL: core page 'ApplicationsList' missing from the lean bundle"
+            exit 1; }
+          test -d /tmp/leansite/plugins/machines
+          test ! -d /tmp/leansite/plugins/printedparts
+          echo "lean build verified: only chosen plugins present"
+
+  # NOTE: the MySQL-8 migration/seed job (fresh `flask db upgrade` + every
+  # plugin chain + strict-mode seeders on a real MySQL 8) runs on the internal
+  # CI server, which supports service containers. The org's arc-runner-set is
+  # Kubernetes/ARC without docker-in-docker, so GitHub Actions service
+  # containers ("services: mysql") are unavailable here ("Job Container is
+  # required"). That coverage stays on the internal CI rather than being
+  # duplicated on GitHub.

.github/workflows/publish-images.yml

@@ -0,0 +1,103 @@
+# Build and publish per-channel container images to GHCR.
+#
+# WHY this exists: pilot dev workstations sit behind an inspecting proxy
+# (Zscaler) that resets npm's many small fetches mid-install, so building the
+# image FROM SOURCE on a pilot box is unreliable. These runners
+# (arc-runner-set) install npm cleanly - the CI `frontend` job already proves
+# it - so we build the image ONCE here and pilots pull the finished image.
+# A single image pull is one resumable HTTPS stream, far more robust through
+# the proxy than hundreds of npm requests.
+#
+# Channels are mapped to how THIS repo actually ships, which is not how the
+# branch this came from ships. Upstream, main is a release branch and dev-be is
+# the trunk. Here main IS the trunk - it runs hundreds of commits past the last
+# release - and releases are tags (ADR-007). Publishing main as :stable would
+# put unreleased work behind a word that promises the opposite, to sites that
+# have no way to know:
+#
+#   tag v*  -> ghcr.io/<owner>/shopdb-flask:stable  (badge off)  the release
+#   main    -> ghcr.io/<owner>/shopdb-flask:edge    (DEV badge)  the trunk
+#
+# The image also carries a short-SHA tag for traceability and rollback.
+#
+# Automatic publishing is OFF until someone confirms the GHCR package exists
+# under this owner and decides who may pull it. Re-enable by uncommenting the
+# push: block below; workflow_dispatch works meanwhile.
+
+name: publish-images
+
+on:
+  # push:
+  #   tags:
+  #     - 'v*'
+  #   branches:
+  #     - main
+  # Manual rebuild/publish of the current ref's channel image.
+  workflow_dispatch:
+
+# One in-flight publish per branch; a newer push supersedes an older one.
+concurrency:
+  group: publish-images-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-push:
+    runs-on: arc-runner-set
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+
+      # Lowercase the owner: GHCR repository paths must be lowercase, but
+      # github.repository_owner can carry uppercase (e.g. ge-aero is fine, but
+      # this keeps the workflow correct for any owner casing).
+      - name: Resolve image name and channel tag
+        id: meta
+        run: |
+          owner="$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')"
+          image="ghcr.io/${owner}/shopdb-flask"
+          # A tag is a release, anything else is the trunk. Deliberately not
+          # keyed on the branch name: a release here is a tag, so keying on
+          # "main" would label the trunk stable.
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            channel="stable"
+          else
+            channel="edge"
+          fi
+          echo "image=${image}" >> "$GITHUB_OUTPUT"
+          echo "channel=${channel}" >> "$GITHUB_OUTPUT"
+          echo "sha=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Connect to a persistent, out-of-cluster BuildKit deployment instead of
+      # spinning up a builder against a local Docker daemon. The arc-runner-set
+      # pods have no Docker daemon (no /var/run/docker.sock) and cannot run a
+      # privileged DinD sidecar under cluster policy, so we point Buildx at a
+      # remote buildkitd Service. The endpoint is provided as a repo/org secret
+      # (e.g. tcp://buildkit.buildkit.svc.cluster.local:1234), so it is not
+      # hardcoded here. See deploy/ci/buildkit-remote.yaml for the deployment.
+      - name: Set up Buildx (remote BuildKit)
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: remote
+          endpoint: ${{ secrets.BUILDKIT_ENDPOINT }}
+
+      - name: Build and push channel image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.channel }}
+            ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.channel }}-${{ steps.meta.outputs.sha }}
+          # Reuse the channel tag as a cache source/target so subsequent builds
+          # only redo layers that actually changed.
+          cache-from: type=registry,ref=${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.channel }}
+          cache-to: type=inline

.github/workflows/scan-darkwing-portable.yml

@@ -0,0 +1,32 @@
+# Darkwing vulnerability scan, manual dispatch.
+#
+# Copied verbatim from the ge-aero/darkwing README so it stays byte-identical
+# to the sanctioned integration. Do not edit this file to add triggers or
+# gating - see scan-darkwing-pr.yml for that, which is ours to change.
+#
+# The file must sit on the default branch before a scan can run on ANY branch.
+name: Scan (darkwing, portable)
+
+on:
+  workflow_dispatch:
+    inputs:
+      target_ref:
+        description: Ref, branch, or sha of this repo to scan
+        required: false
+        type: string
+        default: main
+
+permissions:
+  contents: read # checkout this repo via the ambient GITHUB_TOKEN
+  security-events: write # SARIF upload to the Security tab
+  actions: read # required by upload-sarif on private/internal repos
+
+jobs:
+  scan:
+    runs-on: darkwing-scan
+    steps:
+      # @v1 is a moving tag pointing to the latest release that is compatible
+      # with this workflow file.
+      - uses: ge-aero/darkwing@v1
+        with:
+          target_ref: ${{ inputs.target_ref || 'main' }}

.github/workflows/scan-darkwing-pr.yml

@@ -0,0 +1,62 @@
+# Darkwing scan on pull requests, so the "check against darkwing" is a check
+# and not a thing somebody remembers to click.
+#
+# WHY THIS IS SEPARATE from scan-darkwing-portable.yml: that file is copied
+# byte-for-byte from the ge-aero/darkwing README and is left alone so it keeps
+# matching the sanctioned integration. Everything below is ours.
+#
+# THE TRAP THIS AVOIDS. The README workflow resolves its scan target as
+# `inputs.target_ref || 'main'`. On a pull_request event there are no inputs,
+# so that expression falls through to 'main' and the job scans the default
+# branch instead of the code under review - a green Darkwing check that never
+# looked at the change. Resolve the head SHA explicitly.
+#
+# Darkwing exits 0 whatever it finds (its own FAQ: "Does a finding fail my
+# build? No."), so a passing job means the scan RAN, not that the code is
+# clean. Findings land in Security -> Code scanning. Turning a finding into a
+# hard failure means reading findings.sarif ourselves; the commented step at
+# the bottom is the shape of that, deliberately left off until we have seen the
+# false-positive rate on this repo.
+name: Scan (darkwing, PR)
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+# One scan per PR. A new push supersedes the old one rather than queueing a
+# second Bedrock spend against a diff nobody is reviewing any more.
+concurrency:
+  group: darkwing-pr-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  scan:
+    runs-on: darkwing-scan
+    steps:
+      - uses: ge-aero/darkwing@v1
+        with:
+          # The PR's head, NOT the default branch. See the note above.
+          target_ref: ${{ github.event.pull_request.head.sha }}
+
+      # Gating, once the signal is trusted. Darkwing writes findings.sarif into
+      # its work dir and attaches it as the `findings` artifact; this reads the
+      # severities out and fails on error-level results only.
+      #
+      # - name: Fail on error-level findings
+      #   run: |
+      #     python - <<'PY'
+      #     import json, pathlib, sys
+      #     sarif = pathlib.Path('darkwing/findings.sarif')
+      #     if not sarif.is_file():
+      #         sys.exit('no findings.sarif: the scan did not produce results')
+      #     doc = json.loads(sarif.read_text())
+      #     bad = [r for run in doc.get('runs', [])
+      #              for r in run.get('results', [])
+      #              if r.get('level') == 'error']
+      #     if bad:
+      #         sys.exit(f'{len(bad)} error-level finding(s); see the Security tab')
+      #     PY

.github/workflows/smoke.yml

@@ -0,0 +1,13 @@
+name: Runner smoke
+on:
+  workflow_dispatch:
+jobs:
+  hello:
+    runs-on: arc-runner-set
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          echo "runner: $RUNNER_NAME  os: $RUNNER_OS"
+          python3 --version || echo "no python3 on PATH"
+          node --version   || echo "no node on PATH"
+          bash --version | head -1

.gitignore

@@ -28,7 +28,11 @@ env/
 
 # IDE
 .idea/
-.vscode/
+.vscode/*
+# Share the team's launch/tasks/extensions; keep personal settings out.
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/extensions.json
 *.swp
 *.swo
 *~
@@ -69,9 +73,73 @@ id_rsa.*
 *.ppk
 *.p12
 *.pfx
+
+# Local/test TLS material for the dev HTTPS listener. Self-signed, per-host,
+# never shipped. The container mounts these at runtime; a site provides its own.
+certs/
 secrets.json
 secrets.yaml
 secrets.yml
 *_secret
 *_secrets
 credentials.json
+scripts/site_imports/wjf/idmap.json
+
+# work-PC publication clone: bundle drop folder for the transfer pipeline
+_transfer/
+
+# Local developer scratch notes and chat handoffs - never committed
+devnotes/
+
+# docs/ is generated/published to the wiki, not tracked in the product repo.
+# A single tracked file here makes docs/ exist in the CI checkout, which
+# defeats the intentional skip in the docs publish/version tests. Keep this
+# local-only guide out of version control so those tests skip as designed.
+docs/CSV-IMPORT-GUIDE.md
+
+# Local-only authored docs (executive summaries, workflow/security writeups,
+# planner exports, draft decks and diagrams). Same reasoning as above: keep
+# personal docs out of version control. docs/openapi.json stays tracked and
+# is intentionally NOT ignored here.
+docs/EXECUTIVE-SUMMARY.md
+docs/DESIGN-DECISIONS-agent.md
+docs/OPERATOR-WORKFLOW.md
+docs/SECURITY-RISK-ASSESSMENT.md
+docs/ShopDB-Planner-Tasks.csv
+docs/DRAFT--ShopDB-CSV-Import-Guide.pptx
+docs/diagrams/
+docs/media/
+
+# Local-only working artifacts: DB dumps, sample/test datasets, scratch
+# scripts, captured command output, generated maps/reports, vulnerability
+# scan output, and staged agent publish trees. None of these are product
+# source; they are developer scratch that should never enter version control.
+# exports/ (merge kits, decks, catalog snapshots) stays on disk for reference
+# but is not tracked.
+backups/
+exports/
+testdata/
+vuln/
+agent/publish-wjf/
+*.sql
+shopmap.pdf
+shopmap.png
+agent_build.txt
+agent_publish.txt
+backend_out.txt
+backend_out2.txt
+docker_build.txt
+docker_up.txt
+gates_out.txt
+pytest_targeted.txt
+pt*.txt
+alandry.py
+kendry.py
+
+# Visual Studio local editor state (not product source).
+.vs/
+
+# Scratch tooling under scripts/ (catalog diff/merge helpers, docx generator).
+# Not product source; developer-local utilities.
+scripts/.temp/
+scripts/docs/

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "Vue.volar",
+    "dbaeumer.vscode-eslint",
+    "ms-azuretools.vscode-docker"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,30 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Flask API (:5001)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "flask",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "FLASK_APP": "shopdb",
+        "FLASK_ENV": "development",
+        "FLASK_DEBUG": "1"
+      },
+      "args": ["run", "--port", "5001", "--no-reload"],
+      "jinja": true,
+      "justMyCode": false,
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Pytest (current file)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "cwd": "${workspaceFolder}",
+      "args": ["${file}", "-v"],
+      "console": "integratedTerminal"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,46 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Backend: flask run (:5001)",
+      "type": "shell",
+      "command": "${workspaceFolder}/venv/bin/flask run --port 5001",
+      "options": {
+        "cwd": "${workspaceFolder}",
+        "env": { "FLASK_APP": "shopdb" }
+      },
+      "windows": {
+        "command": "${workspaceFolder}\\venv\\Scripts\\flask.exe run --port 5001"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Frontend: npm run dev (:5173)",
+      "type": "shell",
+      "command": "npm run dev",
+      "options": { "cwd": "${workspaceFolder}/frontend" },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Dev site (backend + frontend)",
+      "dependsOn": [
+        "Backend: flask run (:5001)",
+        "Frontend: npm run dev (:5173)"
+      ],
+      "dependsOrder": "parallel",
+      "problemMatcher": []
+    },
+    {
+      "label": "Check: naming + tests + build",
+      "type": "shell",
+      "command": "bash scripts/check-naming-and-style.sh && venv/bin/python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build",
+      "windows": {
+        "command": "bash scripts/check-naming-and-style.sh && venv\\Scripts\\python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build"
+      },
+      "options": { "cwd": "${workspaceFolder}" },
+      "problemMatcher": []
+    }
+  ]
+}

CLAUDE.md

@@ -1,129 +1,141 @@
 # ShopDB Flask Project
 
-Modern rewrite of the classic-ASP shopdb. Built as a framework so sister GE Aerospace sites can adopt it. Plugin system is the product.
+Modern rewrite of the classic-ASP shopdb. Built as a framework so sister GE
+Aerospace sites can adopt it. The plugin system is the product.
+
+**This site is not the only site.** Anything that names West Jefferson - a
+hostname, a share path, a subnet, a machine-number format, a label prefix - is a
+defect unless it is a setting with a neutral default, a site-namespaced
+directory, or seed data. That is ADR-015, and it is the rule most often broken
+in the places tooling cannot see: PowerShell, the installer, JSON, the imaging
+share.
+
+## Facts that move live in the map
+
+`docs/PROJECT-MAP.md` is GENERATED. It carries the product and contract
+versions, the plugin inventory, every Alembic chain head, the ADR index with
+status, and the size of the codebase. Read it instead of asking; regenerate it
+rather than correcting it by hand:
+
+```bash
+venv/bin/python scripts/gen_project_map.py           # write
+venv/bin/python scripts/gen_project_map.py --check   # CI form
+```
+
+Hand-written version numbers in this file were wrong by two contract releases
+and 400 tests before the map existed. Nothing that the generator can derive
+should be typed here again.
+
+## Where to look
+
+| question | read |
+|---|---|
+| what a name may be called | `CONTRIBUTING.md` |
+| why the architecture is like that | `docs/adr/` (index in the map) |
+| what a plugin may touch | `docs/PLUGIN-HOOKS.md` |
+| what the collector sends | `docs/COLLECTOR-INTEGRATION.md`, ADR-006 |
+| how a site is deployed | `docs/INSTALL-WINDOWS.md`, `docs/OPERATE-WINDOWS.md` |
+| how code reaches GitHub | `tools/export-github.sh` |
+| which branch reaches which server | `devnotes/deploy-and-branch-model.html` |
+
+## Standards are gates, not prose
+
+Compliance is checked, not remembered. Run these rather than re-reading the
+rules:
+
+```bash
+bash scripts/check-naming-and-style.sh    # naming, style, site literals (ADR-015)
+venv/bin/python -m pytest -q              # includes the docs publishability gate
+venv/bin/python -m pytest tests/test_plugin_migrations.py   # chain heads registry
+venv/bin/python scripts/gen_project_map.py --check
+```
+
+A new plugin table means updating `PLUGIN_TABLE_OWNERS` and
+`EXPECTED_HEAD_REVISION` in `tests/test_plugin_migrations.py`.
+
+Dependencies have their own check. It needs the network, so it is not in the
+suite - run it before a release, and see `docs/DEPENDENCY-SECURITY.md`:
+
+```bash
+venv/bin/python scripts/scan_sbom.py --gate    # exit 1 on a SHIPPED finding
+```
 
 ## Database
 
-- **Active database:** `shopdb_flask` (MySQL, asset-based schema)
-- **Legacy database:** `shopdb` (Classic ASP schema, used only for one-time data import via `scripts/import_from_mysql.py`)
-- **Connection:** `.env` file. See `.env.example`.
+- **Active:** `shopdb_flask` (MySQL, asset-based schema)
+- **Legacy:** `shopdb` (classic ASP schema; one-time import only)
+- **Connection:** `.env`, see `.env.example`
 
-Architecture decisions live in `docs/adr/`. Read those before making schema or contract changes.
+Core migrations run with `flask db upgrade`; every plugin owns its own chain
+(ADR-008) and runs with `flask plugin upgrade-all`. **A deploy needs both** -
+skipping the second is how a new column reaches production as a 1054 error.
 
-- ADR-001: Asset model is the platform contract (Machine retires) - ACCEPTED
-- ADR-002: Plugin contract versioning (semver) - ACCEPTED
-- ADR-003: Plugin distribution model (in-tree bundled + filesystem-based external) - ACCEPTED
-- ADR-004: Deployment topology (per-site instances, not multi-tenant) - ACCEPTED
-- ADR-005: Equipment vs measuringtools plugin scope - ACCEPTED
-- ADR-006: Plugin collector contract pattern - ACCEPTED
+Tests run on SQLite, production is MySQL. Dialect drift is not caught by the
+suite: `ORDER BY ... NULLS LAST` parses on SQLite and is rejected by MySQL. Sort
+in Python when in doubt.
 
 ## Coding convention
 
-`CONTRIBUTING.md` defines naming rules (DB tables, columns, Python, JS, Vue, API). Pre-commit hook at `scripts/check-naming-and-style.sh` enforces them. Read `CONTRIBUTING.md` before naming any new identifier.
-
-## Current state (as of 2026-07-10)
-
-Refactor phases 0-5 landed; phase 6 (multi-site distribution readiness) in progress.
-
-### Phases done
-
-- **Phase 0**: 6 ADRs accepted, naming convention v1, pre-commit style hook
-- **Phase 1**: 8 smoke tests + 7 production-config tests, Flask-SQLAlchemy 3 fixtures, uv lockfile, hardened ProductionConfig
-- **Phase 2**: contract surface defined (`__contract_version__`, `BasePlugin` hooks, `docs/PLUGIN-HOOKS.md`), 51 contract tests
-- **Phase 3**: manifest-first loader, fail-loud/isolate policy, contract-version range checking, auto-register core blueprints, `shopdb.api` namespace, `BasePlugin.get_setting/set_setting` helpers
-- **Phase 4**: `flask plugin new <name>` CLI, scaffold templates, 14 canary tests, `docs/PLUGIN-QUICKSTART.md`
-- **Phase 5**: ADRs moved to `docs/adr/`, Alembic baseline migration, per-site deploy artifacts (`Dockerfile`, `docker-compose.yml`, `docs/DEPLOY.md`)
-
-### Active state
-
-- 206 tests passing, naming/style check green
-- `__contract_version__` at 0.5.0
-- 10 bundled plugins all satisfy contract: computers, employees, equipment, knowledgebase, network, notifications, printers, slides, usb, warranty
-- Single core Alembic chain: baseline `68b3947ae14f` -> head `7d16_directoryemployees` (23 migrations). A fresh site runs `flask db upgrade` from empty; it is reproducible and idempotent.
-- Pre-1.0 framework; sister sites should pin tight `core_version` ranges until contract reaches 1.0
-
-### Deferred
-
-- Equipment data migration (one-shot script for legacy ASP shopdb -> assets). Per ADR-001, only `category='Equipment' AND machinenumber IS NOT NULL` migrates. Skill `migrating-asset-schema` documents the pattern; the actual one-shot script lives in `scripts/migration/` when run.
-- Printers retirement: legacy `PrinterData` model + frontend changes. Coordinated with the equipment data migration.
-- `measuringtools` plugin (ADR-005). First plugin to be built using the scaffold.
-- Frontend hook contract for asset-detail, map markers, search results
-- Alembic per-plugin migration chains (the framework supports them; bundled plugins haven't moved off `db.create_all()` yet)
-
-## Quick start
-
-```bash
-# Start dev environment
-~/start-dev-env.sh
-
-# Activate venv and install deps
-cd /home/camp/projects/shopdb-flask
-source venv/bin/activate
-pip install -r requirements.txt
-
-# Configure environment
-cp .env.example .env
-# Edit .env with DB credentials, JWT secrets
-
-# Create / update database tables via the Alembic chain
-flask db upgrade
-
-# Seed RBAC, default settings, and reference data (all idempotent)
-flask seed permissions
-flask seed settings
-flask seed reference-data
-
-# Restart services
-pm2 restart shopdb-flask-api shopdb-flask-ui
-```
-
-## Service URLs
-
-- Flask API: http://localhost:5001
-- Flask UI: http://localhost:5173
-- Legacy ASP (data source for one-time import): http://192.168.122.151:8080
+`CONTRIBUTING.md` is authoritative: lowercase concatenated DB columns, snake_case
+pure-code identifiers, a closed acronym list, banned shorthand. The pre-commit
+hook `scripts/check-naming-and-style.sh` enforces what it can.
 
 ## Plugin structure
 
 ```
-plugins/
-  <plugin_name>/
-    __init__.py
-    plugin.py          # BasePlugin implementation
-    manifest.json      # Plugin metadata (name, version, dependencies, api_prefix)
-    models/
-      __init__.py      # Export all models
-      <model>.py       # SQLAlchemy models
-    api/
-      __init__.py
-      routes.py        # Flask Blueprint
-    services/          # Optional, business logic
-    schemas/           # Optional, marshmallow schemas
-    migrations/        # Optional, plugin-specific Alembic migrations
+plugins/<name>/
+  manifest.json      # metadata, single source of truth (ADR-002)
+  plugin.py          # BasePlugin implementation
+  models/            # __init__.py exports every model
+  api/routes.py      # Flask blueprint
+  migrations/        # this plugin's own Alembic chain
+  services/ schemas/ frontend/ client/   # as needed
 ```
 
-Each plugin must have:
-
-- `models/__init__.py` exports all models
-- `plugin.py` extends `BasePlugin`
-- `manifest.json` with metadata (single source of truth per ADR-002)
-- No direct imports from core code (use the contract surface defined in ADR-001)
+No plugin imports core directly - everything goes through the `shopdb.api`
+contract surface. A manifest-less directory under `plugins/` is core frontend
+surface and always ships.
 
 ## Key files
 
-- `shopdb/__init__.py` - app factory, blueprint registration
-- `shopdb/plugins/base.py` - BasePlugin ABC, PluginMeta dataclass
-- `shopdb/plugins/loader.py` - filesystem discovery, dependency-aware loading
-- `shopdb/core/api/assets.py` - example of optional plugin imports
-- `frontend/src/router/index.js` - frontend routing
-- `frontend/src/components/AppSidebar.vue` - navigation menu
-- `docs/adr/` - architecture decision records
+- `shopdb/__init__.py` - app factory, version constants
+- `shopdb/plugins/base.py` - BasePlugin, PluginMeta
+- `shopdb/plugins/loader.py` - discovery and dependency-aware loading
+- `shopdb/plugins/alembic_template.py` - the env every plugin chain runs through
+- `frontend/src/router/index.js`, `frontend/src/components/AppSidebar.vue`
+- `tools/export-github.sh` - scrub and publication gate; builds the dist for
+  the branch it is on (`wj` -> /shopdb, `dev` -> /ops) and refuses on any other
+- `tools/mirror-wilm.sh` - push a carried wilm bundle to gitea
 
-## Migration notes
+## State
 
-- `migrations/DATA_MIGRATION_GUIDE.md` - one-time import from legacy ASP shopdb
-- `migrations/MIGRATE_USB_DEVICES_FROM_EQUIPMENT.md` - USB device migration from equipment table
-- `migrations/FIX_LOCATIONONLY_EQUIPMENT_TYPES.md` - LocationOnly equipment type fix
-- `migrations/PRODUCTION_MIGRATION_GUIDE.md` - production import methods
-- `migrations/rename_underscore_columns.sql` - one-time rename of snake_case columns to lowercase concatenated (per CONTRIBUTING.md)
-- `migrations/versions/` - the core Alembic chain (baseline `68b3947ae14f` -> head `7d16_directoryemployees`). Run `flask db upgrade` to apply.
+Refactor phases 0-5 landed; phase 6 (multi-site distribution readiness) largely
+complete. The last milestone before 1.0 is unchanged and still open: the
+legacy-data import plus a production pilot (`scripts/site_imports/wjf/` is the
+reference loader, validated end to end).
+
+Pre-1.0 framework. Sister sites pin tight `core_version` ranges until the
+contract reaches 1.0.
+
+### Deferred
+
+- Equipment data migration (legacy ASP -> assets). Per ADR-001 only
+  `category='Equipment' AND machinenumber IS NOT NULL` migrates.
+- Printers retirement: legacy `PrinterData` model, coordinated with the above.
+
+## Quick start
+
+```bash
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env          # DB credentials, JWT secrets
+
+flask db upgrade              # core chain
+flask plugin upgrade-all      # every plugin chain
+flask seed permissions && flask seed settings && flask seed reference-data
+
+pm2 restart shopdb-flask-api shopdb-flask-ui
+```
+
+Dev API on :5001, dev UI on :5173. `venv/bin/python tools/shot.py /route` logs
+in and screenshots a page.

CONTRIBUTING.md

@@ -24,6 +24,24 @@
 - **Index names**: `idx_<table>_<column>`. Underscores allowed here only because indexes are infrastructure, not data.
   - Good: `idx_machines_locationid`
 
+### Migrations and deploy ordering
+
+- **A model change ships WITH its migration in the same change.** Adding or
+  changing a column/table on a SQLAlchemy model without the matching Alembic
+  migration is a broken change, even if it passes tests against a freshly built
+  schema.
+- **Code and schema must never deploy out of step.** A model that references a
+  column its migration has not applied yet makes MySQL raise
+  `1054 Unknown column`, which 500s every query on that table (this is not a
+  degraded read - the whole endpoint fails).
+- **Bringing up a new image MUST run migrations before serving traffic**, in
+  order: `flask db upgrade` (core chain) then `flask plugin upgrade-all`
+  (per-plugin chains). A rebuilt image with new model code but an
+  un-migrated database will 500 until this runs.
+- Core schema lives in `migrations/versions/`; each plugin owns its own chain
+  under `plugins/<name>/migrations/`. New schema = a new migration with an
+  idempotent guard and a real downgrade, clean on strict MySQL 8.
+
 ### Allowed acronyms (closed list, expand by PR)
 
 - **Universal**: `id`, `url`, `api`, `http`, `https`, `json`, `jwt`, `sql`, `os`, `ip`, `dns`, `csv`, `pdf`, `cors`, `ttl`, `uuid`, `html`, `css`, `orm`
@@ -136,7 +154,7 @@ When creating a new plugin:
 4. Follow naming conventions above.
 5. Run `flask plugin install <name>` to install.
 
-See `docs/PLUGIN-QUICKSTART.md` (when published) for the 30-minute walkthrough.
+See the PLUGIN-QUICKSTART wiki page (when published) for the 30-minute walkthrough.
 
 ## Testing
 
@@ -151,6 +169,56 @@ Tests are required for:
 - New plugin hooks (contract test)
 - Schema migrations (before/after data integrity)
 
+## Branches: what belongs on main, and what does not
+
+`main` is the product every site runs and the publication mirror exports.
+`<site>` branches hold work that is not ready for other sites to see. There are
+two: `wj` here, and `wilm` on the corporate GitHub, where the other site
+develops the .NET endpoint agent.
+
+A site branch is not a fork. Both feed `main`, and the sooner they do it the
+cheaper it is. A branch the dev box cannot see is still a branch: `wilm` is not
+visible from here because this machine has no GitHub account, which is why
+`fetch-wilm-branch.cmd` on the share exists to bring it back for review.
+
+**Most work is product.** ADR-015 gives site differences three homes on `main`:
+a setting with a neutral default, seed data, or a site-namespaced directory
+(`scripts/site_imports/<site>/`, which the style gate exempts). That is the only
+site-specific home in the tree, so a site branch is about TIMING, not locality:
+things that are not ready yet, rather than things that are permanently ours.
+
+Say which at commit time, with a trailer, because the decision does not survive
+being deferred - months later it is a list of subject lines and a guess:
+
+```bash
+git commit -m "Add the thing" -m "Scope: product"   # main should have it
+git commit -m "Add the thing" -m "Scope: site"      # this site alone
+```
+
+Then:
+
+```bash
+tools/wj-status.sh                          # what is unpromoted, and where it belongs
+tools/promote-to-main.sh --dry-run <sha>    # what files would reach main
+tools/promote-to-main.sh <sha> [<sha> ...]  # oldest first; runs main's gates
+tools/git-push.sh main                      # you push, deliberately
+```
+
+Windows equivalents are `tools\git-push.cmd` and `tools\promote-to-main.cmd`.
+
+Promotion cherry-picks NAMED commits rather than merging the branch. Merging
+takes the site work along with the product work, which is how a site branch
+quietly becomes the product.
+
+**The failure to watch for is not what you think.** Promoting something
+site-specific by accident is caught by the ADR-015 gate on the way into `main`.
+The real risk is product work sitting on a site branch until bringing it back is
+a port rather than a merge - one such round trip cost a MySQL dialect fix, a
+contract violation and a plugin install.
+
+So rebase the site branch on `main` often, and promote as you go rather than in
+one batch at the end.
+
 ## Code review checklist
 
 - [ ] No underscores in table or column names

Dockerfile

@@ -2,9 +2,12 @@
 #
 # One image, one site. Per ADR-004, each adopting facility runs its own
 # stack with its own DB, secrets, and enabled-plugin list. This image
-# bundles all ten core plugins (computers, employees, equipment,
-# knowledgebase, network, notifications, printers, slides, usb, warranty);
-# install them at runtime with `flask plugin install <name>`.
+# bundles all 13 catalog plugins (computers, employees, geenforce,
+# knowledgebase, machines, measuringtools, network, notifications,
+# printedparts, printers, slides, usb, warranty); a site installs + enables
+# the ones it wants with `flask plugin install <name>` (or, declaratively,
+# `flask plugin apply-profile <profile.json>`). Per ADR-013 a future lean
+# build stages only the chosen plugin directories into this image.
 #
 # The frontend is built in a first stage and its dist output is copied into
 # the final image so Flask can serve the SPA (register_frontend_routes in
@@ -20,16 +23,75 @@ FROM node:20-slim AS frontendbuild
 
 WORKDIR /build
 
-# Copy only the manifests first so `npm ci` caches on dependency changes.
-COPY frontend/package*.json ./
-RUN npm ci
+# Optionally trust the site's corporate root CA so npm's TLS to the registry
+# validates behind an inspecting proxy. The .pem is gitignored and absent from a
+# clean checkout, so the copy is made optional by pairing it with a file that
+# always exists; the cert is installed only when actually provided. Without it
+# npm 10.x behind an inspecting proxy fails silently and leaves an incomplete
+# node_modules; a clean build with no proxy is unaffected.
+COPY corp-root-ca.pem* frontend/package.json /tmp/corpca/
+# node:20-slim ships without the ca-certificates package (no update-ca-certificates
+# and no /usr/local/share/ca-certificates), so install it before trusting the cert.
+RUN if [ -f /tmp/corpca/corp-root-ca.pem ]; then \
+        apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
+        rm -rf /var/lib/apt/lists/* && \
+        cp /tmp/corpca/corp-root-ca.pem /usr/local/share/ca-certificates/corp-root-ca.crt && \
+        update-ca-certificates; \
+    fi
 
-COPY frontend/ ./
-RUN npm run build
-# Output lands in /build/dist (Vite default), copied into the final stage below.
+# Copy only the manifests first so `npm ci` caches on dependency changes.
+COPY frontend/package*.json ./frontend/
+# Trust the corp CA for npm's TLS only when it was actually installed above. The
+# guard keeps NODE_EXTRA_CA_CERTS unset on a clean checkout (no cert), so Node
+# does not warn about a missing cert path; a proxy-inspected build still gets
+# the cert because the file is present.
+# Install the frontend dependencies. vite and the rest of the build toolchain
+# live under devDependencies, so include them explicitly (--include=dev).
+# Behind an inspecting proxy (Zscaler) each package fetch is slow (40-50s) and
+# npm's default concurrency piles up parallel sockets that the proxy resets
+# mid-stream, making npm abort with "Exit handler never called" and leaving an
+# incomplete node_modules with no vite. Serializing to a single socket
+# (maxsockets 1) lets every fetch complete; the retry loop and raised timeouts
+# ride out any remaining transient reset, and the final test hard-verifies the
+# toolchain landed so a truncated install fails loudly here rather than as a
+# confusing "vite: not found" three steps later.
+RUN if [ -f /usr/local/share/ca-certificates/corp-root-ca.crt ]; then \
+        export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt; \
+    fi; \
+    cd frontend && \
+    npm config set fetch-retries 5 && \
+    npm config set fetch-retry-factor 2 && \
+    npm config set fetch-retry-mintimeout 20000 && \
+    npm config set fetch-retry-maxtimeout 120000 && \
+    npm config set fetch-timeout 600000 && \
+    npm config set maxsockets 1 && \
+    ( npm ci --include=dev --no-audit --no-fund \
+        || { echo "npm ci attempt 1 failed, retrying..."; sleep 5; npm ci --include=dev --no-audit --no-fund; } \
+        || { echo "npm ci attempt 2 failed, retrying..."; sleep 10; npm ci --include=dev --no-audit --no-fund; } ) && \
+    test -x node_modules/.bin/vite || { \
+        echo "ERROR: node_modules/.bin/vite missing after npm ci (proxy likely truncated the install)."; \
+        exit 1; \
+    }
+
+# The frontend keeps its repo-relative layout here, because npm prebuild runs
+# `node ../scripts/stage-frontend.mjs`, which stages each plugin's frontend/ into
+# the Vite tree and codegens routes.gen.js. That script resolves its repo root as
+# its own directory's parent, so it needs scripts/ and plugins/ as SIBLINGS of
+# frontend/. Building with frontend/ flattened to the stage root made `../scripts`
+# resolve to /scripts and the build failed on a missing module.
+COPY scripts/stage-frontend.mjs ./scripts/
+COPY plugins/ ./plugins/
+
+COPY frontend/ ./frontend/
+RUN if [ -f /usr/local/share/ca-certificates/corp-root-ca.crt ]; then \
+        export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt; \
+    fi; \
+    cd frontend && npm run build
+# Output lands in /build/frontend/dist (Vite default), copied into the final
+# stage below.
 
 # ---- Stage 2: Python application image ----
-FROM python:3.12-slim AS base
+FROM python:3.14-slim AS base
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
@@ -57,7 +119,14 @@ COPY scripts/ ./scripts/
 COPY wsgi.py ./
 
 # Built SPA from stage 1. Flask serves it via register_frontend_routes.
-COPY --from=frontendbuild /build/dist ./frontend/dist
+COPY --from=frontendbuild /build/frontend/dist ./frontend/dist
+
+# Create instance/ IN THE IMAGE, owned by the app user, before the chown below.
+# Docker seeds an empty named volume from the image's content at the mountpoint,
+# ownership included. Without this the mountpoint is created root-owned 0755 and
+# the container, which runs as shopdb, cannot write plugins.json or any upload
+# into its own instance directory.
+RUN mkdir -p /app/instance
 
 RUN useradd --create-home --shell /bin/bash shopdb \
     && chown -R shopdb:shopdb /app
@@ -66,14 +135,20 @@ USER shopdb
 EXPOSE 5001
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-    CMD curl --fail --silent http://localhost:5001/api/auth/login -X POST \
+    CMD curl --silent http://localhost:5001/api/auth/login -X POST \
         -H "Content-Type: application/json" -d '{}' \
         | grep -q "VALIDATION_ERROR" || exit 1
 
+# Threaded workers, matching docker-compose.yml - see the reasoning there. A
+# compose file overrides this CMD, but an image run without one (a plain
+# `docker run`, a site's own orchestrator) would otherwise still get the
+# blocking sync default and the same starvation.
 CMD ["gunicorn", \
      "--bind", "0.0.0.0:5001", \
+     "--worker-class", "gthread", \
      "--workers", "4", \
-     "--timeout", "60", \
+     "--threads", "8", \
+     "--timeout", "30", \
      "--access-logfile", "-", \
      "--error-logfile", "-", \
      "wsgi:app"]

README.md

@@ -1,233 +1,293 @@
-# ShopDB Flask
-
-A modern rewrite of the classic ASP/VBScript ShopDB application using Flask (Python) and Vue 3. This application manages shop floor machines, PCs, printers, applications, and related infrastructure for manufacturing environments.
-
-## Overview
-
-ShopDB tracks and manages:
-- **Machines** - CNC equipment, CMMs, inspection systems, etc.
-- **PCs** - Shopfloor computers, engineering workstations
-- **Printers** - Network printers with Zabbix integration
-- **Applications** - Software deployed across the shop floor
-- **Knowledge Base** - Documentation and troubleshooting guides
-
-## Tech Stack
-
-**Backend:**
-- Python 3.x with Flask
-- SQLAlchemy ORM
-- MySQL 5.6+ database
-- JWT authentication
-- Plugin architecture for extensibility
-
-**Frontend:**
-- Vue 3 with Composition API
-- Vue Router for navigation
-- Pinia for state management
-- Vite build system
-
-## Project Structure
-
-```
-shopdb-flask/
-├── shopdb/                 # Flask application
-│   ├── core/
-│   │   ├── api/            # REST API endpoints
-│   │   ├── models/         # SQLAlchemy models
-│   │   ├── schemas/        # Validation schemas
-│   │   └── services/       # Business logic
-│   ├── plugins/            # Plugin system
-│   └── utils/              # Shared utilities
-├── frontend/               # Vue 3 application
-│   ├── src/
-│   │   ├── api/            # API client
-│   │   ├── components/     # Reusable components
-│   │   ├── views/          # Page components
-│   │   ├── router/         # Route definitions
-│   │   └── stores/         # Pinia stores
-│   └── public/             # Static assets
-├── plugins/                # Bundled and external plugins
-├── migrations/             # Alembic migration chain (flask db upgrade)
-├── scripts/                # Import and utility scripts
-└── tests/                  # Test suite
-```
-
-## Naming Conventions
-
-To maintain consistency with the legacy ShopDB database and codebase, the following naming standards apply:
-
-### Database
-
-- **Table names:** Lowercase, single word, no underscores or dashes
-  - Examples: `machines`, `pctypes`, `machinetypes`, `businessunits`
-- **Column names:** Lowercase, single word, no underscores or dashes
-  - Examples: `machineid`, `machinenumber`, `pctypeid`, `isactive`, `createddate`
-- **Foreign keys:** Referenced table name + `id`
-  - Examples: `locationid`, `vendorid`, `modelnumberid`, `pctypeid`
-- **Boolean columns:** Prefixed with `is` or `has`
-  - Examples: `isactive`, `isshopfloor`, `isvnc`, `iswinrm`, `islicenced`
-
-### Code
-
-- **Python variables:** Follow database naming where applicable (lowercase, no underscores for model fields)
-- **JavaScript variables:** camelCase for local variables, but match API field names from backend
-- **Vue components:** PascalCase for component names
-- **CSS classes:** Lowercase with dashes for multi-word classes
-
-### API
-
-- **Endpoints:** Lowercase, plural nouns
-  - Examples: `/api/machines`, `/api/pctypes`, `/api/locations`
-- **Query parameters:** Lowercase, single word
-  - Examples: `?type=pc`, `?locationid=5`, `?isactive=true`
-
-## Style Guidelines
-
-- No emojis in code, comments, documentation, or UI
-- Keep UI functional and professional
-- Dark theme is the default
-- Consistent table layouts across all list views
-
-## Setup
-
-### Prerequisites
-
-- Python 3.8+
-- Node.js 18+
-- MySQL 5.7+ (5.6 works with extra utf8mb4 config; see docs/DEPLOY.md)
-
-ShopDB Flask uses MySQL as the canonical database. SQLite is used only for the
-test suite (`TestingConfig` in `shopdb/config.py` points at an in-memory
-SQLite). Do not run dev or production against SQLite.
-
-### Distribution
-
-The application is distributed internally through the GE Aerospace Gitea. Clone
-it from there; there is no public package or image registry.
-
-### Fast path (Docker)
-
-The Docker image builds the Vue frontend and serves it from the API container,
-so a container deploy needs no separate Node build step.
-
-```bash
-cp .env.example .env
-# Edit .env: set SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, CORS_ORIGINS,
-# and the MYSQL_* passwords (see docs/CONFIG.md for every variable).
-
-docker compose up -d --build
-
-# Create the schema and seed the platform data (idempotent, safe to re-run):
-docker compose exec api flask db upgrade
-docker compose exec api flask seed permissions
-docker compose exec api flask seed settings
-docker compose exec api flask seed reference-data
-```
-
-Then browse to the site and complete the first-run setup wizard at `/setup`
-(it creates the first admin account and captures site identity). To create the
-admin headlessly instead of using the wizard:
-
-```bash
-docker compose exec api flask seed admin --username admin --email admin@facility.example.com
-```
-
-### Manual path (venv + Node)
-
-```bash
-# Backend
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-cp .env.example .env
-# Edit .env with your database credentials and secrets.
-
-flask db upgrade
-flask seed permissions
-flask seed settings
-flask seed reference-data
-flask run
-
-# Frontend (separate terminal)
-cd frontend
-npm install
-npm run dev          # dev server on :5173
-npm run build        # production build into frontend/dist (served by Flask)
-```
-
-Complete first-run setup at `/setup`, or run `flask seed admin` for a headless
-admin account.
-
-To import data from the legacy ShopDB MySQL database (one-time, see
-`migrations/DATA_MIGRATION_GUIDE.md`):
-
-```bash
-python scripts/import_from_mysql.py
-```
-
-For the full per-site deployment runbook see [docs/DEPLOY.md](docs/DEPLOY.md);
-for every environment variable and Setting key see [docs/CONFIG.md](docs/CONFIG.md).
-
-## Configuration
-
-Environment variables (`.env`):
-
-| Variable | Description |
-|----------|-------------|
-| `DATABASE_URL` | MySQL connection string |
-| `SECRET_KEY` | Flask secret key |
-| `JWT_SECRET_KEY` | JWT signing key |
-| `JWT_ACCESS_TOKEN_EXPIRES` | Access token TTL (seconds) |
-| `LOG_LEVEL` | Logging verbosity |
-
-## API Documentation
-
-The REST API follows standard conventions:
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/machines` | List machines (filterable by type) |
-| GET | `/api/machines/:id` | Get machine details |
-| POST | `/api/machines` | Create machine |
-| PUT | `/api/machines/:id` | Update machine |
-| DELETE | `/api/machines/:id` | Soft delete machine |
-
-Query parameters for list endpoints:
-- `page` - Page number (default: 1)
-- `per_page` - Items per page (default: 25)
-- `sort` - Sort field
-- `order` - Sort direction (asc/desc)
-- `search` - Search term
-- `type` - Filter by machine type (pc, printer, equipment)
-
-## Plugin System
-
-ShopDB supports plugins for extending functionality. See `CONTRIBUTING.md` for plugin development guidelines.
-
-The image bundles ten plugins; only the ones a site installs are loaded:
-
-- **computers** - Shopfloor PCs and workstations
-- **employees** - Employee directory
-- **equipment** - CNC, CMM, and inspection equipment
-- **knowledgebase** - Documentation and troubleshooting guides
-- **network** - Network devices
-- **notifications** - Shopfloor notifications and recognition feed
-- **printers** - Extended printer management with Zabbix integration
-- **slides** - TV/kiosk slideshows
-- **usb** - CMMC USB check-in/out tracking
-- **warranty** - Dell warranty lookups
-
-## Legacy Migration
-
-This project replicates functionality from the classic ASP/VBScript ShopDB site. Key mappings:
-
-| Legacy | Modern |
-|--------|--------|
-| ASP/VBScript | Flask/Python |
-| Classic ADO | SQLAlchemy |
-| Server-side HTML | Vue 3 SPA |
-| Session auth | JWT tokens |
-
-## License
-
-Internal use only.
+# ShopDB Flask
+
+A modern rewrite of the classic ASP/VBScript ShopDB application using Flask (Python) and Vue 3. This application manages shop floor machines, PCs, printers, applications, and related infrastructure for manufacturing environments.
+
+## Overview
+
+ShopDB tracks and manages:
+- **Machines** - CNC equipment, CMMs, inspection systems, etc.
+- **PCs** - Shopfloor computers, engineering workstations
+- **Printers** - Network printers with Zabbix supply integration
+- **Network devices** - Switches, routers, and the subnet browser
+- **Measuring tools** - Gage-lab instruments with calibration tracking
+- **Applications** - Software deployed across the shop floor, with per-PC install tracking
+- **Employees** - Directory, recognition and training notifications
+- **Warranties** - Coverage records with Dell warranty lookups
+- **USB devices** - CMMC check-in/out tracking
+- **Knowledge Base** - Documentation and troubleshooting guides
+- **GE-Enforce manifests** - Imaging/software manifest editing and fleet compliance
+
+## Tech Stack
+
+**Backend:**
+- Python 3.14 with Flask
+- SQLAlchemy ORM
+- MySQL 5.7+ database (5.6 works with extra utf8mb4 config; see the DEPLOY wiki page)
+- JWT authentication
+- Plugin architecture for extensibility
+
+**Frontend:**
+- Vue 3 with Composition API
+- Vue Router for navigation
+- Pinia for state management
+- Vite build system
+
+## Project Structure
+
+```
+shopdb-flask/
++-- shopdb/                 # Flask application
+|   +-- core/
+|   |   +-- api/            # REST API endpoints
+|   |   +-- models/         # SQLAlchemy models
+|   |   +-- schemas/        # Validation schemas
+|   |   `-- services/       # Business logic
+|   +-- plugins/            # Plugin system
+|   `-- utils/              # Shared utilities
++-- frontend/               # Vue 3 application
+|   +-- src/
+|   |   +-- api/            # API client
+|   |   +-- components/     # Reusable components
+|   |   +-- views/          # Page components
+|   |   +-- router/         # Route definitions
+|   |   `-- stores/         # Pinia stores
+|   `-- public/             # Static assets
++-- plugins/                # Bundled and external plugins
++-- migrations/             # Alembic migration chain (flask db upgrade)
++-- scripts/                # Import and utility scripts
+`-- tests/                  # Test suite
+```
+
+## Naming Conventions
+
+To maintain consistency with the legacy ShopDB database and codebase, the following naming standards apply:
+
+### Database
+
+- **Table names:** Lowercase, single word, no underscores or dashes
+  - Examples: `assets`, `computers`, `printers`, `businessunits`
+- **Column names:** Lowercase, single word, no underscores or dashes
+  - Examples: `assetid`, `assetnumber`, `hostname`, `isactive`, `createddate`
+- **Foreign keys:** Referenced table name + `id`
+  - Examples: `locationid`, `vendorid`, `modelnumberid`, `computertypeid`
+- **Boolean columns:** Prefixed with `is` or `has`
+  - Examples: `isactive`, `isshopfloor`, `iscolor`, `isdhcp`, `islicenced`
+
+### Code
+
+- **Python variables:** Follow database naming where applicable (lowercase, no underscores for model fields)
+- **JavaScript variables:** camelCase for local variables, but match API field names from backend
+- **Vue components:** PascalCase for component names
+- **CSS classes:** Lowercase with dashes for multi-word classes
+
+### API
+
+- **Endpoints:** Lowercase, plural nouns
+  - Examples: `/api/machines`, `/api/computers`, `/api/locations`
+- **Query parameters:** Lowercase, single word
+  - Examples: `?locationid=5`, `?isactive=true`, `?assettype=computer`
+
+## Style Guidelines
+
+- No emojis in code, comments, documentation, or UI
+- Keep UI functional and professional
+- Dark theme is the default
+- Consistent table layouts across all list views
+
+## Setup
+
+### Prerequisites
+
+- Python 3.14
+- Node.js 18+
+- MySQL 5.7+ (5.6 works with extra utf8mb4 config; see the DEPLOY wiki page)
+
+ShopDB Flask uses MySQL as the canonical database. SQLite is used only for the
+test suite (`TestingConfig` in `shopdb/config.py` points at an in-memory
+SQLite). Do not run dev or production against SQLite.
+
+### Distribution
+
+Source lives here. The Windows installer ships as a release asset rather than a
+file in the repository - it is around 240 MB, well past what a repository takes
+and well inside what a release asset does. There is no package or image
+registry; a site installs from that `.exe` or builds from source.
+
+### Fast path (Docker)
+
+The Docker image builds the Vue frontend and serves it from the API container,
+so a container deploy needs no separate Node build step.
+
+```bash
+cp .env.example .env
+# Edit .env: set SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, CORS_ORIGINS,
+# and the MYSQL_* passwords (see the CONFIG wiki page for every variable).
+
+docker compose up -d --build
+
+# Create the schema and seed the platform data (idempotent, safe to re-run):
+docker compose exec api flask db upgrade
+docker compose exec api flask seed permissions
+docker compose exec api flask seed settings
+docker compose exec api flask seed reference-data
+```
+
+Then browse to the site and complete the first-run setup wizard at `/setup`
+(it creates the first admin account and captures site identity). To create the
+admin headlessly instead of using the wizard:
+
+```bash
+docker compose exec api flask seed admin --username admin --email admin@facility.example.com
+```
+
+### Manual path (venv + Node)
+
+```bash
+# Backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+# Edit .env with your database credentials and secrets.
+
+export FLASK_APP=shopdb
+flask db upgrade
+flask plugin upgrade-all      # per-plugin schema (ADR-008)
+flask seed permissions
+flask seed settings
+flask seed reference-data
+flask run --port 5001         # MUST be 5001 - the frontend dev server proxies here
+
+# Frontend (separate terminal)
+cd frontend
+npm install
+npm run dev          # dev server on :5173
+npm run build        # production build into frontend/dist (served by Flask)
+```
+
+Complete first-run setup at `/setup`, or run `flask seed admin` for a headless
+admin account. The repo ships VS Code config in `.vscode/` (F5 debugs the
+backend; a "Dev site" task runs both servers). A fuller day-one walkthrough,
+including VS Code and troubleshooting, is the DEVELOPMENT-SETUP page in the
+project wiki.
+
+To import a site's legacy data, use the HTTP import surface: an admin API
+token plus the IMPORT-API page in the project wiki drive the whole migration
+through documented endpoints (`X-Import-Mode` preserves original timestamps).
+`scripts/site_imports/wjf/` is the reference site's loader, kept as a worked
+example of the whole sequence.
+
+### Which deployment route
+
+| Target | Use |
+|---|---|
+| **Windows Server + IIS** (how sister sites run) | **the INSTALL-WINDOWS page in the project wiki** - one installer `.exe`, offline, no manual IIS work. Day 2: the OPERATE-WINDOWS page in the project wiki |
+| Linux / Docker, air-gapped | the DEPLOY-AIRGAP page in the project wiki |
+| Linux / Docker, connected | the DEPLOY page in the project wiki |
+
+For every environment variable and Setting key see the CONFIG page in the project wiki.
+
+### What the Windows installer requires
+
+The installer checks all of this before it changes anything and refuses rather
+than half-installing.
+
+| | Minimum | Notes |
+|---|---|---|
+| Windows Server | **2019** (build 10.0.17763) | Ships **IIS 10.0**, which is therefore the earliest IIS supported. Server 2016 is also IIS 10.0 but falls below the build floor and is refused. |
+| Windows client (test boxes) | **10 22H2** (build 10.0.19045) or 11 | **Pro or higher** - Home has no IIS at all. |
+| Architecture | 64-bit | The payload is cp314 win_amd64. |
+| IIS Web Server role | installed beforehand | `Install-WindowsFeature -Name Web-Server -IncludeManagementTools`. Needs no internet. |
+| Free disk | 5 GB | Refused below this. 40 GB is comfortable once uploads and config backups accumulate. |
+| Database | bundled MySQL 8.4 LTS, or your own | Bring credentials if you use an existing server. |
+
+The binding constraint is the operating system rather than IIS: the payload is
+Python 3.14 plus HttpPlatformHandler and URL Rewrite, and the handler itself runs
+on older IIS. An older host is untested rather than known-broken.
+
+If you must deploy onto something older, the INSTALL-WINDOWS-IIS page in the project wiki
+is the manual procedure and has no OS gate - it even documents MySQL 5.6, which is
+that era of machine. The trade is stated there: it produces a server the
+installer will not subsequently upgrade.
+
+## Configuration
+
+Environment variables (`.env`):
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | MySQL connection string |
+| `SECRET_KEY` | Flask secret key |
+| `JWT_SECRET_KEY` | JWT signing key |
+| `JWT_ACCESS_TOKEN_EXPIRES` | Access token TTL (seconds) |
+| `LOG_LEVEL` | Logging verbosity |
+
+## API Documentation
+
+The REST API follows standard conventions:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/machines` | List machines (filterable by type) |
+| GET | `/api/machines/:id` | Get machine details |
+| POST | `/api/machines` | Create machine |
+| PUT | `/api/machines/:id` | Update machine |
+| DELETE | `/api/machines/:id` | Soft delete machine |
+
+Each asset plugin exposes the same CRUD pattern on its own prefix
+(`/api/computers`, `/api/printers`, `/api/network`, `/api/measuringtools`),
+and cross-cutting asset endpoints live under `/api/assets`.
+
+Query parameters for list endpoints:
+- `page` - Page number (default: 1)
+- `perpage` - Items per page
+- `sort` - Sort field
+- `dir` - Sort direction (asc/desc)
+- `search` - Search term
+- `assettype` - Filter by asset type (computer, printer, machine, networkdevice, measuringtool)
+
+## Where to start
+
+the START-HERE page in the project wiki routes by what you are here to do -
+standing up a site, deploying the shop-floor tools, writing a plugin,
+integrating with the API, or diagnosing something. On the published mirror the
+same page is the wiki's front door.
+
+## Plugin System
+
+ShopDB supports plugins for extending functionality. See `CONTRIBUTING.md` for plugin development guidelines.
+
+The image bundles these plugins; only the ones a site installs are loaded. The
+current count and each plugin's version and migration head are in
+the PROJECT-MAP page in the project wiki, which is generated:
+
+- **backups** - Machine configuration backups (NTLARS/DNC, CMM, part marker, UDC) with revision history and diffs
+- **computers** - Shopfloor PCs and workstations, collector fleet ingest
+- **employees** - Employee directory
+- **geenforce** - GE-Enforce imaging/software manifests and fleet compliance
+- **machines** - CNC, CMM, and other shop-floor machines
+- **measuringtools** - Gage-lab instruments with calibration tracking
+- **knowledgebase** - Documentation and troubleshooting guides
+- **network** - Network devices and subnets
+- **notifications** - Shopfloor notifications and recognition feed
+- **printedparts** - 3D-printed part catalogue, kiosk issue tracking and stock alerts
+- **printers** - Extended printer management with Zabbix integration
+- **slides** - TV/kiosk slideshows
+- **tools** - Tech Tools: barcode and QR generation laid out for real label stock
+- **usb** - CMMC USB check-in/out tracking
+- **warranty** - Warranty records with Dell lookups
+
+## Legacy Migration
+
+This project replicates functionality from the classic ASP/VBScript ShopDB site. Key mappings:
+
+| Legacy | Modern |
+|--------|--------|
+| ASP/VBScript | Flask/Python |
+| Classic ADO | SQLAlchemy |
+| Server-side HTML | Vue 3 SPA |
+| Session auth | JWT tokens |
+
+## License
+
+Internal use only.

agent/.gitignore

@@ -0,0 +1,12 @@
+# .NET build output - never tracked; produced by dotnet build/publish.
+bin/
+obj/
+publish/
+
+# Application-delivery development builds. Held in reserve for extensive
+# testing; never shipped to a site publish folder or tracked.
+dev-bin/
+
+# Local publish/staging scratch and command-output captures.
+_stage/
+*.user

agent/README.md

@@ -0,0 +1,177 @@
+# ShopDB Endpoint Agent
+
+A Windows telemetry agent that reports endpoint state to a ShopDB server's
+`endpoints` plugin. It runs as a Windows service in production and as a console
+app for development and testing.
+
+## Projects
+
+- `ShopDbEndpointAgent.Core` - contracts, config, logging, collection, and the
+  resilient collector HTTP client. No host concerns; unit-testable.
+- `ShopDbEndpointAgent` - the service host (generic host + Windows service
+  lifetime). Composes Core through DI. This is the telemetry runtime.
+- `ShopDbEndpointAgent.Tray` - interactive user-session tray app: a system-tray
+  icon with "Send Status now" (on-demand report) and the 5-click issue reporter
+  (ServiceNow flow is still a scaffold). Separate process from the service,
+  because a SYSTEM service cannot draw a tray icon in a user session.
+
+## Configuration
+
+Runtime config is layered. Non-secret defaults live in `appsettings.json`
+(shipped with the build). The collector key and base URL are provisioned out of
+band in the registry and win over `appsettings.json`, so a distributed build
+never carries the secret and the site can rotate the key without a rebuild.
+
+### Registry (production)
+
+Create these values under `HKLM\SOFTWARE\GE\ShopDB` (64-bit view):
+
+| Value          | Type   | Meaning                                          |
+|----------------|--------|--------------------------------------------------|
+| `BaseUrl`      | String | `https://shopdb.example.net` (server root)       |
+| `CollectorKey` | String | The endpoint agent key from Settings -> Endpoints -> Key management |
+
+Example (elevated PowerShell):
+
+```
+New-Item -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Force | Out-Null
+Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'BaseUrl' -Value 'https://shopdb.example.net'
+Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'CollectorKey' -Value '<paste the generated key>'
+```
+
+### appsettings.json (all environments)
+
+| Key               | Default     | Meaning                                        |
+|-------------------|-------------|------------------------------------------------|
+| `baseurl`         | ""          | Dev fallback for the server root (registry wins). |
+| `apikey`          | placeholder | Dev fallback for the collector key (registry wins). |
+| `cadenceseconds`  | 900         | Report interval (15 min).                      |
+| `jitterseconds`   | 60          | Random +/- spread on the interval (anti-herd). |
+| `adoptonfirstrun` | true        | Send `adopt=true` on first contact only.       |
+| `utilitiespath`   | ""          | Directory of site PowerShell "agent utilities". |
+| `logpath`         | ""          | Override the rolling log directory.            |
+
+For a dev box, set `baseurl` and `apikey` here and skip the registry.
+
+## Running
+
+Console (dev), one report then exit:
+
+```
+dotnet run --project ShopDbEndpointAgent -- --once
+```
+
+Console (dev), continuous cadence loop:
+
+```
+dotnet run --project ShopDbEndpointAgent -- --console
+```
+
+## Install as a Windows service
+
+Publish self-contained, then register with `sc.exe` (elevated):
+
+```
+dotnet publish ShopDbEndpointAgent -c Release -r win-x64 --self-contained -o C:\ProgramData\ShopDB\EndpointAgent\bin
+sc.exe create "ShopDBEndpointAgent" binPath= "C:\ProgramData\ShopDB\EndpointAgent\bin\shopdb-endpoint-agent.exe" start= auto DisplayName= "ShopDB Endpoint Agent"
+sc.exe description "ShopDBEndpointAgent" "Reports endpoint telemetry to ShopDB."
+sc.exe start "ShopDBEndpointAgent"
+```
+
+The service runs as LocalSystem by default, which it needs to read the Security
+event channel and system WMI.
+
+## Tray app (system-tray icon)
+
+The tray is a per-user process, not a service, so it starts at sign-in rather
+than under `sc.exe`. The generated `install.ps1` handles it: it copies
+`shopdb-endpoint-tray.exe` next to the agent and registers a machine-wide logon
+autostart (`HKLM\Software\Microsoft\Windows\CurrentVersion\Run\ShopDbEndpointTray`,
+64-bit view). The installer deliberately does NOT start the tray itself: it runs
+elevated, so any process it starts inherits an admin token, and mapped drives are
+per logon token - an elevated tray probes the wrong drive table. The Run key only
+fires at logon, which would leave the tray dead until sign-out on a machine
+someone is already using, so the installer also registers a transient
+`ShopDB tray first launch` scheduled task under `S-1-5-32-545` at `RunLevel
+Limited`, runs it once, and unregisters it. That task is the only mechanism that
+can reach into an existing interactive session without carrying the installer's
+token. Pass `-NoTray` for a headless, service-only install.
+
+User-context collection does not depend on the tray. The installer registers a
+`ShopDB user-context probe` scheduled task against the Users group at
+`RunLevel Limited`, which runs `shopdbagent.exe --collect-usercontext` in the
+operator's own session at logon and every 30 minutes.
+
+Right-click the tray icon for:
+
+- `Send Status now` - reports this PC to ShopDB immediately so the monitor page
+  refreshes without waiting for the next cadence tick. It shells out to
+  `shopdbagent.exe --once`, reusing the exact production collection path; the
+  tray holds no collector key. A balloon tip reflects success or failure (on
+  failure, see the rolling agent log).
+- `Report an issue...` - the ServiceNow ticket flow (scaffold; submission path
+  is an open decision).
+
+A desktop shortcut to `shopdb-endpoint-tray.exe` can be added later for an
+explicitly launchable ServiceNow surface.
+
+## WebUI command execution model (security context)
+
+The WebUI can send an endpoint an allowlisted command (server source of truth:
+`plugins/endpoints/commands.py`; agent handler: `CommandExecutor`). The agent
+service runs as LocalSystem, but not every command runs in that context. The
+launch context is chosen per action so processes surface to the operator while
+privileged operations keep the token they need:
+
+- Generic `process_start` (for example DncMain, UDC) launches into the ACTIVE
+  CONSOLE USER's session at medium integrity, so the app is visible on the
+  operator's desktop. CyberArk/EPM brokers any elevation afterward.
+- Generic `process_stop` / `process_status` run as SYSTEM (kill and probe).
+- `service_start` / `service_stop` / `service_status` run as SYSTEM, because
+  service control requires the admin/SYSTEM token.
+- `mtconnect_start` / `mtconnect_stop` / `mtconnect_status` all run as SYSTEM,
+  because MTConnect is the "UDC MTConnect Agent" Windows service and service
+  control requires the admin/SYSTEM token. `mtconnect_start` runs `install.bat`
+  (`Agent.exe install`) to install or repair the service, then ensures it is
+  running; `mtconnect_stop` stops the service; `mtconnect_status` queries it.
+  `run.bat` (`agent.exe run agent.cfg`) is a foreground TESTING launcher and is
+  deliberately NOT used by the agent.
+- `system_restart` runs as SYSTEM and reboots the machine immediately via
+  `shutdown.exe /r /t 0` (no grace timer). It is a fixed action with no target,
+  gated server-side by the dedicated `endpoints.restart` permission on top of
+  `endpoints.command`, and fronted by a WebUI confirmation gate.
+
+Do not route MTConnect through the generic `process_start` user-session path or
+service control breaks. MTConnect is intentionally absent from the
+`process_start` launch map for the same reason; the fixed `mtconnect_*` handler
+owns it.
+
+Behavior note for redeploys: the MTConnect service-control model is a runtime
+change, so the agent must be rebuilt and redeployed for it to take effect.
+Server-side command/allowlist/RBAC changes are picked up by the container
+rebuild; rebuild and redeploy the agent whenever the runtime launch/control
+logic itself changes.
+
+## Diagnostics
+
+- Rolling file log: `%ProgramData%\ShopDB\EndpointAgent\logs\YYYYMMDD-agent.log`
+  (14-day retention).
+- Windows Event Log: agent runtime failures and unhandled exceptions are written
+  to the `Application` log under source `ShopDB Endpoint Agent`. The source is
+  created on first elevated run (or by the installer). Filter Event Viewer by
+  that source to see agent/system interop failures.
+
+## Agent utilities (PowerShell seam)
+
+If `utilitiespath` points at a directory, the runtime runs each `*.ps1` there
+per report, parses its JSON stdout, and merges the result into the report. This
+is the seam the future server-side "Agent configuration" settings page uses to
+push site-authored collectors down. Scripts must be code-signed and
+allow-listed before this is enabled in the field (rollout concern).
+
+## Logging extensibility
+
+All runtime code logs through `Microsoft.Extensions.Logging` (`ILogger`). Adding
+a sink later (a ShopDB HTTP sink, Seq, syslog) is a host-builder change in
+`Program.cs::ConfigureLogging` with no changes to the worker, collector, or
+client.

agent/ShopDbAdoptionTool/Program.cs

@@ -0,0 +1,358 @@
+using System.Management;
+using System.Net.Http.Json;
+using System.Net.NetworkInformation;
+using System.Runtime.Versioning;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ShopDbAdoptionTool;
+
+// ShopDB adoption tool (SPIKE). A one-shot, agentless enrollment client: it uses
+// only the endpoints collector key to create a ShopDB PC (Computer) + Endpoint
+// entry via the existing collector adopt path, then exits. It is NOT the endpoint
+// agent - it installs nothing, runs no service, and reports no ongoing telemetry.
+// For sites that want an inventory entry without running the full agent.
+//
+// Configuration comes from adopt.config.json beside the exe, or from
+// --baseurl / --collectorkey / --hostname arguments (arguments win). The
+// collector key is never written to disk by this tool; it is read from the
+// config the operator generated and placed next to the exe.
+[SupportedOSPlatform("windows")]
+internal static class Program
+{
+    private const string ReportPath = "/api/collector/endpoints";
+
+    private static async Task<int> Main(string[] args)
+    {
+        try
+        {
+            var config = LoadConfig(args);
+            if (string.IsNullOrWhiteSpace(config.BaseUrl) ||
+                string.IsNullOrWhiteSpace(config.CollectorKey))
+            {
+                Console.Error.WriteLine(
+                    "Missing baseurl or collectorkey. Provide adopt.config.json next to the "
+                    + "exe or pass --baseurl and --collectorkey.");
+                return 2;
+            }
+
+            // The app manifest forces UAC elevation, so this is a belt-and-braces
+            // guard for edge cases (for example a stripped manifest). Full WMI and
+            // the machine Uninstall hives need admin, or collection is partial.
+            if (!IsElevated())
+            {
+                Console.Error.WriteLine(
+                    "This tool must run as administrator so hardware and installed-"
+                    + "software collection succeeds. Right-click and Run as administrator.");
+                return 3;
+            }
+
+            var payload = BuildPayload(config);
+            Console.WriteLine($"Adopting '{payload.Hostname}' into {config.BaseUrl} ...");
+            Console.WriteLine(
+                $"Collected {payload.Applications?.Length ?? 0} installed applications.");
+
+            using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
+            client.DefaultRequestHeaders.Add("X-API-Key", config.CollectorKey);
+
+            var url = config.BaseUrl!.TrimEnd('/') + ReportPath;
+            using var response = await client.PostAsJsonAsync(url, payload);
+            var body = await response.Content.ReadAsStringAsync();
+
+            if (!response.IsSuccessStatusCode)
+            {
+                Console.Error.WriteLine(
+                    $"Adoption failed: HTTP {(int)response.StatusCode}. {body}");
+                return 1;
+            }
+
+            Console.WriteLine("Adoption succeeded.");
+            Console.WriteLine(body);
+            return 0;
+        }
+        catch (Exception error)
+        {
+            Console.Error.WriteLine($"Adoption error: {error.Message}");
+            return 1;
+        }
+    }
+
+    private static AdoptConfig LoadConfig(string[] args)
+    {
+        var config = new AdoptConfig();
+
+        var configPath = Path.Combine(AppContext.BaseDirectory, "adopt.config.json");
+        if (File.Exists(configPath))
+        {
+            var fromFile = JsonSerializer.Deserialize<AdoptConfig>(
+                File.ReadAllText(configPath),
+                new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
+            if (fromFile is not null)
+                config = fromFile;
+        }
+
+        for (var i = 0; i < args.Length - 1; i++)
+        {
+            var value = args[i + 1];
+            switch (args[i].ToLowerInvariant())
+            {
+                case "--baseurl":
+                    config.BaseUrl = value;
+                    break;
+                case "--collectorkey":
+                    config.CollectorKey = value;
+                    break;
+                case "--hostname":
+                    config.Hostname = value;
+                    break;
+            }
+        }
+
+        return config;
+    }
+
+    private static AdoptPayload BuildPayload(AdoptConfig config)
+    {
+        var hostname = !string.IsNullOrWhiteSpace(config.Hostname)
+            ? config.Hostname!
+            : Environment.MachineName;
+
+        return new AdoptPayload
+        {
+            Hostname = hostname,
+            Adopt = true,
+            LoggedInUser = GetLoggedInUser(),
+            SerialNumber = WmiFirst("SELECT SerialNumber FROM Win32_BIOS", "SerialNumber"),
+            PcType = WmiFirst("SELECT Model FROM Win32_ComputerSystem", "Model"),
+            VendorName = WmiFirst("SELECT Manufacturer FROM Win32_ComputerSystem", "Manufacturer"),
+            ModelNumber = GetModelNumber(),
+            OsName = WmiFirst("SELECT Caption FROM Win32_OperatingSystem", "Caption"),
+            IpAddress = ResolveIpAddress(),
+            LastBootTime = GetLastBootTime(),
+            Applications = GetApplications(),
+            AgentVersion = "adopt-0.1.0",
+        };
+    }
+
+    // Mirrors the endpoint agent: prefer the WMI logged-on user, fall back to
+    // the process identity so the field is never blank.
+    private static string GetLoggedInUser()
+    {
+        var user = WmiFirst("SELECT UserName FROM Win32_ComputerSystem", "UserName");
+        return string.IsNullOrWhiteSpace(user)
+            ? $"{Environment.UserDomainName}\\{Environment.UserName}"
+            : user;
+    }
+
+    // Human-readable model first (what pctype classifies on); SystemSKUNumber is
+    // an OEM SKU code, used only when Model is blank. Matches EndpointCollector.
+    private static string? GetModelNumber()
+    {
+        var model = WmiFirst("SELECT Model FROM Win32_ComputerSystem", "Model");
+        if (!string.IsNullOrWhiteSpace(model))
+            return model;
+        return WmiFirst("SELECT SystemSKUNumber FROM Win32_ComputerSystem",
+            "SystemSKUNumber");
+    }
+
+    private static DateTimeOffset? GetLastBootTime()
+    {
+        var raw = WmiFirst("SELECT LastBootUpTime FROM Win32_OperatingSystem",
+            "LastBootUpTime");
+        if (string.IsNullOrWhiteSpace(raw))
+            return null;
+        try
+        {
+            return ManagementDateTimeConverter.ToDateTime(raw).ToUniversalTime();
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    // Run one WMI query and return the first row's column as a trimmed string,
+    // or null. Best-effort: WMI failures never abort adoption.
+    private static string? WmiFirst(string query, string column)
+    {
+        try
+        {
+            using var searcher = new ManagementObjectSearcher(query);
+            foreach (var item in searcher.Get())
+            {
+                var value = item[column]?.ToString()?.Trim();
+                if (!string.IsNullOrWhiteSpace(value))
+                    return value;
+            }
+        }
+        catch
+        {
+            // Best-effort: the server treats every hardware field as optional.
+        }
+        return null;
+    }
+
+    // Installed-software SBOM. Mirrors the endpoint agent exactly: enumerate both
+    // Uninstall registry hives (64-bit and WOW6432Node), keep entries with a
+    // DisplayName, de-dupe on name+version, and emit {displayname, displayversion,
+    // publisher}. Requires admin to read the machine hives reliably (see the
+    // app manifest). Never throws out to the caller.
+    private static object[] GetApplications()
+    {
+        const string uninstall64 =
+            @"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall";
+        const string uninstall32 =
+            @"SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall";
+
+        var result = new List<object>();
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        CollectUninstallHive(uninstall64, result, seen);
+        CollectUninstallHive(uninstall32, result, seen);
+        return result.ToArray();
+    }
+
+    private static void CollectUninstallHive(string subKey, List<object> result,
+        HashSet<string> seen)
+    {
+        try
+        {
+            using var machine = Microsoft.Win32.RegistryKey.OpenBaseKey(
+                Microsoft.Win32.RegistryHive.LocalMachine,
+                Microsoft.Win32.RegistryView.Default);
+            using var uninstall = machine.OpenSubKey(subKey);
+            if (uninstall is null)
+                return;
+
+            foreach (var name in uninstall.GetSubKeyNames())
+            {
+                try
+                {
+                    using var entry = uninstall.OpenSubKey(name);
+                    var displayName = entry?.GetValue("DisplayName")?.ToString()?.Trim();
+                    if (string.IsNullOrWhiteSpace(displayName))
+                        continue;
+
+                    var displayVersion =
+                        entry?.GetValue("DisplayVersion")?.ToString()?.Trim() ?? "";
+                    var publisher =
+                        entry?.GetValue("Publisher")?.ToString()?.Trim() ?? "";
+
+                    if (!seen.Add(displayName + "\u0000" + displayVersion))
+                        continue;
+
+                    result.Add(new
+                    {
+                        displayname = displayName,
+                        displayversion = displayVersion,
+                        publisher,
+                    });
+                }
+                catch
+                {
+                    // Skip unreadable entries; keep collecting the rest.
+                }
+            }
+        }
+        catch
+        {
+            // Skip an unreadable hive; the other hive may still return data.
+        }
+    }
+
+    private static string? ResolveIpAddress()
+    {
+        try
+        {
+            foreach (var network in NetworkInterface.GetAllNetworkInterfaces())
+            {
+                if (network.OperationalStatus != OperationalStatus.Up)
+                    continue;
+                if (network.NetworkInterfaceType == NetworkInterfaceType.Loopback)
+                    continue;
+                foreach (var address in network.GetIPProperties().UnicastAddresses)
+                {
+                    if (address.Address.AddressFamily ==
+                        System.Net.Sockets.AddressFamily.InterNetwork)
+                        return address.Address.ToString();
+                }
+            }
+        }
+        catch
+        {
+            // Best-effort: the server treats ipaddress as optional.
+        }
+        return null;
+    }
+
+    // True when the process runs with the Administrators group in its token.
+    private static bool IsElevated()
+    {
+        try
+        {
+            using var identity = System.Security.Principal.WindowsIdentity.GetCurrent();
+            var principal = new System.Security.Principal.WindowsPrincipal(identity);
+            return principal.IsInRole(
+                System.Security.Principal.WindowsBuiltInRole.Administrator);
+        }
+        catch
+        {
+            return false;
+        }
+    }
+}
+
+internal sealed class AdoptConfig
+{
+    [JsonPropertyName("baseurl")]
+    public string? BaseUrl { get; set; }
+
+    [JsonPropertyName("collectorkey")]
+    public string? CollectorKey { get; set; }
+
+    [JsonPropertyName("hostname")]
+    public string? Hostname { get; set; }
+}
+
+// Payload keys mirror the endpoints collector adopt schema exactly (lowercase,
+// concatenated) so the server stores them without translation. This tool sends
+// the adopt identity plus the hardware and SBOM subset the endpoint agent
+// collects; ongoing health telemetry (cpu, services, events) is intentionally
+// absent because this is agentless enrollment, not the agent.
+internal sealed class AdoptPayload
+{
+    [JsonPropertyName("hostname")]
+    public string Hostname { get; set; } = "";
+
+    [JsonPropertyName("adopt")]
+    public bool Adopt { get; set; }
+
+    [JsonPropertyName("loggedinuser")]
+    public string? LoggedInUser { get; set; }
+
+    [JsonPropertyName("serialnumber")]
+    public string? SerialNumber { get; set; }
+
+    [JsonPropertyName("pctype")]
+    public string? PcType { get; set; }
+
+    [JsonPropertyName("vendorname")]
+    public string? VendorName { get; set; }
+
+    [JsonPropertyName("modelnumber")]
+    public string? ModelNumber { get; set; }
+
+    [JsonPropertyName("osname")]
+    public string? OsName { get; set; }
+
+    [JsonPropertyName("ipaddress")]
+    public string? IpAddress { get; set; }
+
+    [JsonPropertyName("lastboottime")]
+    public DateTimeOffset? LastBootTime { get; set; }
+
+    [JsonPropertyName("applications")]
+    public object[]? Applications { get; set; }
+
+    [JsonPropertyName("agentversion")]
+    public string? AgentVersion { get; set; }
+}

agent/ShopDbAdoptionTool/ShopDbAdoptionTool.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+	<OutputType>Exe</OutputType>
+	<TargetFramework>net8.0-windows</TargetFramework>
+	<ImplicitUsings>enable</ImplicitUsings>
+	<Nullable>enable</Nullable>
+	<RootNamespace>ShopDbAdoptionTool</RootNamespace>
+	<AssemblyName>shopdb-adopt</AssemblyName>
+	<!-- 0.1.0 (SPIKE): one-shot, agentless enrollment. Uses only the endpoints
+		 collector key to create a ShopDB PC (Computer) + Endpoint entry via the
+		 existing POST /api/collector/endpoints adopt path. Deliberately NOT the
+		 endpoint agent: no service, no polling, no delivery. For sites that want
+		 an inventory entry without running the full agent. -->
+	<Version>0.1.0</Version>
+	<InvariantGlobalization>true</InvariantGlobalization>
+	<RuntimeIdentifier>win-x64</RuntimeIdentifier>
+	<SelfContained>true</SelfContained>
+	<PublishSingleFile>true</PublishSingleFile>
+	<IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
+	<EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
+	<DebugType>none</DebugType>
+	<ApplicationManifest>app.manifest</ApplicationManifest>
+  </PropertyGroup>
+
+  <ItemGroup>
+	<PackageReference Include="System.Management" Version="8.0.0" />
+  </ItemGroup>
+
+</Project>

agent/ShopDbAdoptionTool/app.manifest

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <assemblyIdentity version="0.1.0.0" name="ShopDbAdoptionTool.app" />
+  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+	<security>
+	  <requestedPrivileges xmlns="urn:schemas-microsoft-com:asm.v2">
+		<!-- Adoption reads the machine Uninstall hives and full WMI hardware for
+			 the SBOM and hardware collection. Require elevation so the run is not
+			 silently partial when launched from a standard user token. -->
+		<requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
+	  </requestedPrivileges>
+	</security>
+  </trustInfo>
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+	<application>
+	  <!-- Windows 10 and Windows 11 -->
+	  <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
+	</application>
+  </compatibility>
+</assembly>

agent/ShopDbEndpointAgent.Core/AgentConfig.cs

@@ -0,0 +1,235 @@
+using System.Text.Json.Serialization;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Runtime configuration for the agent. Non-secret values come from
+// appsettings.json; the collector key and base URL are provisioned out of band
+// in the registry (HKLM:\SOFTWARE\GE\ShopDB) and layered on top - see
+// RegistryConfigProvider. The registry wins so a distributed appsettings.json
+// never carries the secret and the site can rotate the key without a rebuild.
+public sealed class AgentConfig
+{
+    [JsonPropertyName("baseurl")] public string BaseUrl { get; set; } = "";
+    [JsonPropertyName("apikey")] public string ApiKey { get; set; } = "";
+    [JsonPropertyName("cadenceseconds")] public int CadenceSeconds { get; set; } = 900;
+
+    // Jitter spreads a fleet's reports so they do not arrive in lockstep
+    // (thundering herd). Actual delay = cadence +/- up to jitterseconds.
+    [JsonPropertyName("jitterseconds")] public int JitterSeconds { get; set; } = 60;
+
+    [JsonPropertyName("adoptonfirstrun")] public bool AdoptOnFirstRun { get; set; } = true;
+
+    // Directory holding site-provided PowerShell "agent utilities" the runtime
+    // may invoke through the documented collection seam. Empty = none loaded.
+    [JsonPropertyName("utilitiespath")] public string UtilitiesPath { get; set; } = "";
+
+    // Absolute path for the rolling diagnostics log. Empty = the default under
+    // %ProgramData%\ShopDB\EndpointAgent\logs.
+    [JsonPropertyName("logpath")] public string LogPath { get; set; } = "";
+
+    // What this endpoint watches. Shipped in appsettings.json (non-secret) so a
+    // site can retarget monitors without a rebuild. Processes are interactive
+    // apps watched by image name; services are Windows services watched by their
+    // service key name. Empty lists = nothing watched.
+    [JsonPropertyName("monitors")] public MonitorConfig Monitors { get; set; } = new();
+
+    // Per-image launchable paths for the generic process_start action. The wire
+    // historically never carried a path; now a server-provisioned monitor MAY
+    // carry one, but the agent only accepts it after LaunchPathPolicy validates
+    // it against ApprovedLaunchRoots (see below). Start otherwise sends only the
+    // image name and the agent maps it here to a known-good executable
+    // (or a .bat launcher). Anything not in the resolved map fails closed. A
+    // site overrides or extends the shipped defaults in appsettings.json without
+    // a rebuild. Keyed by process image name (case-insensitive, .exe optional).
+    [JsonPropertyName("launchpaths")]
+    public Dictionary<string, string> LaunchPaths { get; set; } = new();
+
+    // Approved root directories a server-provisioned launch path must sit under
+    // before the agent will honor it. Empty = fall back to LaunchPathPolicy's
+    // shipped org defaults (Program Files roots). A site (or the future Site
+    // Agent Configuration tool) can widen or narrow this without a rebuild.
+    [JsonPropertyName("approvedlaunchroots")]
+    public List<string> ApprovedLaunchRoots { get; set; } = new();
+
+    // Shipped defaults for the org's common shop-floor apps. A site's
+    // appsettings.json LaunchPaths entries win over these on a per-image basis.
+    // MTConnect is intentionally absent here: it is a Windows service controlled
+    // by the fixed mtconnect_* handler (install.bat + service control), not the
+    // generic process_start path. eDNC and UDC launch their runtime executables
+    // directly.
+    public static readonly IReadOnlyDictionary<string, string> DefaultLaunchPaths =
+        new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["DncMain.exe"] = @"C:\Program Files (x86)\Dnc\bin\DncMain.exe",
+            ["UDC.exe"] = @"C:\Program Files\UDC\UDC.exe",
+        };
+
+    // The effective launch map: shipped defaults overlaid with appsettings.json
+    // entries (site wins). Keys are normalized to bare image names so a lookup
+    // tolerates 'DncMain' or 'DncMain.exe'.
+    public IReadOnlyDictionary<string, string> ResolveLaunchPaths()
+    {
+        var resolved = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var pair in DefaultLaunchPaths)
+            resolved[NormalizeImage(pair.Key)] = pair.Value;
+        foreach (var pair in LaunchPaths)
+        {
+            if (string.IsNullOrWhiteSpace(pair.Key) || string.IsNullOrWhiteSpace(pair.Value))
+                continue;
+            resolved[NormalizeImage(pair.Key)] = pair.Value;
+        }
+        return resolved;
+    }
+
+    private static string NormalizeImage(string image)
+    {
+        var bare = (image ?? "").Trim();
+        if (bare.EndsWith(".exe", StringComparison.OrdinalIgnoreCase))
+            bare = bare[..^4];
+        return bare;
+    }
+
+    // REMOVED DELIBERATELY - DO NOT REINTRODUCE: 'scriptpaths' / ScriptPaths.
+    //
+    // This used to be a per-name map of PRE-STAGED scripts on the endpoint
+    // (typically under C:\ProgramData\ShopDB\EndpointAgent\scripts), which
+    // run_script would look up by name and execute. It was superseded by
+    // server-hosted delivery and left behind as dead config: nothing read the
+    // map, so it was an execution path that appeared supported but was not.
+    //
+    // It is gone rather than merely unused because reviving it is a security
+    // regression, and dead code invites revival. That model had NO integrity
+    // check - no digest, no provenance - so whoever could write into the staging
+    // directory chose what the agent ran as SYSTEM. ProgramData is world-
+    // writable by default unless the tree is explicitly tightened, which made
+    // the gate "is this name in appsettings.json", not "is this content
+    // trusted".
+    //
+    // The supported path is run_script with a server-issued delivery descriptor:
+    // the body is fetched from ShopDB over the collector credential and verified
+    // against a server-pinned SHA-256 before it executes, so the content is
+    // authenticated and the action is attributable in the command log. If you
+    // need a script to run on an endpoint, publish it server-side and send it
+    // through that path. If you need to trigger something already installed on
+    // the box, use scheduledtask_run, which is far narrower.
+
+    // Approved scheduled task paths for the scheduledtask_run action. The wire
+    // carries a free-text task path so the WebUI can expose it as a single
+    // field; ScheduledTaskPolicy validates it against this list and fails closed
+    // when it does not match. An entry matches that exact task path, or acts as
+    // a folder prefix for anything beneath it.
+    //
+    // Empty means "use the shipped Corporate Tools defaults"
+    // (ScheduledTaskPolicy.DefaultApprovedTaskPaths). Setting it REPLACES those
+    // defaults, so a site can narrow the set as well as widen it without an
+    // agent rebuild. Keep it tight: every entry here is something an operator
+    // holding endpoints.deploy can start, in whatever context the task itself
+    // registered.
+    [JsonPropertyName("approvedtaskpaths")]
+    public List<string> ApprovedTaskPaths { get; set; } = new();
+
+    public bool IsUsable()
+        => !string.IsNullOrWhiteSpace(BaseUrl)
+           && !string.IsNullOrWhiteSpace(ApiKey)
+           && ApiKey != "REPLACE_WITH_COLLECTOR_KEY";
+
+    // Validates the BaseUrl scheme before any request is made. A plaintext
+    // http:// URL aimed at a real (non-loopback) server is the classic
+    // misconfiguration that hits the TLS port and used to spin the command
+    // long-poll into a storm; refusing to start on it turns a silent, noisy
+    // runtime failure into a single clear startup error. Loopback over http is
+    // still allowed so a developer running the API on plain http locally works.
+    // Returns a human-readable problem, or null when the BaseUrl is acceptable.
+    public string? BaseUrlProblem()
+    {
+        if (string.IsNullOrWhiteSpace(BaseUrl))
+            return null;
+
+        if (!Uri.TryCreate(BaseUrl.Trim(), UriKind.Absolute, out var uri))
+            return $"BaseUrl '{BaseUrl}' is not a valid absolute URL.";
+
+        if (uri.Scheme == Uri.UriSchemeHttps)
+            return null;
+
+        if (uri.Scheme == Uri.UriSchemeHttp)
+        {
+            if (uri.IsLoopback)
+                return null;
+            return $"BaseUrl '{BaseUrl}' uses plaintext http:// against a " +
+                "non-loopback host. The server requires https://; an http:// " +
+                "URL hits the TLS port and fails every request. Reprovision " +
+                "BaseUrl in HKLM\\SOFTWARE\\GE\\ShopDB (or appsettings.json) " +
+                "with an https:// URL.";
+        }
+
+        return $"BaseUrl '{BaseUrl}' uses unsupported scheme '{uri.Scheme}'. " +
+            "Use https:// (or http:// only for a loopback dev server).";
+    }
+}
+
+// Watched targets for this endpoint. Both lists carry entries with a wire name
+// (process image name or Windows service key name) and an optional friendly app
+// label the server/UI can show (for example "eDNC" for dncMain.exe).
+public sealed class MonitorConfig
+{
+    [JsonPropertyName("processes")] public MonitorTarget[] Processes { get; set; }
+        = Array.Empty<MonitorTarget>();
+
+    [JsonPropertyName("services")] public MonitorTarget[] Services { get; set; }
+        = Array.Empty<MonitorTarget>();
+
+    // Union the local (appsettings.json) watch list with the server-resolved one,
+    // keyed case-insensitively by wire name so a target watched both locally and
+    // by policy is not enumerated twice. Server entries win on the label (App) so
+    // a policy display name overrides a stale local one, but a local-only target
+    // is preserved - the server list augments, it does not replace. Nulls on
+    // either side degrade to the other, which is what keeps monitoring alive when
+    // a fetch fails.
+    public static MonitorConfig Merge(MonitorConfig? local, ResolvedMonitors? server)
+    {
+        return new MonitorConfig
+        {
+            Processes = MergeTargets(local?.Processes, server?.Processes),
+            Services = MergeTargets(local?.Services, server?.Services),
+        };
+    }
+
+    private static MonitorTarget[] MergeTargets(
+        MonitorTarget[]? local, MonitorTarget[]? server)
+    {
+        var byName = new Dictionary<string, MonitorTarget>(
+            StringComparer.OrdinalIgnoreCase);
+        foreach (var target in local ?? Array.Empty<MonitorTarget>())
+        {
+            if (string.IsNullOrWhiteSpace(target?.Name))
+                continue;
+            byName[target.Name.Trim()] = target;
+        }
+        foreach (var target in server ?? Array.Empty<MonitorTarget>())
+        {
+            if (string.IsNullOrWhiteSpace(target?.Name))
+                continue;
+            byName[target.Name.Trim()] = target;
+        }
+        return byName.Values.ToArray();
+    }
+}
+
+public sealed class MonitorTarget
+{
+    // Process image name (for example "udc.exe") or Windows service key name
+    // (for example "MTConnectAgent"). Matched case-insensitively.
+    [JsonPropertyName("name")] public string Name { get; set; } = "";
+
+    // Human-facing application label, optional. Falls back to Name when empty.
+    [JsonPropertyName("app")] public string App { get; set; } = "";
+
+    // Optional server-provisioned launch path for a process monitor. Only set on
+    // process targets that a site leader configured a path for. The agent NEVER
+    // launches this blindly: LaunchPathPolicy validates it against an approved-
+    // root allowlist first, and a local appsettings.json launchpaths entry for
+    // the same image still wins. Null/empty means "no server path" - the agent
+    // falls back to its local launch map, and process_start fails closed when
+    // neither yields a validated path.
+    [JsonPropertyName("launchpath")] public string? LaunchPath { get; set; }
+}

agent/ShopDbEndpointAgent.Core/AgentConfigProvider.cs

@@ -0,0 +1,110 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Win32;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Builds the effective AgentConfig by layering two sources:
+//   1. appsettings.json  - non-secret runtime defaults, shipped with the build.
+//   2. HKLM\SOFTWARE\GE\ShopDB  - the collector key and base URL, provisioned
+//      out of band (Intune/DSC/GE-Enforce). Registry values WIN so a
+//      distributed appsettings.json never carries the secret and the site can
+//      rotate the key without a rebuild.
+//
+// Reading the registry never throws out to the caller: a missing hive or value
+// simply leaves the appsettings value in place, which is what makes dev boxes
+// (appsettings only) and fielded machines (registry provisioned) both work.
+public static class AgentConfigProvider
+{
+    public const string RegistryPath = @"SOFTWARE\GE\ShopDB";
+
+    // Registry value names. These mirror the names the computers reporter uses
+    // (see plugins/endpoints/DESIGN-DECISIONS-agent.md section 1).
+    public const string BaseUrlValue = "BaseUrl";
+    public const string CollectorKeyValue = "CollectorKey";
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+    };
+
+    public static AgentConfig Load(string? appSettingsPath = null,
+        Microsoft.Extensions.Logging.ILogger? logger = null)
+    {
+        var config = LoadAppSettings(appSettingsPath) ?? new AgentConfig();
+        ApplyRegistryOverrides(config, logger);
+        return config;
+    }
+
+    private static AgentConfig? LoadAppSettings(string? path)
+    {
+        path ??= Path.Combine(AppContext.BaseDirectory, "appsettings.json");
+        if (!File.Exists(path))
+            return null;
+        try
+        {
+            var json = File.ReadAllText(path);
+            return JsonSerializer.Deserialize<AgentConfig>(json, JsonOptions);
+        }
+        catch
+        {
+            // Malformed appsettings: fall back to defaults + registry so the
+            // agent can still run if the secret is provisioned in the registry.
+            return null;
+        }
+    }
+
+    private static void ApplyRegistryOverrides(AgentConfig config,
+        Microsoft.Extensions.Logging.ILogger? logger = null)
+    {
+        // Try 64-bit view first, then the default/32-bit view. On a locked-down
+        // box (CyberArk/EPM gating regedit and hive reads) the read can throw
+        // SecurityException/UnauthorizedAccessException even when the values
+        // exist. We log the exact outcome per view instead of swallowing it, so
+        // "Config incomplete" can be told apart from "access denied".
+        RegistryView[] views = { RegistryView.Registry64, RegistryView.Registry32 };
+        foreach (var view in views)
+        {
+            try
+            {
+                using var machine = RegistryKey.OpenBaseKey(
+                    RegistryHive.LocalMachine, view);
+                using var key = machine.OpenSubKey(RegistryPath);
+                if (key is null)
+                {
+                    logger?.LogWarning(
+                        "Registry key HKLM\\{Path} not found in {View} view.",
+                        RegistryPath, view);
+                    continue;
+                }
+
+                var baseUrl = key.GetValue(BaseUrlValue) as string;
+                if (!string.IsNullOrWhiteSpace(baseUrl))
+                    config.BaseUrl = baseUrl.Trim();
+
+                var collectorKey = key.GetValue(CollectorKeyValue) as string;
+                if (!string.IsNullOrWhiteSpace(collectorKey))
+                    config.ApiKey = collectorKey.Trim();
+
+                logger?.LogInformation(
+                    "Registry {View}: BaseUrl {BaseUrlState}, CollectorKey {KeyState}.",
+                    view,
+                    string.IsNullOrWhiteSpace(baseUrl) ? "MISSING" : "present",
+                    string.IsNullOrWhiteSpace(collectorKey) ? "MISSING" : "present");
+
+                // Success reading this view; stop unless nothing was found.
+                if (!string.IsNullOrWhiteSpace(baseUrl) ||
+                    !string.IsNullOrWhiteSpace(collectorKey))
+                    return;
+            }
+            catch (Exception error)
+            {
+                logger?.LogError(error,
+                    "Registry read of HKLM\\{Path} in {View} view was blocked " +
+                    "({ErrorType}). If CyberArk/EPM is gating the hive, grant the " +
+                    "agent read access or use appsettings.json for this test.",
+                    RegistryPath, view, error.GetType().Name);
+            }
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/AgentFaultMonitor.cs

@@ -0,0 +1,99 @@
+using System.Diagnostics;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Agent self-monitoring (WER-style). Routes otherwise-unobserved failures -
+// unhandled exceptions on any thread and faulted tasks nobody awaited - to the
+// ILogger (so they land in the rolling file) AND directly to a dedicated
+// Windows Event Log source so agent runtime failures and agent/system interop
+// errors are visible in Event Viewer alongside the OS's own records.
+//
+// The Event Log source is created on first use; creating a source needs admin,
+// so if it is absent and cannot be created we degrade to the file log only and
+// never throw from a fault handler (that would mask the original failure).
+public sealed class AgentFaultMonitor
+{
+    public const string EventLogSource = "ShopDB Endpoint Agent";
+    public const string EventLogName = "Application";
+
+    private readonly ILogger logger;
+    private readonly bool eventLogReady;
+
+    public AgentFaultMonitor(ILogger logger)
+    {
+        this.logger = logger;
+        eventLogReady = EnsureEventLogSource();
+    }
+
+    // Wire the process-wide fault hooks. Call once at startup.
+    public void Install()
+    {
+        AppDomain.CurrentDomain.UnhandledException += OnUnhandledException;
+        TaskScheduler.UnobservedTaskException += OnUnobservedTaskException;
+    }
+
+    public void ReportFatal(string context, Exception error)
+    {
+        // File log first, always: the Event Log sink below is admin-gated (the
+        // source cannot be created without elevation), so an unelevated run such
+        // as the tray-launched --once/--report path would otherwise fail with no
+        // trace anywhere. The rolling file log is the one sink guaranteed to work
+        // in every context.
+        logger.LogError(error, "Fatal in {Context}", context);
+        Report(EventLogEntryType.Error, 1000, $"{context}: {error}");
+    }
+
+    private void OnUnhandledException(object sender, UnhandledExceptionEventArgs args)
+    {
+        var error = args.ExceptionObject as Exception;
+        var message = error?.ToString() ?? "unknown unhandled exception";
+        logger.LogCritical(error, "Unhandled exception (terminating={Terminating})",
+            args.IsTerminating);
+        Report(EventLogEntryType.Error, 1001,
+            $"Unhandled exception (terminating={args.IsTerminating}): {message}");
+    }
+
+    private void OnUnobservedTaskException(object? sender,
+        UnobservedTaskExceptionEventArgs args)
+    {
+        logger.LogError(args.Exception, "Unobserved task exception");
+        Report(EventLogEntryType.Warning, 1002,
+            $"Unobserved task exception: {args.Exception}");
+        // Mark observed so it does not escalate to a process-level failure.
+        args.SetObserved();
+    }
+
+    private void Report(EventLogEntryType type, int eventId, string message)
+    {
+        if (!eventLogReady)
+            return;
+        try
+        {
+            EventLog.WriteEntry(EventLogSource, message, type, eventId);
+        }
+        catch
+        {
+            // Event Log write failed (source removed, log full): the file log
+            // already has this entry; a fault handler must never throw.
+        }
+    }
+
+    private static bool EnsureEventLogSource()
+    {
+        try
+        {
+            if (EventLog.SourceExists(EventLogSource))
+                return true;
+            EventLog.CreateEventSource(new EventSourceCreationData(
+                EventLogSource, EventLogName));
+            return true;
+        }
+        catch
+        {
+            // Needs admin the first time; the installer creates the source, so
+            // in the field this succeeds. In dev without admin we log to file.
+            return false;
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/CollectSignal.cs

@@ -0,0 +1,26 @@
+namespace ShopDbEndpointAgent.Core;
+
+// A one-shot wake signal shared between the command worker and the telemetry
+// worker. After a command runs (e.g. MTConnect start/stop), the command worker
+// calls Request() so the telemetry loop collects immediately instead of waiting
+// out the remaining cadence, and the WebUI card reflects the new state within a
+// single report cycle rather than up to 15 minutes later.
+public sealed class CollectSignal
+{
+    private readonly SemaphoreSlim gate = new(0, 1);
+
+    // Wake the telemetry loop for one off-cadence collection. Extra calls while
+    // one is already pending collapse into a single wake (the gate caps at 1).
+    public void Request()
+    {
+        try { gate.Release(); }
+        catch (SemaphoreFullException) { /* a wake is already pending */ }
+    }
+
+    // Wait until either the cadence delay elapses or a collect is requested.
+    // Returns true when woken by a request, false on a normal cadence timeout.
+    public async Task<bool> WaitAsync(TimeSpan delay, CancellationToken token)
+    {
+        return await gate.WaitAsync(delay, token);
+    }
+}

agent/ShopDbEndpointAgent.Core/CollectorClient.cs

@@ -0,0 +1,201 @@
+using System.Net;
+using System.Net.Http.Json;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Posts one EndpointReport to POST {baseurl}/api/collector/endpoints with the
+// X-API-Key header (plugins/endpoints/AGENT-CONTRACT.md section 1), unwrapping
+// the ShopDB envelope { status, data, meta } to return the CollectorResponse.
+//
+// Resilience: transient failures (network errors, timeouts, 5xx, 429) are
+// retried with exponential backoff plus jitter, bounded by maxAttempts. A 4xx
+// other than 429 is a permanent error (bad key, unknown host in strict mode)
+// and is surfaced immediately without retry - hammering the server changes
+// nothing.
+public sealed class CollectorClient : IDisposable
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        DefaultIgnoreCondition = System.Text.Json.Serialization
+            .JsonIgnoreCondition.WhenWritingNull,
+    };
+
+    private readonly HttpClient http;
+    private readonly ILogger<CollectorClient> logger;
+    private readonly int maxAttempts;
+    private readonly Random jitter = new();
+
+    public CollectorClient(AgentConfig config, ILogger<CollectorClient> logger,
+        int maxAttempts = 4)
+    {
+        this.logger = logger;
+        this.maxAttempts = Math.Max(1, maxAttempts);
+        http = new HttpClient
+        {
+            BaseAddress = new Uri(config.BaseUrl.TrimEnd('/') + "/"),
+            Timeout = TimeSpan.FromSeconds(30),
+        };
+        http.DefaultRequestHeaders.Add("X-API-Key", config.ApiKey);
+    }
+
+    public async Task<CollectorResponse> SendAsync(
+        EndpointReport report, CancellationToken token)
+    {
+        Exception? last = null;
+        for (int attempt = 1; attempt <= maxAttempts; attempt++)
+        {
+            token.ThrowIfCancellationRequested();
+            try
+            {
+                return await SendOnceAsync(report, token);
+            }
+            catch (CollectorException error) when (error.IsPermanent)
+            {
+                // Bad credential or rejected payload: no retry.
+                throw;
+            }
+            catch (Exception error) when (
+                error is CollectorException or HttpRequestException or TaskCanceledException
+                && !token.IsCancellationRequested)
+            {
+                last = error;
+                if (attempt == maxAttempts)
+                    break;
+                var delay = BackoffDelay(attempt);
+                logger.LogWarning(
+                    "Collector send attempt {Attempt}/{Max} failed: {Message}; retrying in {Delay}s",
+                    attempt, maxAttempts, error.Message, delay.TotalSeconds);
+                await Task.Delay(delay, token);
+            }
+        }
+        throw last ?? new CollectorException(0, "collector send failed");
+    }
+
+    private async Task<CollectorResponse> SendOnceAsync(
+        EndpointReport report, CancellationToken token)
+    {
+        using var response = await http.PostAsJsonAsync(
+            "api/collector/endpoints", report, JsonOptions, token);
+
+        var body = await response.Content.ReadAsStringAsync(token);
+        if (!response.IsSuccessStatusCode)
+            throw new CollectorException((int)response.StatusCode, body);
+
+        var envelope = JsonSerializer.Deserialize<CollectorEnvelope>(body, JsonOptions);
+        if (envelope?.Data is null)
+            throw new CollectorException((int)response.StatusCode, "empty response body");
+        return envelope.Data;
+    }
+
+    // Fetch the server-resolved watch list (policy-attached processes/services)
+    // for this hostname, GET /api/endpoints/monitors/resolved. Shares the same
+    // X-API-Key credential as telemetry. Best-effort: returns null on any
+    // failure so the caller falls back to the last-known/local list rather than
+    // blanking monitoring on a transient blip. A single attempt, no retry - the
+    // next telemetry cycle retries naturally, and a stale-but-usable watch list
+    // beats an empty one.
+    public async Task<ResolvedMonitors?> FetchResolvedMonitorsAsync(
+        string hostname, CancellationToken token)
+    {
+        var url = "api/endpoints/monitors/resolved?hostname="
+            + Uri.EscapeDataString(hostname);
+        try
+        {
+            using var response = await http.GetAsync(url, token);
+            var body = await response.Content.ReadAsStringAsync(token);
+            if (!response.IsSuccessStatusCode)
+            {
+                logger.LogWarning(
+                    "Resolved-monitors fetch returned HTTP {Status}: {Body}",
+                    (int)response.StatusCode, body);
+                return null;
+            }
+            var envelope = JsonSerializer.Deserialize<ResolvedMonitorsEnvelope>(
+                body, JsonOptions);
+            return envelope?.Data;
+        }
+        catch (Exception error) when (
+            error is HttpRequestException or TaskCanceledException or JsonException
+            && !token.IsCancellationRequested)
+        {
+            logger.LogWarning(error, "Resolved-monitors fetch failed; keeping current watch list");
+            return null;
+        }
+    }
+
+    private TimeSpan BackoffDelay(int attempt)
+    {
+        // 2^(attempt-1) seconds, capped, plus up to 1s jitter.
+        double seconds = Math.Min(30, Math.Pow(2, attempt - 1));
+        return TimeSpan.FromSeconds(seconds + jitter.NextDouble());
+    }
+
+    // Uploads one operator issue report (free-text reason/details plus an
+    // optional PNG screenshot) to POST /api/endpoints/operatorreports as
+    // multipart/form-data, authorized by the same X-API-Key collector key as
+    // telemetry. The server resolves this hostname to its asset. A single
+    // attempt: the tray shows the operator the outcome and can retry by hand,
+    // and a stuck retry loop holding a screenshot in memory is worse than a
+    // clear failure. Returns the parsed upload response (new row id) or throws.
+    public async Task<OperatorReportUploadResponse?> UploadOperatorReportAsync(
+        string reason, string details, string? screenshotPath, string hostname,
+        CancellationToken token)
+    {
+        using var form = new MultipartFormDataContent();
+        form.Add(new StringContent(reason ?? string.Empty), "reason");
+        form.Add(new StringContent(details ?? string.Empty), "details");
+        form.Add(new StringContent(hostname ?? string.Empty), "hostname");
+
+        StreamContent? imageContent = null;
+        FileStream? imageStream = null;
+        try
+        {
+            if (!string.IsNullOrWhiteSpace(screenshotPath) && File.Exists(screenshotPath))
+            {
+                imageStream = File.OpenRead(screenshotPath);
+                imageContent = new StreamContent(imageStream);
+                imageContent.Headers.ContentType =
+                    new System.Net.Http.Headers.MediaTypeHeaderValue("image/png");
+                form.Add(imageContent, "screenshot",
+                    Path.GetFileName(screenshotPath));
+            }
+
+            using var response = await http.PostAsync(
+                "api/endpoints/operatorreports", form, token);
+            var body = await response.Content.ReadAsStringAsync(token);
+            if (!response.IsSuccessStatusCode)
+                throw new CollectorException((int)response.StatusCode, body);
+
+            var envelope = JsonSerializer.Deserialize<OperatorReportUploadEnvelope>(
+                body, JsonOptions);
+            return envelope?.Data;
+        }
+        finally
+        {
+            imageContent?.Dispose();
+            imageStream?.Dispose();
+        }
+    }
+
+    public void Dispose() => http.Dispose();
+}
+
+public sealed class CollectorException : Exception
+{
+    public int StatusCode { get; }
+
+    // A permanent failure is a 4xx that is not 429 (rate limit): retrying with
+    // the same key and payload cannot succeed, so the worker should back off to
+    // its normal cadence rather than fast-retry.
+    public bool IsPermanent =>
+        StatusCode >= 400 && StatusCode < 500
+        && StatusCode != (int)HttpStatusCode.TooManyRequests;
+
+    public CollectorException(int statusCode, string body)
+        : base($"collector returned HTTP {statusCode}: {body}")
+    {
+        StatusCode = statusCode;
+    }
+}

agent/ShopDbEndpointAgent.Core/CommandClient.cs

@@ -0,0 +1,104 @@
+using System.Net;
+using System.Net.Http.Json;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Talks to the endpoint command channel (plugins/endpoints/AGENT-CONTRACT.md
+// section 7). The agent opens no inbound port: it long-polls
+// GET /api/endpoints/commands/next, which the server holds open until a command
+// is queued (HTTP 200) or the hold window elapses (HTTP 204). After running the
+// claimed command locally the agent posts the outcome to
+// POST /api/endpoints/commands/{id}/result. Both share the endpoints collector
+// key via X-API-Key, so the command channel rides the same kill switch as
+// telemetry and adds no second secret.
+public sealed class CommandClient : IDisposable
+{
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        DefaultIgnoreCondition = System.Text.Json.Serialization
+            .JsonIgnoreCondition.WhenWritingNull,
+    };
+
+    private readonly HttpClient http;
+    private readonly SocketsHttpHandler handler;
+    private readonly ILogger<CommandClient> logger;
+
+    public CommandClient(AgentConfig config, ILogger<CommandClient> logger)
+    {
+        this.logger = logger;
+        // The command channel long-polls: the server holds each claim open for a
+        // hold window and then, between windows, the pooled TLS connection sits
+        // idle. Gunicorn's keep-alive closes an idle socket after a couple of
+        // seconds, so a connection reused after that yields "unexpected EOF or 0
+        // bytes from the transport stream" on the next TLS handshake. Retire
+        // pooled connections faster than the server's keep-alive so a socket the
+        // server has already dropped is never handed back out; the lifetime cap
+        // is a hard backstop so no connection lingers indefinitely.
+        handler = new SocketsHttpHandler
+        {
+            PooledConnectionIdleTimeout = TimeSpan.FromSeconds(1),
+            PooledConnectionLifetime = TimeSpan.FromMinutes(2),
+        };
+        http = new HttpClient(handler, disposeHandler: true)
+        {
+            BaseAddress = new Uri(config.BaseUrl.TrimEnd('/') + "/"),
+            // Longer than the collector client: the claim request is held open
+            // server-side (~25s), so the read timeout must clear that plus slack.
+            Timeout = TimeSpan.FromSeconds(60),
+        };
+        http.DefaultRequestHeaders.Add("X-API-Key", config.ApiKey);
+    }
+
+    // Claim the next pending command for this hostname, or null when the server
+    // returned 204 (nothing queued within the hold window). A 4xx other than 429
+    // is surfaced so the worker can back off instead of hot-looping a bad key or
+    // an unknown host.
+    public async Task<CommandClaim?> ClaimNextAsync(
+        string hostname, CancellationToken token)
+    {
+        var url = "api/endpoints/commands/next?hostname="
+            + Uri.EscapeDataString(hostname);
+        using var response = await http.GetAsync(url, token);
+
+        if (response.StatusCode == HttpStatusCode.NoContent)
+            return null;
+
+        var body = await response.Content.ReadAsStringAsync(token);
+        if (!response.IsSuccessStatusCode)
+            throw new CollectorException((int)response.StatusCode, body);
+
+        var envelope = JsonSerializer.Deserialize<CommandClaimEnvelope>(
+            body, JsonOptions);
+        return envelope?.Data;
+    }
+
+    // Report a claimed command's outcome. Best-effort: a failure to post the
+    // result is logged and swallowed so a transient network blip does not crash
+    // the worker; the command simply stays 'running' server-side until a later
+    // operator retry supersedes it.
+    // hostname rides along so the server can check this agent owns the command
+    // it is finalizing. The shared collector key does not say who is calling,
+    // so without it any agent can post a result for any command id. The server
+    // treats the parameter as optional for older agents and enforces it when
+    // present, so shipping this ahead of a fleet update is safe.
+    public async Task ReportResultAsync(
+        int commandId, string hostname, CommandResult result,
+        CancellationToken token)
+    {
+        var url = $"api/endpoints/commands/{commandId}/result?hostname="
+            + Uri.EscapeDataString(hostname);
+        using var response = await http.PostAsJsonAsync(
+            url, result, JsonOptions, token);
+        if (!response.IsSuccessStatusCode)
+        {
+            var body = await response.Content.ReadAsStringAsync(token);
+            logger.LogWarning(
+                "Reporting result for command {CommandId} returned HTTP {Status}: {Body}",
+                commandId, (int)response.StatusCode, body);
+        }
+    }
+
+    public void Dispose() => http.Dispose();
+}

agent/ShopDbEndpointAgent.Core/CommandWorker.cs

@@ -0,0 +1,174 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// The command loop as a hosted BackgroundService, separate from TelemetryWorker
+// so a slow or held-open command poll never delays a telemetry report and vice
+// versa. It long-polls the server for an allowlisted command
+// (plugins/endpoints/AGENT-CONTRACT.md section 7), runs it through
+// CommandExecutor, and posts the result back. The server holds each poll open
+// briefly, so this loop is effectively "wait for work, do it, immediately wait
+// again" rather than a fixed-cadence poll.
+//
+// Like TelemetryWorker, one bad iteration never kills the loop: a permanent
+// error (bad key, unknown host) backs off to a slow retry so it does not hammer
+// the server, and any other failure is logged and retried after a short pause.
+public sealed class CommandWorker : BackgroundService
+{
+    // Pause after a transient failure before re-polling, so a flapping network
+    // or a briefly-down server does not spin this loop.
+    private static readonly TimeSpan TransientRetryDelay = TimeSpan.FromSeconds(10);
+
+    // Longer back-off after a permanent error (bad key, host removed): the
+    // operator has to fix something, so re-polling fast changes nothing.
+    private static readonly TimeSpan PermanentRetryDelay = TimeSpan.FromSeconds(300);
+
+    // A genuine idle long-poll close only happens after the server has held the
+    // request open for most of its hold window (~25s). A connection that drops
+    // in well under this did not idle out - it failed at connect/TLS (e.g. an
+    // http:// BaseUrl hitting the TLS port), which must NOT be treated as a
+    // normal close and fast re-polled. Below this threshold we take the
+    // transient-failure backoff instead.
+    private static readonly TimeSpan MinIdlePollDuration = TimeSpan.FromSeconds(5);
+
+    // Hard floor between poll starts. Even if some unforeseen path returns
+    // immediately every iteration, this caps the loop at a safe request rate so
+    // a misconfigured agent can never turn into a request storm.
+    private static readonly TimeSpan MinPollInterval = TimeSpan.FromSeconds(2);
+
+    private readonly CommandClient client;
+    private readonly CommandExecutor executor;
+    private readonly ILogger<CommandWorker> logger;
+    private readonly CollectSignal? collectSignal;
+    private readonly string hostname;
+
+    public CommandWorker(CommandClient client, CommandExecutor executor,
+        ILogger<CommandWorker> logger, CollectSignal? collectSignal = null)
+    {
+        this.client = client;
+        this.executor = executor;
+        this.logger = logger;
+        this.collectSignal = collectSignal;
+        hostname = Environment.MachineName;
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation("Command channel started for host {Host}", hostname);
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            var pollStarted = System.Diagnostics.Stopwatch.StartNew();
+            try
+            {
+                var claim = await client.ClaimNextAsync(hostname, stoppingToken);
+                if (claim is not null)
+                    await RunClaimAsync(claim, stoppingToken);
+                // On a 204 (no work) the server already consumed the hold
+                // window, so re-poll immediately.
+            }
+            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+            {
+                break;
+            }
+            catch (CollectorException error) when (error.IsPermanent)
+            {
+                logger.LogError(error,
+                    "Permanent command-channel error; backing off");
+                await SafeDelay(PermanentRetryDelay, stoppingToken);
+            }
+            catch (Exception error) when (IsIdlePollClose(error)
+                && pollStarted.Elapsed >= MinIdlePollDuration)
+            {
+                // The server (or a proxy) held the poll open for most of the
+                // hold window and then closed it without a command. That is the
+                // normal end of a hold window, not a failure: log quietly at
+                // debug and re-poll immediately.
+                logger.LogDebug(error, "Command poll connection closed; re-polling");
+            }
+            catch (Exception error)
+            {
+                // Anything else - including a connection/TLS failure that drops
+                // in under MinIdlePollDuration (e.g. an http:// BaseUrl hitting
+                // the TLS port) - is a real transient failure. Back off so a
+                // misconfiguration cannot spin into a request storm.
+                logger.LogWarning(error, "Command poll failed; retrying shortly");
+                await SafeDelay(TransientRetryDelay, stoppingToken);
+            }
+
+            // Floor the loop rate. On the immediate re-poll paths (204 or a
+            // genuine idle close) the elapsed time already exceeds this, so it
+            // adds no latency; it only bites if an iteration returned unusually
+            // fast, capping the worst case at a safe request rate.
+            var remaining = MinPollInterval - pollStarted.Elapsed;
+            if (remaining > TimeSpan.Zero)
+                await SafeDelay(remaining, stoppingToken);
+        }
+
+        logger.LogInformation("Command channel stopped");
+    }
+
+    private async Task RunClaimAsync(CommandClaim claim, CancellationToken token)
+    {
+        logger.LogInformation("Running command {Id} action={Action}",
+            claim.EndpointCommandId, claim.Action);
+
+        CommandResult result;
+        try
+        {
+            result = await executor.ExecuteAsync(claim, token);
+        }
+        catch (Exception error)
+        {
+            logger.LogError(error, "Command {Id} action={Action} threw",
+                claim.EndpointCommandId, claim.Action);
+            result = new CommandResult
+            {
+                Succeeded = false,
+                Message = $"Command failed: {error.Message}",
+            };
+        }
+
+        await client.ReportResultAsync(
+            claim.EndpointCommandId, hostname, result, token);
+        logger.LogInformation("Command {Id} finished succeeded={Succeeded}",
+            claim.EndpointCommandId, result.Succeeded);
+
+        // A command changed something on the endpoint (e.g. MTConnect start/stop);
+        // wake the telemetry loop to collect now so the WebUI card reflects the
+        // new state within one report cycle instead of after the full cadence.
+        collectSignal?.Request();
+    }
+
+    // A long poll that the server or an intermediary closes without sending a
+    // command surfaces as an HttpRequestException wrapping an HttpIOException
+    // (ResponseEnded), or a bare IOException. Whether that is a benign hold-
+    // window close or a fast connect/TLS failure is decided by the caller using
+    // how long the poll stayed open (see MinIdlePollDuration); this only matches
+    // the exception shape.
+    private static bool IsIdlePollClose(Exception error)
+    {
+        for (Exception? current = error; current is not null; current = current.InnerException)
+        {
+            if (current is System.Net.Http.HttpIOException httpIo
+                && httpIo.HttpRequestError == System.Net.Http.HttpRequestError.ResponseEnded)
+                return true;
+            if (current is System.IO.IOException)
+                return true;
+        }
+        return false;
+    }
+
+    private static async Task SafeDelay(TimeSpan delay, CancellationToken token)
+    {
+        try
+        {
+            await Task.Delay(delay, token);
+        }
+        catch (OperationCanceledException)
+        {
+            // Shutting down: let the loop condition end it.
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/ConsoleWindow.cs

@@ -0,0 +1,51 @@
+using System.Runtime.InteropServices;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Hides the console window this process was given.
+//
+// shopdbagent.exe is a console executable, so anything that starts it in an
+// interactive session gets a visible black window. That was invisible while the
+// tray owned the probe - it launched with CreateNoWindow - but the user-context
+// scheduled task runs the exe directly in the operator's session, where the
+// window is very much visible and pops up on every collection cycle.
+//
+// The window is hidden rather than the exe rebuilt as a WinExe: the agent is
+// also a service host and a command-line tool, and both of those want a real
+// console for --once, --report and service debugging.
+public static class ConsoleWindow
+{
+    private const int SW_HIDE = 0;
+
+    [DllImport("kernel32.dll")]
+    private static extern nint GetConsoleWindow();
+
+    [DllImport("user32.dll")]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool ShowWindow(nint window, int command);
+
+    // Best-effort: a process with no console (already detached, or redirected by
+    // a caller) simply has nothing to hide, and failing to hide a window must
+    // never stop the collection that window belongs to.
+    public static void Hide()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        try
+        {
+            var window = GetConsoleWindow();
+            if (window != nint.Zero)
+            {
+                ShowWindow(window, SW_HIDE);
+            }
+        }
+        catch
+        {
+            // Nothing useful to do or say: there is no log sink yet at the point
+            // this runs, and a visible window is cosmetic next to losing data.
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/Contracts.cs

@@ -0,0 +1,231 @@
+using System.Text.Json.Serialization;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Wire keys MUST stay lowercase/no-underscore to match the ShopDB collector
+// schema (plugins/endpoints/AGENT-CONTRACT.md). PascalCase C# properties are
+// mapped back with JsonPropertyName so the serializer does not rename them.
+
+public sealed class EndpointReport
+{
+    [JsonPropertyName("hostname")] public string Hostname { get; set; } = "";
+    [JsonPropertyName("adopt")] public bool? Adopt { get; set; }
+    [JsonPropertyName("loggedinuser")] public string? LoggedInUser { get; set; }
+    [JsonPropertyName("serialnumber")] public string? SerialNumber { get; set; }
+    [JsonPropertyName("pctype")] public string? PcType { get; set; }
+    [JsonPropertyName("vendorname")] public string? VendorName { get; set; }
+    [JsonPropertyName("modelnumber")] public string? ModelNumber { get; set; }
+    [JsonPropertyName("osname")] public string? OsName { get; set; }
+    [JsonPropertyName("ipaddress")] public string? IpAddress { get; set; }
+    [JsonPropertyName("machinenumber")] public string? MachineNumber { get; set; }
+    [JsonPropertyName("agentversion")] public string? AgentVersion { get; set; }
+    [JsonPropertyName("trayversion")] public string? TrayVersion { get; set; }
+    [JsonPropertyName("lastboottime")] public DateTimeOffset? LastBootTime { get; set; }
+    [JsonPropertyName("uptimeseconds")] public long? UptimeSeconds { get; set; }
+    [JsonPropertyName("idleseconds")] public long? IdleSeconds { get; set; }
+    [JsonPropertyName("cpupercent")] public double? CpuPercent { get; set; }
+    [JsonPropertyName("memorypercent")] public double? MemoryPercent { get; set; }
+    [JsonPropertyName("services")] public object[]? Services { get; set; }
+    [JsonPropertyName("ports")] public object[]? Ports { get; set; }
+    [JsonPropertyName("interfaces")] public object[]? Interfaces { get; set; }
+    [JsonPropertyName("scheduledtasks")] public object[]? ScheduledTasks { get; set; }
+    [JsonPropertyName("events")] public EndpointEventRecord[]? Events { get; set; }
+    // Additive inventory telemetry. The server does not persist these yet; its
+    // ingest logs them as unknown keys (plugins/endpoints/plugin.py) so the
+    // incoming values are observable before any DB column or UI card exists.
+    // Keys stay lowercase/no-underscore to match AGENT-CONTRACT.md.
+    [JsonPropertyName("disks")] public object[]? Disks { get; set; }
+    [JsonPropertyName("bios")] public object? Bios { get; set; }
+    [JsonPropertyName("memory")] public object? Memory { get; set; }
+    [JsonPropertyName("processor")] public object? Processor { get; set; }
+    [JsonPropertyName("osinfo")] public object? OsInfo { get; set; }
+    [JsonPropertyName("domain")] public string? Domain { get; set; }
+    // Installed-software SBOM, mirroring the Assess-Orchestrator applications
+    // collection: both Uninstall registry hives, {displayname, displayversion,
+    // publisher}. Server logs it as an unpersisted key until the SBOM store lands.
+    [JsonPropertyName("applications")] public object[]? Applications { get; set; }
+
+    // True when Windows is holding a reboot. A machine that has been waiting to
+    // reboot for weeks explains stalled patching and "the fix did not take"
+    // reports, and on a shop floor PC nobody reboots voluntarily.
+    [JsonPropertyName("pendingreboot")] public bool? PendingReboot { get; set; }
+
+    // Which signal(s) drove pendingreboot, so the server can tell a box staged
+    // mid-servicing (pendingfilerename) from one with a stale servicing key.
+    // Empty array = checked, nothing pending. Omitted = the check failed.
+    [JsonPropertyName("rebootreasons")] public string[]? RebootReasons { get; set; }
+
+    // hiberbootenabled (fast startup configured) and lastboottype (what the
+    // last boot actually did). Uptime is not trustworthy when these disagree.
+    [JsonPropertyName("bootinfo")] public object? BootInfo { get; set; }
+
+    // Defender health. Persisted but deliberately not surfaced: known false
+    // positives in this environment.
+    [JsonPropertyName("defender")] public object? Defender { get; set; }
+
+    // Physical drive health from two sources: MSFT_PhysicalDisk (the only one
+    // that reports NVMe) and Win32_DiskDrive.Status (ATA/SATA and fallback).
+    // Each entry carries a precomputed predictfailure so an alert is a boolean
+    // test rather than a string match against an enum. Null predictfailure
+    // means the drive did not answer - unknown, not healthy.
+    [JsonPropertyName("diskhealth")] public object[]? DiskHealth { get; set; }
+
+    // Session-scoped data gathered by a probe running as the signed-in user:
+    // mapped drives and user-owned listeners. Null when nobody is signed in or
+    // the probe did not produce a result this cycle - absent means "not
+    // observed", which is deliberately distinct from an empty list.
+    [JsonPropertyName("usercontext")] public object? UserContext { get; set; }
+
+    // Pending Dell Command | Update results, produced by the shopdb-dellupdates
+    // agent utility rather than collected in C#: the data comes from dcu-cli's
+    // own scan output, so the utility that parses it belongs next to the task
+    // that writes it. Null means no scan has ever run (or the utility is not
+    // installed), which is deliberately distinct from a scan that found nothing
+    // pending - the first is "unknown", the second is "known clean".
+    [JsonPropertyName("dellupdates")] public object? DellUpdates { get; set; }
+}
+
+public sealed class EndpointEventRecord
+{
+    [JsonPropertyName("eventid")] public int EventId { get; set; }
+
+    // The Windows event record id: monotonic and unique within its channel on a
+    // given machine. It is both the agent's harvest watermark and the server's
+    // dedupe key, so the same record can never be stored twice. Null only when
+    // the source record did not expose one.
+    [JsonPropertyName("eventrecordid")] public long? EventRecordId { get; set; }
+
+    [JsonPropertyName("eventchannel")] public string? EventChannel { get; set; }
+    [JsonPropertyName("eventsource")] public string? EventSource { get; set; }
+    [JsonPropertyName("eventtime")] public DateTimeOffset? EventTime { get; set; }
+    [JsonPropertyName("eventmessage")] public string? EventMessage { get; set; }
+    [JsonPropertyName("fields")] public Dictionary<string, object>? Fields { get; set; }
+}
+
+public sealed class CollectorResponse
+{
+    [JsonPropertyName("status")] public string Status { get; set; } = "";
+    [JsonPropertyName("action")] public string? Action { get; set; }
+    [JsonPropertyName("assetid")] public int? AssetId { get; set; }
+    [JsonPropertyName("identityvalue")] public string? IdentityValue { get; set; }
+    [JsonPropertyName("warnings")] public string[]? Warnings { get; set; }
+}
+
+// The collector wraps the plugin payload in the ShopDB envelope
+// { status, data: { action, assetid, identityvalue, warnings }, meta }.
+public sealed class CollectorEnvelope
+{
+    [JsonPropertyName("status")] public string Status { get; set; } = "";
+    [JsonPropertyName("data")] public CollectorResponse? Data { get; set; }
+}
+
+// Server response to an operator issue report upload. Carries the new row id so
+// the agent can log it for correlation.
+public sealed class OperatorReportUploadResponse
+{
+    [JsonPropertyName("operatorreportid")] public int? OperatorReportId { get; set; }
+    [JsonPropertyName("assetid")] public int? AssetId { get; set; }
+}
+
+public sealed class OperatorReportUploadEnvelope
+{
+    [JsonPropertyName("status")] public string Status { get; set; } = "";
+    [JsonPropertyName("data")] public OperatorReportUploadResponse? Data { get; set; }
+}
+
+// A command the server claimed for this endpoint on the long-poll. The
+// allowlisted action name crosses the wire (see AGENT-CONTRACT.md section 7);
+// generic actions (service_* / process_*) also carry the subject to act on -
+// Target is a Windows service name or a process image (for example
+// 'DncMain.exe') and TargetKind is 'service' or 'process'. Fixed-target actions
+// (mtconnect_*) leave both null. Carrying the target on the wire is what lets a
+// site build the agent once and drive every future policy/app from server data.
+public sealed class CommandClaim
+{
+    [JsonPropertyName("endpointcommandid")] public int EndpointCommandId { get; set; }
+    [JsonPropertyName("action")] public string Action { get; set; } = "";
+    [JsonPropertyName("target")] public string? Target { get; set; }
+    [JsonPropertyName("targetkind")] public string? TargetKind { get; set; }
+
+    // For update_app the server resolves the pinned application version into a
+    // delivery descriptor (package URL, SHA-256, silent-install switches). The
+    // agent fetches the bytes itself with its collector credential; the wire
+    // never carries the installer body. Null for every other action.
+    [JsonPropertyName("app")] public AppDeliveryClaim? App { get; set; }
+
+    // For run_script the server resolves the ShopDB-hosted script into a
+    // delivery descriptor (body URL, SHA-256, run context). The agent fetches
+    // the body itself with its collector credential; the wire never carries the
+    // script body. Null for every other action.
+    [JsonPropertyName("script")] public ScriptDeliveryClaim? Script { get; set; }
+}
+
+// The resolved installer-push descriptor accompanying an update_app claim.
+// InstallPath is a ShopDB-relative package URL the agent joins to its BaseUrl
+// and downloads with its collector credential; Sha256 pins the exact bytes;
+// SilentArgs are this version's unattended-install switches (may be empty for
+// an MSI, which the agent installs via msiexec /qn). AppVersionId is null when
+// the push resolves an app-level install source rather than a pinned version.
+public sealed class AppDeliveryClaim
+{
+    [JsonPropertyName("appversionid")] public int? AppVersionId { get; set; }
+    [JsonPropertyName("appid")] public int AppId { get; set; }
+    [JsonPropertyName("appname")] public string? AppName { get; set; }
+    [JsonPropertyName("version")] public string? Version { get; set; }
+    [JsonPropertyName("installpath")] public string? InstallPath { get; set; }
+    [JsonPropertyName("sha256")] public string? Sha256 { get; set; }
+    [JsonPropertyName("silentargs")] public string? SilentArgs { get; set; }
+}
+
+// The resolved script-push descriptor accompanying a run_script claim.
+// InstallPath is a ShopDB-relative body URL the agent joins to its BaseUrl and
+// downloads with its collector credential; Sha256 pins the exact bytes;
+// RunContext is 'system' (the agent's own service account) or 'user' (the
+// interactive logged-on session), decided per script in the ShopDB library.
+public sealed class ScriptDeliveryClaim
+{
+    [JsonPropertyName("scriptid")] public int ScriptId { get; set; }
+    [JsonPropertyName("scriptname")] public string? ScriptName { get; set; }
+    [JsonPropertyName("installpath")] public string? InstallPath { get; set; }
+    [JsonPropertyName("sha256")] public string? Sha256 { get; set; }
+    [JsonPropertyName("runcontext")] public string? RunContext { get; set; }
+}
+
+// Envelope for the claim long-poll: { status, data: { endpointcommandid, action } }.
+public sealed class CommandClaimEnvelope
+{
+    [JsonPropertyName("status")] public string Status { get; set; } = "";
+    [JsonPropertyName("data")] public CommandClaim? Data { get; set; }
+}
+
+// The outcome the agent posts back after running a claimed command. When the
+// action probed MTConnect, MtConnectRunning carries the observed state so the
+// server can cache it for the WebUI toggle.
+public sealed class CommandResult
+{
+    [JsonPropertyName("succeeded")] public bool Succeeded { get; set; }
+    [JsonPropertyName("message")] public string? Message { get; set; }
+    [JsonPropertyName("mtconnectrunning")] public bool? MtConnectRunning { get; set; }
+    [JsonPropertyName("detail")] public Dictionary<string, object>? Detail { get; set; }
+}
+
+// The server-resolved watch list for this endpoint (processes and services the
+// site's policy attaches to the box's PC type), fetched each telemetry cycle so
+// a policy-attached monitor is enumerated without editing appsettings.json on
+// the box. Same {name, app} shape as the local MonitorConfig, so the merge is a
+// direct list union. Empty lists mean "watch nothing extra beyond local".
+public sealed class ResolvedMonitors
+{
+    [JsonPropertyName("processes")] public MonitorTarget[] Processes { get; set; }
+        = Array.Empty<MonitorTarget>();
+
+    [JsonPropertyName("services")] public MonitorTarget[] Services { get; set; }
+        = Array.Empty<MonitorTarget>();
+}
+
+// Envelope for the resolved-monitors route: { status, data: { processes, services } }.
+public sealed class ResolvedMonitorsEnvelope
+{
+    [JsonPropertyName("status")] public string Status { get; set; } = "";
+    [JsonPropertyName("data")] public ResolvedMonitors? Data { get; set; }
+}

agent/ShopDbEndpointAgent.Core/CuratedEventCatalog.cs

@@ -0,0 +1,52 @@
+namespace ShopDbEndpointAgent.Core;
+
+// The curated Windows Event catalog, LOCKED to the server list in
+// plugins/endpoints/plugin.py (CURATED_EVENT_IDS) and documented in
+// plugins/endpoints/DESIGN-DECISIONS-agent.md section 4. The server stores ONLY
+// these IDs; anything else in a report's `events` is ignored (not an error).
+// Sending only these keeps the payload small and mirrors the catalog intent.
+//
+// Channels matter: an ID is read from its own log, so the collector reads
+// Security, System, and Application - not System alone. IDs are namespaced by
+// channel here because the same numeric ID can mean different things across
+// logs; we only harvest the (channel, id) pairs the server curates.
+public static class CuratedEventCatalog
+{
+    public sealed record Entry(int EventId, string Channel, string Meaning);
+
+    public static readonly IReadOnlyList<Entry> Entries = new List<Entry>
+    {
+        new(4624, "Security", "Successful logon"),
+        new(4625, "Security", "Failed logon"),
+        new(4634, "Security", "Logoff"),
+        new(4672, "Security", "Special privileges assigned to new logon"),
+        new(4697, "Security", "Service installed"),
+        new(4698, "Security", "Scheduled task created"),
+        new(4618, "Security", "Monitored security event pattern"),
+        new(41, "System", "Kernel-Power, unexpected shutdown"),
+        new(55, "System", "NTFS file system corruption"),
+        new(7011, "System", "Service Control Manager timeout"),
+        new(10016, "System", "DCOM permission error"),
+        // Windows Error Reporting on the Application channel: 1000 is the
+        // faulting-application record (app, version, faulting module, exception
+        // code), 1001 is the WER bucket record Windows pairs with it, and 1002
+        // is an unresponsive app rather than a crash. The structured detail for
+        // all three arrives in the record's EventData, which the collector lifts
+        // into `fields`.
+        new(1000, "Application", "Application error / faulting module"),
+        new(1001, "Application", "Application error / bugcheck report"),
+        new(1002, "Application", "Application hang"),
+    };
+
+    // The distinct channels the collector must read.
+    public static readonly IReadOnlyList<string> Channels =
+        Entries.Select(entry => entry.Channel).Distinct().ToList();
+
+    // The set of curated IDs for a given channel, for a fast membership check
+    // while walking that channel's log newest-first.
+    public static IReadOnlySet<int> IdsForChannel(string channel)
+        => Entries.Where(entry =>
+                string.Equals(entry.Channel, channel, StringComparison.OrdinalIgnoreCase))
+            .Select(entry => entry.EventId)
+            .ToHashSet();
+}

agent/ShopDbEndpointAgent.Core/EventWatermarkStore.cs

@@ -0,0 +1,132 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Remembers the newest Windows event record id already reported for each
+// curated channel, so a collect cycle harvests ONLY records the server has not
+// seen.
+//
+// Why this exists: the collector used to re-read the newest N records of every
+// channel on every cycle, and the server ingest appends event rows without a
+// dedupe check. A single crash therefore landed in the database once per
+// cadence tick for as long as it stayed inside that window - up to 96 identical
+// rows a day per event. Carrying a watermark makes the steady state "only what
+// is new", which is also what makes the full event XML affordable to send.
+//
+// The watermark is persisted under %ProgramData% (not in memory) because a
+// service restart would otherwise re-report the whole window again, which is
+// exactly the crash-loop case where duplicate events are most likely.
+//
+// Record ids are per channel and monotonic on a given machine. A cleared or
+// rebuilt event log restarts them at 1; that is handled by treating a stored
+// watermark HIGHER than the newest available record as stale and resetting it,
+// otherwise the channel would go permanently silent.
+public sealed class EventWatermarkStore
+{
+    private const string StoreFileName = "eventwatermark.json";
+
+    // %ProgramData%\ShopDB\EndpointAgent - the same root the rolling agent log
+    // lives under, so all agent-owned state sits in one place.
+    public static string DefaultStateDirectory => Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
+        "ShopDB", "EndpointAgent");
+
+    private readonly string storePath;
+    private readonly ILogger<EventWatermarkStore> logger;
+    private readonly Dictionary<string, long> watermarks;
+
+    public EventWatermarkStore(ILogger<EventWatermarkStore> logger,
+        string? stateDirectory = null)
+    {
+        this.logger = logger;
+        var directory = string.IsNullOrWhiteSpace(stateDirectory)
+            ? DefaultStateDirectory
+            : stateDirectory;
+        storePath = Path.Combine(directory, StoreFileName);
+        watermarks = Load();
+    }
+
+    // The last record id reported for this channel, or 0 when the channel has
+    // never been harvested. 0 means "first contact": the caller sends a bounded
+    // tail for initial context rather than the entire backlog.
+    public long GetWatermark(string channel)
+        => watermarks.TryGetValue(channel, out var value) ? value : 0;
+
+    public bool HasWatermark(string channel)
+        => watermarks.ContainsKey(channel);
+
+    // Advance the channel forward only. Never moves backwards, so an
+    // out-of-order read cannot cause the same record to be reported twice.
+    public void Advance(string channel, long recordId)
+    {
+        if (recordId <= 0)
+            return;
+        if (watermarks.TryGetValue(channel, out var current) && current >= recordId)
+            return;
+        watermarks[channel] = recordId;
+    }
+
+    // A cleared or rebuilt log restarts record ids near 1. When the newest
+    // record available is below the stored watermark the store is stale, so
+    // drop it and let the channel re-seed instead of going silent forever.
+    public bool ResetIfStale(string channel, long newestAvailableRecordId)
+    {
+        if (newestAvailableRecordId <= 0)
+            return false;
+        if (!watermarks.TryGetValue(channel, out var current) || current <= newestAvailableRecordId)
+            return false;
+
+        logger.LogInformation(
+            "Event channel {Channel} record id went backwards ({Stored} -> {Newest}); log was cleared, reseeding",
+            channel, current, newestAvailableRecordId);
+        watermarks.Remove(channel);
+        return true;
+    }
+
+    // Best-effort persist. A failure here costs at most a repeated report of
+    // records already sent, so it must never abort a collection.
+    public void Save()
+    {
+        try
+        {
+            var directory = Path.GetDirectoryName(storePath);
+            if (!string.IsNullOrWhiteSpace(directory))
+                Directory.CreateDirectory(directory);
+
+            // Write-then-rename so a crash mid-write cannot leave a truncated
+            // file that would reseed every channel on the next start.
+            var temporaryPath = storePath + ".tmp";
+            File.WriteAllText(temporaryPath,
+                JsonSerializer.Serialize(watermarks));
+            File.Move(temporaryPath, storePath, overwrite: true);
+        }
+        catch (Exception error)
+        {
+            logger.LogDebug(error, "Could not persist event watermarks to {Path}", storePath);
+        }
+    }
+
+    private Dictionary<string, long> Load()
+    {
+        try
+        {
+            if (!File.Exists(storePath))
+                return new Dictionary<string, long>(StringComparer.OrdinalIgnoreCase);
+
+            var loaded = JsonSerializer.Deserialize<Dictionary<string, long>>(
+                File.ReadAllText(storePath));
+            return loaded is null
+                ? new Dictionary<string, long>(StringComparer.OrdinalIgnoreCase)
+                : new Dictionary<string, long>(loaded, StringComparer.OrdinalIgnoreCase);
+        }
+        catch (Exception error)
+        {
+            // A corrupt store reseeds every channel, which costs one bounded
+            // tail per channel - acceptable versus failing the collection.
+            logger.LogWarning(error,
+                "Event watermark store unreadable at {Path}; reseeding channels", storePath);
+            return new Dictionary<string, long>(StringComparer.OrdinalIgnoreCase);
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/FileLoggerProvider.cs

@@ -0,0 +1,218 @@
+using System.Collections.Concurrent;
+using System.Text;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// A dependency-free rolling-file ILoggerProvider. The runtime code only ever
+// talks to ILogger, so swapping or adding sinks later (a ShopDB HTTP sink, Seq,
+// syslog) is a host-builder change with zero worker changes. This provider
+// writes one line per entry to a daily file under the configured log directory
+// and prunes files older than the retention window.
+public sealed class FileLoggerProvider : ILoggerProvider
+{
+    private readonly string directory;
+    private readonly LogLevel minLevel;
+    private readonly int retentionDays;
+    private readonly string filePrefix;
+    private readonly object gate = new();
+    private readonly ConcurrentDictionary<string, FileLogger> loggers = new();
+    private string currentDateStamp = "";
+    private StreamWriter? writer;
+
+    // Why the sink can be unusable, or null when it opened normally. The
+    // constructor cannot throw (see below), but a caller that has a second,
+    // known-writable place to complain to needs to be able to ask.
+    public string? SinkProblem { get; private set; }
+
+    public FileLoggerProvider(string directory, LogLevel minLevel = LogLevel.Information,
+        int retentionDays = 14, string filePrefix = "agent")
+    {
+        this.directory = directory;
+        this.minLevel = minLevel;
+        this.retentionDays = retentionDays;
+        this.filePrefix = filePrefix;
+        // Best-effort: creating the log directory can fail on a locked-down host
+        // or when a non-privileged user targets a SYSTEM-owned path. Never let
+        // that abort construction; Write() degrades to a no-op if the sink is
+        // unusable.
+        //
+        // The reason is KEPT rather than discarded. A silently dead sink is what
+        // made the user-context probe undiagnosable: running as the operator it
+        // could not write into the SYSTEM-owned ProgramData log directory, so a
+        // probe that failed and a probe that never ran produced identical
+        // silence. Callers that have a writable fallback can now surface this.
+        try { Directory.CreateDirectory(directory); }
+        catch (Exception error) when (error is IOException or UnauthorizedAccessException)
+        {
+            SinkProblem = $"{directory}: {error.Message}";
+        }
+    }
+
+    // The default log directory when config leaves LogPath empty:
+    // %ProgramData%\ShopDB\EndpointAgent\logs
+    //
+    // SERVICE-ONLY. This path is SYSTEM-owned and a signed-in operator cannot
+    // write to it, so anything running in the user's session must use
+    // UserProfileLogDirectory() instead.
+    public static string DefaultDirectory()
+        => Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
+            "ShopDB", "EndpointAgent", "logs");
+
+    // The shop-floor operator account. Every shop-floor endpoint uses this same
+    // local account name, so the path is fixed rather than resolved through the
+    // interactive token: the token lookup is the part that fails on a hardened
+    // endpoint, and when it fails the writer and the reader silently disagree
+    // about where the spool lives. If a site ever uses a different account only
+    // user-context is lost - telemetry, commands and inventory are unaffected.
+    public const string ShopFloorUserName = "ShopFloor";
+
+    public static string ShopFloorProfileDirectory()
+        => Path.Combine(DrivesRoot, "Users", ShopFloorUserName);
+
+    private static string DrivesRoot =>
+        Path.GetPathRoot(Environment.GetFolderPath(Environment.SpecialFolder.Windows))
+        ?? @"C:\";
+
+    // Where the TRAY and the user-context probe log:
+    // C:\Users\ShopFloor\ShopDB\Logs
+    // The operator owns this directory, so it is writable from the user session
+    // where ProgramData is not.
+    public static string UserProfileLogDirectory()
+        => Path.Combine(ShopFloorProfileDirectory(), "ShopDB", "Logs");
+
+    public ILogger CreateLogger(string categoryName)
+        => loggers.GetOrAdd(categoryName, name => new FileLogger(this, name));
+
+    internal bool IsEnabled(LogLevel level) => level >= minLevel && level != LogLevel.None;
+
+    internal void Write(string category, LogLevel level, string message, Exception? error)
+    {
+        var now = DateTimeOffset.Now;
+        var line = new StringBuilder()
+            .Append(now.ToString("yyyy-MM-dd HH:mm:ss.fff zzz"))
+            .Append(" [").Append(LevelTag(level)).Append("] ")
+            .Append(ShortCategory(category)).Append(": ")
+            .Append(message);
+        if (error is not null)
+            line.Append(Environment.NewLine).Append(error);
+
+        lock (gate)
+        {
+            // Logging must never take down the agent. If the log file cannot be
+            // opened or written (for example a non-privileged user running the
+            // exe against a logs directory owned by the SYSTEM service, which
+            // yields UnauthorizedAccessException on open), swallow it and drop
+            // the line rather than letting it unwind through bootstrap. A failed
+            // sink is a degraded state, not a fatal one.
+            try
+            {
+                RollIfNeeded(now);
+                writer?.WriteLine(line.ToString());
+            }
+            catch (Exception sinkError) when (sinkError is IOException or UnauthorizedAccessException)
+            {
+                writer = null;
+            }
+        }
+    }
+
+    private void RollIfNeeded(DateTimeOffset now)
+    {
+        var stamp = now.ToString("yyyyMMdd");
+        if (stamp == currentDateStamp && writer is not null)
+            return;
+
+        writer?.Flush();
+        writer?.Dispose();
+        currentDateStamp = stamp;
+        // One convention for every log this codebase writes:
+        // "<yyyyMMdd>-<prefix>.log", so agent, tray and installer logs sort
+        // chronologically when they share a directory and can be collected with
+        // a single date-leading glob. The service previously used the opposite
+        // order, which meant a support request for "the logs from the 5th" had to
+        // know which component wrote which shape.
+        var name = $"{stamp}-{filePrefix}.log";
+        var path = Path.Combine(directory, name);
+        writer = new StreamWriter(new FileStream(
+            path, FileMode.Append, FileAccess.Write, FileShare.ReadWrite))
+        {
+            AutoFlush = true,
+        };
+        PruneOldFiles();
+    }
+
+    private void PruneOldFiles()
+    {
+        try
+        {
+            var cutoff = DateTime.Now.AddDays(-retentionDays);
+            // Both shapes: retention has to keep covering the "<prefix>-<date>"
+            // files written before the convention was unified, or an upgraded
+            // endpoint would keep its pre-upgrade logs forever.
+            string[] patterns = [$"*-{filePrefix}.log", $"{filePrefix}-*.log"];
+            foreach (var pattern in patterns)
+            foreach (var file in Directory.EnumerateFiles(directory, pattern))
+            {
+                if (File.GetLastWriteTime(file) < cutoff)
+                    File.Delete(file);
+            }
+        }
+        catch
+        {
+            // Pruning is best-effort; never let housekeeping break logging.
+        }
+    }
+
+    private static string LevelTag(LogLevel level) => level switch
+    {
+        LogLevel.Trace => "TRC",
+        LogLevel.Debug => "DBG",
+        LogLevel.Information => "INF",
+        LogLevel.Warning => "WRN",
+        LogLevel.Error => "ERR",
+        LogLevel.Critical => "CRT",
+        _ => "---",
+    };
+
+    private static string ShortCategory(string category)
+    {
+        var dot = category.LastIndexOf('.');
+        return dot >= 0 && dot < category.Length - 1 ? category[(dot + 1)..] : category;
+    }
+
+    public void Dispose()
+    {
+        lock (gate)
+        {
+            writer?.Flush();
+            writer?.Dispose();
+            writer = null;
+        }
+    }
+
+    private sealed class FileLogger : ILogger
+    {
+        private readonly FileLoggerProvider provider;
+        private readonly string category;
+
+        public FileLogger(FileLoggerProvider provider, string category)
+        {
+            this.provider = provider;
+            this.category = category;
+        }
+
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+
+        public bool IsEnabled(LogLevel logLevel) => provider.IsEnabled(logLevel);
+
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state,
+            Exception? exception, Func<TState, Exception?, string> formatter)
+        {
+            if (!IsEnabled(logLevel))
+                return;
+            provider.Write(category, logLevel, formatter(state, exception), exception);
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/ICollector.cs

@@ -0,0 +1,24 @@
+namespace ShopDbEndpointAgent.Core;
+
+// The collection surface. The runtime worker depends only on this, so the
+// concrete implementation (pure C# today, possibly C# + PowerShell utilities
+// later) can change without touching the worker or the HTTP client.
+public interface ICollector
+{
+    EndpointReport Collect(string agentVersion, bool adopt);
+}
+
+// The documented seam for site-provided PowerShell "agent utilities". The
+// agent configuration settings page (server-side, future) lets site staff load
+// their own .ps1 scripts as utilities; the runtime discovers them under the
+// configured utilities directory and merges their JSON output into the report.
+//
+// This iteration ships the interface and a discovery contract only - the
+// concrete runner is added when the settings page can push utilities down.
+public interface IAgentUtilityRunner
+{
+    // Run every discovered utility and return a map of utility name -> parsed
+    // JSON result, to be attached to the report. Never throws: a failing
+    // utility is logged and skipped so it cannot break the telemetry run.
+    IReadOnlyDictionary<string, object> RunAll(CancellationToken token);
+}

agent/ShopDbEndpointAgent.Core/InteractiveProcessLauncher.cs

@@ -0,0 +1,333 @@
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Launches a program in the ACTIVE CONSOLE USER'S session at that user's
+// integrity, from the agent's LocalSystem service (session 0).
+//
+// Why this exists: the agent runs as a session-0 service. A plain
+// Process.Start() there launches GUI apps (DncMain.exe, UDC.exe) onto the hidden
+// session-0 desktop, so the logged-in operator never sees a window even though
+// the process is running. process_start needs the app to appear on the user's
+// desktop, so we obtain the interactive user's token and CreateProcessAsUser.
+//
+// Elevation is deliberately NOT handled here: the process starts at the user's
+// normal (medium) integrity and CyberArk/EPM brokers any elevation afterward.
+//
+// Only process_start uses this. Stop/status/service actions stay as SYSTEM.
+public static class InteractiveProcessLauncher
+{
+    // TimedOut=true means the process launched fine but was still running when
+    // the caller's wait budget expired. It is deliberately NOT killed, so the
+    // work still completes; the caller just stops blocking on it.
+    public readonly record struct LaunchOutcome(
+        bool Launched, string? Error, int? ExitCode = null, bool TimedOut = false);
+
+    private const int TokenDuplicate = 0x0002;
+    private const int TokenQuery = 0x0008;
+    private const int TokenAssignPrimary = 0x0001;
+    private const int TokenAdjustPrivileges = 0x0020;
+    private const int TokenAdjustDefault = 0x0080;
+    private const int TokenAdjustSessionId = 0x0100;
+
+    private const uint CreateUnicodeEnvironment = 0x00000400;
+    private const uint CreateNoWindow = 0x08000000;
+
+    private const uint InvalidSessionId = 0xFFFFFFFF;
+
+    private const uint Infinite = 0xFFFFFFFF;
+
+    // WaitForSingleObject returns this when the budget expires with the handle
+    // still unsignalled.
+    private const uint WaitTimeout = 0x00000102;
+
+    // Returns Launched=true when CreateProcessAsUser succeeds. Never throws;
+    // failures come back as Launched=false with a descriptive Error so the
+    // caller can surface a clean CommandResult.
+    public static LaunchOutcome LaunchInActiveSession(
+        string applicationPath, string? workingDirectory)
+        => LaunchInActiveSession(applicationPath, null, workingDirectory);
+
+    // Overload that also passes a command line (arguments). When commandLine is
+    // supplied it is handed to CreateProcessAsUser as lpCommandLine with a null
+    // lpApplicationName so the arguments are honored; the executable is resolved
+    // from the command line's first token as usual.
+    //
+    // When waitForExit is true the launcher waits for the process to exit and
+    // returns its real exit code in LaunchOutcome.ExitCode, so a caller that
+    // needs the actual outcome (run_script in the user session) can report
+    // completed/failed instead of fire-and-forget "launched". GUI callers
+    // (process_start) leave it false and return as soon as the window is up.
+    //
+    // waitTimeout bounds that wait. This matters because the caller may be the
+    // telemetry loop, and telemetry IS the heartbeat: a script that hangs in the
+    // user session used to block here forever (the wait was hardcoded to
+    // Infinite), which would stall reporting and make a perfectly healthy PC
+    // read as offline in the WebUI. On expiry the child is left running and the
+    // outcome comes back with TimedOut=true. Null means wait forever and should
+    // only be used by a caller that is not on a timed path.
+    public static LaunchOutcome LaunchInActiveSession(
+        string applicationPath, string? arguments, string? workingDirectory,
+        bool waitForExit = false, TimeSpan? waitTimeout = null)
+    {
+        var sessionId = WTSGetActiveConsoleSessionId();
+        if (sessionId == InvalidSessionId)
+            return new LaunchOutcome(false,
+                "No active console session (no interactive user is signed in).");
+
+        if (!WTSQueryUserToken(sessionId, out var userToken))
+            return new LaunchOutcome(false,
+                "Could not obtain the interactive user token (WTSQueryUserToken failed): "
+                + new Win32Exception(Marshal.GetLastWin32Error()).Message);
+
+        var duplicatedToken = IntPtr.Zero;
+        var environmentBlock = IntPtr.Zero;
+        try
+        {
+            var desiredAccess = TokenAssignPrimary | TokenDuplicate | TokenQuery
+                | TokenAdjustPrivileges | TokenAdjustDefault | TokenAdjustSessionId;
+            if (!DuplicateTokenEx(userToken, (uint)desiredAccess, IntPtr.Zero,
+                    SecurityImpersonationLevel.SecurityImpersonation,
+                    TokenType.TokenPrimary, out duplicatedToken))
+            {
+                return new LaunchOutcome(false,
+                    "Could not duplicate the user token (DuplicateTokenEx failed): "
+                    + new Win32Exception(Marshal.GetLastWin32Error()).Message);
+            }
+
+            // A per-user environment block so the launched app sees the user's
+            // profile variables rather than SYSTEM's.
+            if (!CreateEnvironmentBlock(out environmentBlock, duplicatedToken, false))
+                environmentBlock = IntPtr.Zero;
+
+            var startupInfo = new STARTUPINFO();
+            startupInfo.cb = Marshal.SizeOf(startupInfo);
+            // Target the interactive desktop so the window is visible.
+            startupInfo.lpDesktop = @"winsta0\default";
+
+            var creationFlags = CreateUnicodeEnvironment | CreateNoWindow;
+
+            // With arguments, pass a single command line ("<exe> <args>") as
+            // lpCommandLine and a null lpApplicationName so the arguments apply;
+            // without arguments, keep the original applicationName form.
+            string? applicationName;
+            string? commandLine;
+            if (string.IsNullOrWhiteSpace(arguments))
+            {
+                applicationName = applicationPath;
+                commandLine = null;
+            }
+            else
+            {
+                applicationName = null;
+                commandLine = "\"" + applicationPath + "\" " + arguments;
+            }
+
+            var launched = CreateProcessAsUser(
+                duplicatedToken,
+                applicationName,
+                commandLine,
+                IntPtr.Zero,
+                IntPtr.Zero,
+                false,
+                creationFlags,
+                environmentBlock,
+                workingDirectory,
+                ref startupInfo,
+                out var processInformation);
+
+            if (!launched)
+            {
+                return new LaunchOutcome(false,
+                    "CreateProcessAsUser failed: "
+                    + new Win32Exception(Marshal.GetLastWin32Error()).Message);
+            }
+
+            int? exitCode = null;
+            bool timedOut = false;
+            if (waitForExit && processInformation.hProcess != IntPtr.Zero)
+            {
+                uint milliseconds = waitTimeout is TimeSpan budget
+                    ? (uint)Math.Clamp(budget.TotalMilliseconds, 0, uint.MaxValue - 1)
+                    : Infinite;
+
+                if (WaitForSingleObject(processInformation.hProcess, milliseconds)
+                    == WaitTimeout)
+                {
+                    // Still running. Leave it alone - killing it would abandon
+                    // half-done work, and a file-spooling probe will still write
+                    // its result for the next cycle to pick up.
+                    timedOut = true;
+                }
+                else if (GetExitCodeProcess(processInformation.hProcess, out var code))
+                {
+                    exitCode = unchecked((int)code);
+                }
+            }
+
+            if (processInformation.hProcess != IntPtr.Zero)
+                CloseHandle(processInformation.hProcess);
+            if (processInformation.hThread != IntPtr.Zero)
+                CloseHandle(processInformation.hThread);
+
+            return new LaunchOutcome(true, null, exitCode, timedOut);
+        }
+        finally
+        {
+            if (environmentBlock != IntPtr.Zero)
+                DestroyEnvironmentBlock(environmentBlock);
+            if (duplicatedToken != IntPtr.Zero)
+                CloseHandle(duplicatedToken);
+            if (userToken != IntPtr.Zero)
+                CloseHandle(userToken);
+        }
+    }
+
+    // Profile directory of the active console user, for example
+    // C:\Users\ShopFloor. The agent runs as LocalSystem, so expanding
+    // %USERPROFILE% here would return SYSTEM's own profile under
+    // config\systemprofile rather than the operator's. The interactive user's
+    // token is the only reliable source, and this class already knows how to
+    // obtain it. Returns null with a reason when nobody is signed in.
+    public static string? TryGetActiveUserProfileDirectory(out string? error)
+    {
+        var sessionId = WTSGetActiveConsoleSessionId();
+        if (sessionId == InvalidSessionId)
+        {
+            error = "No active console session (no interactive user is signed in).";
+            return null;
+        }
+
+        if (!WTSQueryUserToken(sessionId, out var userToken))
+        {
+            error = "Could not obtain the interactive user token: "
+                + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+            return null;
+        }
+
+        try
+        {
+            uint size = 0;
+            GetUserProfileDirectory(userToken, null, ref size);
+            if (size == 0)
+            {
+                error = "Could not size the user profile directory: "
+                    + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+                return null;
+            }
+
+            var buffer = new StringBuilder((int)size);
+            if (!GetUserProfileDirectory(userToken, buffer, ref size))
+            {
+                error = "Could not resolve the user profile directory: "
+                    + new Win32Exception(Marshal.GetLastWin32Error()).Message;
+                return null;
+            }
+
+            error = null;
+            return buffer.ToString();
+        }
+        finally
+        {
+            if (userToken != IntPtr.Zero)
+                CloseHandle(userToken);
+        }
+    }
+
+    private enum SecurityImpersonationLevel
+    {
+        SecurityAnonymous,
+        SecurityIdentification,
+        SecurityImpersonation,
+        SecurityDelegation,
+    }
+
+    private enum TokenType
+    {
+        TokenPrimary = 1,
+        TokenImpersonation,
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct PROCESS_INFORMATION
+    {
+        public IntPtr hProcess;
+        public IntPtr hThread;
+        public uint dwProcessId;
+        public uint dwThreadId;
+    }
+
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    private struct STARTUPINFO
+    {
+        public int cb;
+        public string? lpReserved;
+        public string? lpDesktop;
+        public string? lpTitle;
+        public uint dwX;
+        public uint dwY;
+        public uint dwXSize;
+        public uint dwYSize;
+        public uint dwXCountChars;
+        public uint dwYCountChars;
+        public uint dwFillAttribute;
+        public uint dwFlags;
+        public ushort wShowWindow;
+        public ushort cbReserved2;
+        public IntPtr lpReserved2;
+        public IntPtr hStdInput;
+        public IntPtr hStdOutput;
+        public IntPtr hStdError;
+    }
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern uint WTSGetActiveConsoleSessionId();
+
+    [DllImport("wtsapi32.dll", SetLastError = true)]
+    private static extern bool WTSQueryUserToken(uint sessionId, out IntPtr token);
+
+    [DllImport("advapi32.dll", SetLastError = true)]
+    private static extern bool DuplicateTokenEx(
+        IntPtr existingToken,
+        uint desiredAccess,
+        IntPtr tokenAttributes,
+        SecurityImpersonationLevel impersonationLevel,
+        TokenType tokenType,
+        out IntPtr newToken);
+
+    [DllImport("userenv.dll", SetLastError = true)]
+    private static extern bool CreateEnvironmentBlock(
+        out IntPtr environment, IntPtr token, bool inherit);
+
+    [DllImport("userenv.dll", SetLastError = true)]
+    private static extern bool DestroyEnvironmentBlock(IntPtr environment);
+
+    [DllImport("userenv.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+    private static extern bool GetUserProfileDirectory(
+        IntPtr token, StringBuilder? profileDirectory, ref uint size);
+
+    [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+    private static extern bool CreateProcessAsUser(
+        IntPtr token,
+        string? applicationName,
+        string? commandLine,
+        IntPtr processAttributes,
+        IntPtr threadAttributes,
+        bool inheritHandles,
+        uint creationFlags,
+        IntPtr environment,
+        string? currentDirectory,
+        ref STARTUPINFO startupInfo,
+        out PROCESS_INFORMATION processInformation);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool CloseHandle(IntPtr handle);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool GetExitCodeProcess(IntPtr process, out uint exitCode);
+}

agent/ShopDbEndpointAgent.Core/LaunchPathPolicy.cs

@@ -0,0 +1,238 @@
+using System.Text.Json.Serialization;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Guards server-provisioned launch paths. Historically the command wire never
+// carried a launch path at all - the agent mapped an image name to a known-good
+// local path and anything else failed closed. Server-provisioned monitors now
+// MAY carry a path a site leader set in the WebUI, which is a deliberate
+// relaxation of that invariant. This policy is the replacement safeguard: a
+// server path is only honored when it sits under an approved root, actually
+// exists, and is an approved executable type. Everything else is rejected and
+// the agent falls back to its local launch map (still fail closed).
+//
+// The approved-root list is org-opinionated with shipped defaults (the Windows
+// Program Files roots), overridable per site via AgentConfig.ApprovedLaunchRoots
+// so the future Site Agent Configuration tool can widen or narrow it without a
+// rebuild. A local appsettings.json launchpaths entry still wins over any
+// server path, so a site pin is never silently overridden.
+public sealed class LaunchPathPolicy
+{
+    // Only these extensions are launchable. .bat is included because some shop-
+    // floor apps ship a launcher script (see the eDNC/UDC run.bat pattern).
+    private static readonly string[] ApprovedExtensions =
+        { ".exe", ".bat", ".cmd" };
+
+    // Shipped org defaults: the standard 64- and 32-bit install roots. Resolved
+    // from the environment so a non-C: system drive still matches.
+    public static IReadOnlyList<string> DefaultApprovedRoots { get; } =
+        BuildDefaultRoots();
+
+    private readonly IReadOnlyList<string> approvedRoots;
+
+    public LaunchPathPolicy(IEnumerable<string>? approvedRootsOverride = null)
+    {
+        var roots = (approvedRootsOverride ?? Enumerable.Empty<string>())
+            .Where(root => !string.IsNullOrWhiteSpace(root))
+            .Select(NormalizeRoot)
+            .ToList();
+        approvedRoots = roots.Count > 0 ? roots : DefaultApprovedRoots;
+    }
+
+    // Result of validating a candidate path: the normalized full path when it is
+    // acceptable, or a human-readable reason when it is rejected.
+    public bool TryValidate(string? candidate, out string fullPath, out string reason)
+    {
+        fullPath = "";
+        reason = "";
+
+        if (string.IsNullOrWhiteSpace(candidate))
+        {
+            reason = "empty path";
+            return false;
+        }
+
+        string resolved;
+        try
+        {
+            resolved = Path.GetFullPath(candidate.Trim());
+        }
+        catch (Exception ex)
+        {
+            reason = $"not a valid path: {ex.Message}";
+            return false;
+        }
+
+        // Reject an alternate data stream before anything else looks at the
+        // path. On .NET Framework an interior colon made GetFullPath throw; on
+        // net8.0 it does not, so "readme.txt:payload.exe" survives, reports an
+        // .exe extension, passes the root check, and File.Exists returns true
+        // for the stream. CreateProcess will run it. Write access to any
+        // existing file under an approved root would otherwise be enough.
+        var lastSegment = Path.GetFileName(resolved);
+        if (lastSegment.Contains(':'))
+        {
+            reason = "path names an alternate data stream";
+            return false;
+        }
+
+        var extension = Path.GetExtension(resolved);
+        if (!ApprovedExtensions.Contains(extension, StringComparer.OrdinalIgnoreCase))
+        {
+            reason = $"extension '{extension}' is not launchable";
+            return false;
+        }
+
+        if (!IsUnderApprovedRoot(resolved))
+        {
+            reason = "path is outside every approved launch root";
+            return false;
+        }
+
+        if (!File.Exists(resolved))
+        {
+            reason = "file does not exist";
+            return false;
+        }
+
+        // Everything above is LEXICAL: GetFullPath is pure string normalization
+        // and never touches the disk, so the root check so far constrains the
+        // name, not the file. File.Exists follows reparse points, which means a
+        // junction anywhere under an approved root pointed the check at one
+        // place and the execution at another. Creating a junction needs no
+        // privilege, only write access to the parent - and vendor install trees
+        // under Program Files are not reliably locked down.
+        //
+        // So resolve what the path actually refers to and re-check THAT. A
+        // resolve failure rejects: this is the last gate before the agent runs
+        // the file.
+        string finalPath;
+        try
+        {
+            finalPath = ResolveFinalPath(resolved);
+        }
+        catch (Exception ex)
+        {
+            reason = $"cannot resolve the real path: {ex.Message}";
+            return false;
+        }
+
+        if (!IsUnderApprovedRoot(finalPath))
+        {
+            reason = "path resolves outside every approved launch root";
+            return false;
+        }
+
+        fullPath = finalPath;
+        return true;
+    }
+
+    // The path with every symlink and junction on it followed, so the caller
+    // checks the file that will actually execute. The leaf is resolved first,
+    // then the directory chain above it - a junction is usually placed on a
+    // DIRECTORY, so resolving only the leaf would miss the case this exists to
+    // catch.
+    private static string ResolveFinalPath(string resolved)
+    {
+        string? name;
+        try
+        {
+            name = System.IO.File.ResolveLinkTarget(resolved, returnFinalTarget: true)?.FullName;
+        }
+        catch
+        {
+            name = null;
+        }
+        if (!string.IsNullOrWhiteSpace(name))
+        {
+            // ResolveLinkTarget resolves the file itself; run it back through
+            // GetFullPath so the comparison sees the same shape as the roots.
+            return Path.GetFullPath(name);
+        }
+
+        // Not a link. Its directory chain still might be, so resolve that.
+        var directory = Path.GetDirectoryName(resolved);
+        if (string.IsNullOrEmpty(directory))
+            return resolved;
+        var realDirectory = ResolveDirectoryChain(directory);
+        return Path.GetFullPath(Path.Combine(realDirectory, Path.GetFileName(resolved)));
+    }
+
+    // Walk up the directory chain resolving any junction or symlink on it. A
+    // junction is usually placed on a DIRECTORY, not on the executable, so
+    // resolving only the leaf would miss the case this exists to catch.
+    private static string ResolveDirectoryChain(string directory)
+    {
+        // Stop at the volume root. Walking into it and asking whether "C:\" is
+        // a link throws DirectoryNotFoundException, which the caller turned
+        // into a rejection - so the first version of this rejected every
+        // legitimate path as well as the malicious ones. A fail-closed gate
+        // that also fails the normal case is just an outage. Caught in the VM,
+        // not here.
+        var parent = Path.GetDirectoryName(directory);
+        if (string.IsNullOrEmpty(parent) || parent == directory)
+            return directory;
+
+        var resolvedDirectory = TryResolveLink(directory);
+        if (resolvedDirectory is not null)
+            return resolvedDirectory;
+
+        var realParent = ResolveDirectoryChain(parent);
+        return realParent == parent
+            ? directory
+            : Path.Combine(realParent, Path.GetFileName(directory));
+    }
+
+    // A component's link target, or null when it is not a link OR cannot be
+    // asked. Never throws: "cannot tell" must not be reported as "is a link",
+    // and the caller re-checks the assembled path against the roots regardless,
+    // so an unresolvable component cannot widen what is accepted.
+    private static string? TryResolveLink(string path)
+    {
+        try
+        {
+            var target = System.IO.Directory
+                .ResolveLinkTarget(path, returnFinalTarget: true)?.FullName;
+            return string.IsNullOrWhiteSpace(target) ? null : target;
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private bool IsUnderApprovedRoot(string resolved)
+    {
+        foreach (var root in approvedRoots)
+        {
+            // Compare against root + separator so "C:\Program Files" does not
+            // also match "C:\Program FilesEvil\...". Case-insensitive on Windows.
+            var prefix = root.EndsWith(Path.DirectorySeparatorChar)
+                ? root
+                : root + Path.DirectorySeparatorChar;
+            if (resolved.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+        return false;
+    }
+
+    private static string NormalizeRoot(string root)
+    {
+        var full = Path.GetFullPath(root.Trim());
+        return full.TrimEnd(Path.DirectorySeparatorChar);
+    }
+
+    private static IReadOnlyList<string> BuildDefaultRoots()
+    {
+        var candidates = new[]
+        {
+            Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles),
+            Environment.GetFolderPath(Environment.SpecialFolder.ProgramFilesX86),
+        };
+        return candidates
+            .Where(path => !string.IsNullOrWhiteSpace(path))
+            .Select(NormalizeRoot)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .ToList();
+    }
+}

agent/ShopDbEndpointAgent.Core/OperatorReportPayload.cs

@@ -0,0 +1,52 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ShopDbEndpointAgent.Core;
+
+// The on-disk hand-off between the interactive tray (which captures the
+// operator's screen and notes) and the headless service binary (which holds the
+// collector key and performs the upload). The tray writes this JSON sidecar to a
+// per-run temp folder and invokes `shopdbagent.exe --report <path>`; the agent
+// reads it, uploads, and deletes the folder. Keeping the secret in the service
+// preserves the "tray never holds a credential" rule already used by --once.
+public sealed class OperatorReportPayload
+{
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = "Other (free text)";
+
+    [JsonPropertyName("details")]
+    public string Details { get; set; } = string.Empty;
+
+    // Absolute path to the captured PNG, or null when the operator declined a
+    // screenshot. Written by the tray into the interactive operator's
+    // %USERPROFILE%\ShopDBScreenshots folder and passed through as an absolute
+    // path; the agent reads it verbatim and never re-derives the location (as
+    // SYSTEM its own profile would resolve elsewhere).
+    [JsonPropertyName("screenshotpath")]
+    public string? ScreenshotPath { get; set; }
+
+    private static readonly JsonSerializerOptions Options = new()
+    {
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        WriteIndented = true,
+    };
+
+    public static void Write(string filePath, string reason, string details,
+        string? screenshotPath)
+    {
+        var payload = new OperatorReportPayload
+        {
+            Reason = reason,
+            Details = details,
+            ScreenshotPath = screenshotPath,
+        };
+        File.WriteAllText(filePath, JsonSerializer.Serialize(payload, Options));
+    }
+
+    public static OperatorReportPayload Read(string filePath)
+    {
+        var json = File.ReadAllText(filePath);
+        return JsonSerializer.Deserialize<OperatorReportPayload>(json, Options)
+            ?? throw new InvalidDataException("empty or invalid report payload");
+    }
+}

agent/ShopDbEndpointAgent.Core/PowerShellUtilityRunner.cs

@@ -0,0 +1,114 @@
+using System.Diagnostics;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Site-provided PowerShell "agent utilities" runner. Discovers *.ps1 under the
+// configured utilities directory and runs each with the OS powershell.exe,
+// parsing its stdout as JSON. This is the documented collection seam: the
+// future agent-configuration settings page lets site staff push their own
+// scripts down, and their JSON output is merged into the report under
+// `scheduledtasks`-adjacent extension keys without the runtime knowing what any
+// script means.
+//
+// Safety posture for this iteration:
+//   - Disabled unless a utilities directory is configured AND exists.
+//   - Each script is bounded by a timeout and its failure is isolated.
+//   - Output must be a single JSON value; non-JSON output is logged and dropped.
+// Script SIGNING/allow-listing is a rollout concern (code signing + Intune) and
+// is called out in the design doc; do not enable this in production until that
+// is in place.
+public sealed class PowerShellUtilityRunner : IAgentUtilityRunner
+{
+    private readonly string utilitiesPath;
+    private readonly ILogger<PowerShellUtilityRunner> logger;
+    private readonly TimeSpan perScriptTimeout;
+
+    public PowerShellUtilityRunner(string utilitiesPath,
+        ILogger<PowerShellUtilityRunner> logger, TimeSpan? perScriptTimeout = null)
+    {
+        this.utilitiesPath = utilitiesPath;
+        this.logger = logger;
+        this.perScriptTimeout = perScriptTimeout ?? TimeSpan.FromSeconds(30);
+    }
+
+    public IReadOnlyDictionary<string, object> RunAll(CancellationToken token)
+    {
+        var results = new Dictionary<string, object>();
+        if (string.IsNullOrWhiteSpace(utilitiesPath) || !Directory.Exists(utilitiesPath))
+            return results;
+
+        foreach (var script in Directory.EnumerateFiles(utilitiesPath, "*.ps1"))
+        {
+            token.ThrowIfCancellationRequested();
+            var name = Path.GetFileNameWithoutExtension(script);
+            try
+            {
+                var parsed = RunOne(script, token);
+                if (parsed is not null)
+                    results[name] = parsed;
+            }
+            catch (Exception error)
+            {
+                logger.LogWarning(error, "Agent utility {Utility} failed", name);
+            }
+        }
+        return results;
+    }
+
+    private object? RunOne(string scriptPath, CancellationToken token)
+    {
+        var start = new ProcessStartInfo
+        {
+            FileName = "powershell.exe",
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+        start.ArgumentList.Add("-NoProfile");
+        start.ArgumentList.Add("-NonInteractive");
+        start.ArgumentList.Add("-ExecutionPolicy");
+        start.ArgumentList.Add("Bypass");
+        start.ArgumentList.Add("-File");
+        start.ArgumentList.Add(scriptPath);
+
+        using var process = new Process { StartInfo = start };
+        if (!process.Start())
+            return null;
+
+        var stdout = process.StandardOutput.ReadToEnd();
+        var stderr = process.StandardError.ReadToEnd();
+
+        if (!process.WaitForExit((int)perScriptTimeout.TotalMilliseconds))
+        {
+            try { process.Kill(entireProcessTree: true); } catch { }
+            logger.LogWarning("Agent utility {Script} timed out", scriptPath);
+            return null;
+        }
+
+        if (process.ExitCode != 0)
+        {
+            logger.LogWarning("Agent utility {Script} exit {Code}: {Error}",
+                scriptPath, process.ExitCode, stderr.Trim());
+            return null;
+        }
+
+        stdout = stdout.Trim();
+        if (stdout.Length == 0)
+            return null;
+
+        try
+        {
+            using var document = JsonDocument.Parse(stdout);
+            return JsonSerializer.Deserialize<object>(stdout);
+        }
+        catch (JsonException)
+        {
+            logger.LogWarning("Agent utility {Script} produced non-JSON output",
+                scriptPath);
+            return null;
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/ScheduledTaskPolicy.cs

@@ -0,0 +1,159 @@
+namespace ShopDbEndpointAgent.Core;
+
+// Guards which registered scheduled tasks the scheduledtask_run action may
+// start. The wire carries a free-text task path (so the WebUI can expose it as
+// one field, and a site can widen the set without an agent rebuild); this
+// policy is the safeguard that makes that free text safe to honor.
+//
+// WHY THIS EXISTS AT ALL. The agent runs as SYSTEM. A scheduled task is an
+// INDIRECTION: the task path names a definition, and that definition chooses
+// what actually runs. So "start the task named X" is only as safe as the set of
+// X the agent will accept - an unconstrained task name would be a general-
+// purpose "run anything already registered on this box, as whatever context it
+// asked for" primitive. That is a materially bigger grant than any other
+// allowlisted action, and it would be invisible in the audit trail (the command
+// log would read "scheduledtask_run \Foo" no matter what \Foo does).
+//
+// WHAT THIS DOES AND DOES NOT BUY. A prefix allowlist stops a compromised or
+// misconfigured SERVER from starting arbitrary tasks on the fleet - that is the
+// threat it actually addresses, and it is the realistic one. It does NOT stop an
+// attacker who can already register or rewrite task definitions on the endpoint:
+// such an attacker can define a task under an approved prefix and have the agent
+// start it. That is accepted, because anyone who can write task definitions on a
+// box already has the privilege the task would grant them. Local task definition
+// ACLs, not this policy, are the control for that.
+//
+// The approved-prefix list ships with the Corporate Tools set and is overridable
+// per site via AgentConfig.ApprovedTaskPaths, matching the LaunchPathPolicy
+// pattern so the future Site Agent Configuration tool can narrow or widen it
+// without a rebuild.
+public sealed class ScheduledTaskPolicy
+{
+    // Shipped defaults: the Corporate Tools task set. Prefix entries end with a
+    // backslash and match a whole folder; entries without one match that exact
+    // task path only. Kept deliberately tight - widen per site, not here.
+    //
+    // The ShopDB-* entries are tasks ShopDB itself owns. They are separate task
+    // definitions from any corporate-initiated equivalent ON PURPOSE: a
+    // ShopDB-initiated Dell Command scan must write its results somewhere the
+    // agent's collector can attribute to ShopDB, rather than into whatever
+    // location a corporate-managed task already writes. Keeping the definitions
+    // distinct is what makes "who asked for this scan" answerable at all - see
+    // the note in commands.py about the DCU output path convention.
+    public static IReadOnlyList<string> DefaultApprovedTaskPaths { get; } = new[]
+    {
+        @"\ReportIP",
+        @"\SFLD-ApplyDSCConfig",
+        @"\SFLD - Consume Credentials",
+        @"\ShopDB-DellCommandScan",
+        @"\ShopDB-DellCommandUpdate",
+    };
+
+    private readonly IReadOnlyList<string> approvedPaths;
+
+    public ScheduledTaskPolicy(IEnumerable<string>? approvedPathsOverride = null)
+    {
+        var paths = (approvedPathsOverride ?? Enumerable.Empty<string>())
+            .Where(path => !string.IsNullOrWhiteSpace(path))
+            .Select(NormalizeTaskPath)
+            .ToList();
+        approvedPaths = paths.Count > 0 ? paths : DefaultApprovedTaskPaths;
+    }
+
+    // Validates a candidate task path. On success taskPath is the normalized
+    // path to hand to Task Scheduler; on failure reason explains the rejection
+    // so the command result tells the operator WHY rather than just "denied".
+    public bool TryValidate(string? candidate, out string taskPath, out string reason)
+    {
+        taskPath = "";
+        reason = "";
+
+        if (string.IsNullOrWhiteSpace(candidate))
+        {
+            reason = "empty task path";
+            return false;
+        }
+
+        var normalized = NormalizeTaskPath(candidate);
+
+        // Traversal in a task path is meaningless to Task Scheduler but very
+        // meaningful to a prefix check: "\Approved\..\Evil" starts with an
+        // approved prefix as a STRING while naming something else entirely.
+        // Reject rather than try to canonicalize it away.
+        if (normalized.Contains(".."))
+        {
+            reason = "task path contains a traversal segment";
+            return false;
+        }
+
+        // Control characters and quotes have no place in a task path and are the
+        // shape of an attempt to break out of the argument. The invocation uses
+        // ArgumentList (no shell, no string concatenation) so this is defense in
+        // depth rather than the primary control, but a task path that needs
+        // these is not a task path we should be starting.
+        foreach (var ch in normalized)
+        {
+            if (char.IsControl(ch) || ch == '"' || ch == '&' || ch == '|')
+            {
+                reason = "task path contains an illegal character";
+                return false;
+            }
+        }
+
+        if (!IsApproved(normalized))
+        {
+            reason = "task path is not in the approved task list";
+            return false;
+        }
+
+        taskPath = normalized;
+        return true;
+    }
+
+    // Task Scheduler paths are rooted and backslash-separated. Accept the
+    // operator writing "ReportIP", "\ReportIP", or "/ReportIP" and settle on the
+    // rooted form, so an allowlist entry does not hinge on how it was typed.
+    private static string NormalizeTaskPath(string path)
+    {
+        var trimmed = (path ?? "").Trim().Replace('/', '\\');
+        if (trimmed.Length == 0)
+            return "";
+        if (!trimmed.StartsWith('\\'))
+            trimmed = "\\" + trimmed;
+        // Collapse a trailing separator so "\Folder\" and "\Folder" compare
+        // equal as exact entries; prefix semantics are handled in IsApproved.
+        while (trimmed.Length > 1 && trimmed.EndsWith('\\'))
+            trimmed = trimmed[..^1];
+        return trimmed;
+    }
+
+    // An entry ending in a separator is a FOLDER prefix and matches anything
+    // beneath it; any other entry must match the whole task path exactly. The
+    // exact-match case is why "\Approved" does not silently authorize
+    // "\ApprovedEvil".
+    private bool IsApproved(string candidate)
+    {
+        foreach (var entry in approvedPaths)
+        {
+            if (entry.Length == 0)
+                continue;
+
+            var isFolderPrefix = entry.EndsWith('\\');
+            if (isFolderPrefix)
+            {
+                if (candidate.StartsWith(entry, StringComparison.OrdinalIgnoreCase))
+                    return true;
+                continue;
+            }
+
+            if (string.Equals(candidate, entry, StringComparison.OrdinalIgnoreCase))
+                return true;
+
+            // Allow the folder form without its trailing separator to still act
+            // as a folder: "\SFLD" approves "\SFLD\Thing" but never "\SFLDEvil".
+            if (candidate.StartsWith(entry + "\\", StringComparison.OrdinalIgnoreCase))
+                return true;
+        }
+        return false;
+    }
+}

agent/ShopDbEndpointAgent.Core/ShopDbEndpointAgent.Core.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+	<TargetFramework>net8.0-windows</TargetFramework>
+	<ImplicitUsings>enable</ImplicitUsings>
+	<Nullable>enable</Nullable>
+	<RootNamespace>ShopDbEndpointAgent.Core</RootNamespace>
+	<AssemblyName>ShopDbEndpointAgent.Core</AssemblyName>
+	<InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+
+  <ItemGroup>
+	<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0" />
+	<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
+	<PackageReference Include="Microsoft.Extensions.Options" Version="8.0.0" />
+	<PackageReference Include="Microsoft.Win32.Registry" Version="5.0.0" />
+	<PackageReference Include="System.Management" Version="8.0.0" />
+	<PackageReference Include="System.Diagnostics.EventLog" Version="8.0.0" />
+	<PackageReference Include="System.ServiceProcess.ServiceController" Version="8.0.0" />
+	<!-- EventWaitHandleAcl: creating the user-context refresh event with an
+		 explicit DACL. The service creates it as LocalSystem, and without a
+		 granted ACE the unelevated tray cannot open it. -->
+	<PackageReference Include="System.Threading.AccessControl" Version="8.0.0" />
+  </ItemGroup>
+
+</Project>

agent/ShopDbEndpointAgent.Core/TcpTableReader.cs

@@ -0,0 +1,128 @@
+using System.Net;
+using System.Runtime.InteropServices;
+
+namespace ShopDbEndpointAgent.Core;
+
+// TCP connection state with owning process ids, via GetExtendedTcpTable.
+//
+// Why P/Invoke instead of shelling out to netstat.exe: parsing netstat text
+// output means spawning a process on every telemetry tick and depending on the
+// column layout of a localized command. GetExtendedTcpTable is the API netstat
+// itself calls, returns process ids directly, and costs a single allocation.
+//
+// Listeners are the cheap, bounded half of this (a handful of rows, stable over
+// time) and ride the normal cadence. The full connection table is unbounded and
+// churns constantly, so it stays on-demand.
+public static class TcpTableReader
+{
+    private const int AF_INET = 2;
+    private const uint ERROR_INSUFFICIENT_BUFFER = 122;
+    private const int TCP_TABLE_OWNER_PID_ALL = 5;
+
+    public enum TcpState
+    {
+        Closed = 1,
+        Listen = 2,
+        SynSent = 3,
+        SynReceived = 4,
+        Established = 5,
+        FinWait1 = 6,
+        FinWait2 = 7,
+        CloseWait = 8,
+        Closing = 9,
+        LastAck = 10,
+        TimeWait = 11,
+        DeleteTcb = 12,
+    }
+
+    public readonly record struct TcpRow(
+        string LocalAddress,
+        int LocalPort,
+        string RemoteAddress,
+        int RemotePort,
+        TcpState State,
+        int ProcessId);
+
+    // Full IPv4 TCP table. Throws only on catastrophic interop failure; callers
+    // treat an empty list as "not observed".
+    public static List<TcpRow> GetTcpTable()
+    {
+        var rows = new List<TcpRow>();
+        var buffer = IntPtr.Zero;
+        var size = 0;
+
+        try
+        {
+            // First call sizes the buffer. It is expected to fail with
+            // INSUFFICIENT_BUFFER; anything else is a real error.
+            var result = GetExtendedTcpTable(
+                IntPtr.Zero, ref size, false, AF_INET, TCP_TABLE_OWNER_PID_ALL, 0);
+            if (result != ERROR_INSUFFICIENT_BUFFER && result != 0)
+                return rows;
+
+            buffer = Marshal.AllocHGlobal(size);
+            result = GetExtendedTcpTable(
+                buffer, ref size, false, AF_INET, TCP_TABLE_OWNER_PID_ALL, 0);
+            if (result != 0)
+                return rows;
+
+            var entryCount = Marshal.ReadInt32(buffer);
+            var rowSize = Marshal.SizeOf<MIB_TCPROW_OWNER_PID>();
+            var cursor = IntPtr.Add(buffer, 4);
+
+            for (var index = 0; index < entryCount; index++)
+            {
+                var row = Marshal.PtrToStructure<MIB_TCPROW_OWNER_PID>(cursor);
+                rows.Add(new TcpRow(
+                    FormatAddress(row.localAddress),
+                    FormatPort(row.localPort),
+                    FormatAddress(row.remoteAddress),
+                    FormatPort(row.remotePort),
+                    (TcpState)row.state,
+                    (int)row.owningProcessId));
+                cursor = IntPtr.Add(cursor, rowSize);
+            }
+        }
+        finally
+        {
+            if (buffer != IntPtr.Zero)
+                Marshal.FreeHGlobal(buffer);
+        }
+
+        return rows;
+    }
+
+    public static List<TcpRow> GetListeners()
+        => GetTcpTable().FindAll(row => row.State == TcpState.Listen);
+
+    private static string FormatAddress(uint address)
+        => new IPAddress(BitConverter.GetBytes(address)).ToString();
+
+    // The port arrives as a big-endian value packed into the low two bytes of a
+    // host-order uint, so the bytes must be swapped rather than simply cast.
+    private static int FormatPort(uint port)
+    {
+        var bytes = BitConverter.GetBytes(port);
+        return (bytes[0] << 8) | bytes[1];
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct MIB_TCPROW_OWNER_PID
+    {
+        public uint state;
+        public uint localAddress;
+        public uint localPort;
+        public uint remoteAddress;
+        public uint remotePort;
+        public uint owningProcessId;
+    }
+
+    [DllImport("iphlpapi.dll", SetLastError = true)]
+    private static extern uint GetExtendedTcpTable(
+        IntPtr tcpTable,
+        ref int size,
+        bool order,
+        int addressFamily,
+        int tableClass,
+        int reserved);
+}

agent/ShopDbEndpointAgent.Core/TelemetryWorker.cs

@@ -0,0 +1,260 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// The telemetry loop as a hosted BackgroundService. On first contact it sends
+// adopt=true (once) so the server's computers collector creates the PC; every
+// run after that omits adopt and relies on strict hostname resolution. Between
+// runs it waits the configured cadence plus/minus jitter so a fleet does not
+// report in lockstep (thundering herd).
+//
+// The worker never lets one bad run kill the loop: a transient failure is
+// already retried inside CollectorClient, and a permanent failure (bad key,
+// PC removed server-side) is logged and the loop simply waits for the next
+// cadence tick rather than hammering the server.
+public sealed class TelemetryWorker : BackgroundService
+{
+    // The one agent utility whose output is forwarded to the server today. The
+    // name is the .ps1 filename without its extension, which is how
+    // PowerShellUtilityRunner keys its results.
+    public const string DellUpdatesUtilityName = "shopdb-dellupdates";
+
+    private readonly ICollector collector;
+    private readonly CollectorClient client;
+    private readonly IAgentUtilityRunner? utilities;
+    private readonly AgentConfig config;
+    private readonly string agentVersion;
+    private readonly ILogger<TelemetryWorker> logger;
+    private readonly CollectSignal? collectSignal;
+    private readonly UserContextSpool? userContextSpool;
+    private readonly UserContextRefreshChannel? userContextRefresh;
+    private readonly Random jitter = new();
+
+    // How long to wait for the tray to answer a refresh request.
+    //
+    // Bounded, and bounded SHORT. Telemetry is this agent's liveness signal: a
+    // report that arrives with slightly stale mapped drives is a working
+    // endpoint, while a report that never arrives because we blocked on an
+    // absent tray is an endpoint that looks dead. The probe itself is a single
+    // short PowerShell run, so a tray that is alive answers well inside this;
+    // anything longer means nobody is home.
+    private static readonly TimeSpan UserContextRefreshTimeout = TimeSpan.FromSeconds(12);
+
+    // Poll interval while waiting for the stamp to advance. There is no
+    // completion signal coming back the other way - the tray's answer IS the
+    // rewritten spool file - so this is a poll by design, kept coarse enough to
+    // be free and fine enough not to add visible latency.
+    private static readonly TimeSpan UserContextPollInterval = TimeSpan.FromMilliseconds(400);
+
+    public TelemetryWorker(ICollector collector, CollectorClient client,
+        AgentConfig config, string agentVersion, ILogger<TelemetryWorker> logger,
+        IAgentUtilityRunner? utilities = null, CollectSignal? collectSignal = null,
+        UserContextSpool? userContextSpool = null,
+        UserContextRefreshChannel? userContextRefresh = null)
+    {
+        this.collector = collector;
+        this.client = client;
+        this.config = config;
+        this.agentVersion = agentVersion;
+        this.logger = logger;
+        this.utilities = utilities;
+        this.collectSignal = collectSignal;
+        this.userContextSpool = userContextSpool;
+        this.userContextRefresh = userContextRefresh;
+    }
+
+    // Request a tray-side re-probe and wait, briefly, for the spool to be
+    // rewritten. Never throws and never fails the run.
+    //
+    // The service does NOT collect session data itself and must not start doing
+    // so: mapped drives belong to the operator's logon token, and a LocalSystem
+    // probe reads a different, near-empty drive table. See the tombstone in
+    // Program.cs. This method is the entire service-side involvement - ask, then
+    // wait for the answer to appear on disk.
+    private async Task RefreshUserContextAsync(CancellationToken token)
+    {
+        if (userContextSpool is null || userContextRefresh is null
+            || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        var resultPath = userContextSpool.TryGetResultPath(out _);
+        if (resultPath is null)
+            return;
+
+        // Captured BEFORE the request so "advanced" is measured against what we
+        // would otherwise have reported. A missing spool reads as null, and any
+        // stamp at all then counts as progress - that is the first-probe case.
+        var before = userContextSpool.TryReadCollectedAt(resultPath);
+
+        if (!userContextRefresh.RequestRefresh())
+        {
+            // Could not signal at all. Note that the inverse does NOT mean a tray
+            // is listening: the channel opens-or-creates and does not hold the
+            // handle, so signalling into an empty machine succeeds by creating
+            // the event and finding nobody waiting on it. Detecting an absent
+            // tray is the timeout's job below, not this return value's.
+            logger.LogDebug(
+                "Could not request a user-context refresh; reporting the existing spool.");
+            return;
+        }
+
+        var deadline = DateTime.UtcNow + UserContextRefreshTimeout;
+        while (DateTime.UtcNow < deadline)
+        {
+            try
+            {
+                await Task.Delay(UserContextPollInterval, token);
+            }
+            catch (OperationCanceledException)
+            {
+                return;
+            }
+
+            var after = userContextSpool.TryReadCollectedAt(resultPath);
+            if (after is not null && (before is null || after > before))
+            {
+                logger.LogDebug(
+                    "User-context spool refreshed by the tray (collectedat={Stamp}).",
+                    after);
+                return;
+            }
+        }
+
+        // Timed out. Proceed anyway - deliberately. Session data is one card on
+        // one page; telemetry carries heartbeat, inventory, events and command
+        // results, and holding all of that hostage to a tray that did not answer
+        // in twelve seconds trades a small inaccuracy for a total outage.
+        logger.LogDebug(
+            "The tray did not refresh the user-context spool within {Timeout}; "
+            + "reporting with the existing session data.",
+            UserContextRefreshTimeout);
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation(
+            "Endpoint agent {Version} -> {BaseUrl}, cadence {Cadence}s +/-{Jitter}s",
+            agentVersion, config.BaseUrl, config.CadenceSeconds, config.JitterSeconds);
+
+        bool firstRun = true;
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            bool adopt = firstRun && config.AdoptOnFirstRun;
+            try
+            {
+                await RunOnceAsync(adopt, stoppingToken);
+                firstRun = false;
+            }
+            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+            {
+                break;
+            }
+            catch (CollectorException error) when (error.IsPermanent)
+            {
+                // Bad key or PC removed server-side: surface it, do not retry
+                // faster than cadence. If it was a first-run adopt, keep trying
+                // to adopt next tick (the operator may be provisioning the PC).
+                logger.LogError(error, "Permanent collector error; waiting for next cadence");
+            }
+            catch (Exception error)
+            {
+                logger.LogError(error, "Telemetry run failed");
+            }
+
+            try
+            {
+                if (collectSignal is not null)
+                {
+                    // Wake early if a command asked for an immediate re-collect,
+                    // otherwise fall through when the cadence delay elapses.
+                    bool woken = await collectSignal.WaitAsync(NextDelay(), stoppingToken);
+                    if (woken)
+                        logger.LogInformation("Off-cadence collect requested after a command");
+                }
+                else
+                {
+                    await Task.Delay(NextDelay(), stoppingToken);
+                }
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+        }
+
+        logger.LogInformation("Endpoint agent stopped");
+    }
+
+    // Public so a --once console run and future on-demand triggers can reuse the
+    // exact production collection path.
+    public async Task<CollectorResponse> RunOnceAsync(bool adopt, CancellationToken token)
+    {
+        // Refresh the watch list from server policy BEFORE collecting so a
+        // policy-attached monitor (added in the WebUI, never in appsettings.json)
+        // is enumerated and reported this cycle. Server entries merge over the
+        // local list; a failed fetch returns null and Merge keeps the local list,
+        // so monitoring never blanks on a transient blip.
+        var resolved = await client.FetchResolvedMonitorsAsync(
+            Environment.MachineName, token);
+        if (resolved is not null)
+        {
+            config.Monitors = MonitorConfig.Merge(config.Monitors, resolved);
+            logger.LogDebug(
+                "Watch list refreshed from policy: {Processes} process(es), {Services} service(s)",
+                config.Monitors.Processes.Length, config.Monitors.Services.Length);
+        }
+
+        // Ask the tray to re-probe session data and WAIT for it, before
+        // collecting. Ordering is the whole point: the collector reads the spool
+        // file, so a refresh that lands after Collect() is a refresh the server
+        // does not see until the NEXT cycle. That was the bug - "Send Status"
+        // and "Refresh Status" both re-sent a spool nobody had rewritten, so a
+        // drive the operator had just unmapped kept reporting OK for up to half
+        // an hour and no amount of clicking changed it.
+        await RefreshUserContextAsync(token);
+
+        var report = collector.Collect(agentVersion, adopt);
+
+        if (utilities is not null)
+        {
+            var extra = utilities.RunAll(token);
+            if (extra.Count > 0)
+                logger.LogDebug("Loaded {Count} agent utility result(s)", extra.Count);
+
+            // NARROW ON PURPOSE. The runner executes every .ps1 in the utilities
+            // directory, but only this one known key is attached to the report.
+            // Forwarding the whole dictionary would mean any script dropped into
+            // that directory starts uploading its output to the server on every
+            // cadence - see the signing caveat in PowerShellUtilityRunner's
+            // header. Widening this to the full map is the intended end state of
+            // the IAgentUtilityRunner seam, but it needs script signing or an
+            // allowlist first. Until then, add a key here per utility.
+            if (extra.TryGetValue(DellUpdatesUtilityName, out var dellUpdates))
+                report.DellUpdates = dellUpdates;
+        }
+
+        logger.LogInformation(
+            "Reporting (adopt={Adopt}) user={User} serial={Serial} events={Events}",
+            adopt, report.LoggedInUser, report.SerialNumber, report.Events?.Length ?? 0);
+
+        var result = await client.SendAsync(report, token);
+
+        logger.LogInformation("OK action={Action} assetid={AssetId} identity={Identity}",
+            result.Action, result.AssetId, result.IdentityValue);
+        foreach (var warning in result.Warnings ?? Array.Empty<string>())
+            logger.LogWarning("Server warning: {Warning}", warning);
+
+        return result;
+    }
+
+    private TimeSpan NextDelay()
+    {
+        int spread = Math.Max(0, config.JitterSeconds);
+        int offset = spread == 0 ? 0 : jitter.Next(-spread, spread + 1);
+        int seconds = Math.Max(1, config.CadenceSeconds + offset);
+        return TimeSpan.FromSeconds(seconds);
+    }
+}

agent/ShopDbEndpointAgent.Core/UserContextProbe.cs

@@ -0,0 +1,362 @@
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Collects the session-scoped data that does not exist in the agent's own
+// context, by running a short PowerShell probe IN THE CALLING PROCESS'S
+// SESSION and writing the result to the user's spool file.
+//
+// Collects only data that genuinely does not exist in the agent's own context:
+//   netuse       - mapped drives are per logon session; "net use" from
+//                  LocalSystem returns SYSTEM's (empty) mapping table, never the
+//                  operator's Z: to the file server.
+//   userlisteners- TCP listeners owned by the signed-in user's processes, which
+//                  is what identifies an operator-launched DNC or CMM listener.
+//   idleseconds  - GetLastInputInfo is per session, so session 0 cannot answer
+//                  it. Sampled at probe time only, so treat it as a coarse
+//                  "was anyone at the machine" signal, not live presence.
+//
+// This runs from `shopdbagent.exe --collect-usercontext`, which the tray - and
+// only the tray - invokes, because the tray is already running as the signed-in
+// operator. The service does NOT call this: it previously tried to descend into
+// the session with CreateProcessAsUser, which is the direction that has to
+// duplicate a token, is what endpoint protection watches for, and produced
+// nothing on a live endpoint. Nothing here crosses a privilege boundary now;
+// the probe simply runs as whoever the tray is.
+//
+// The script is embedded rather than shipped as a .ps1 so the probe cannot drift
+// from the agent binary or be tampered with on disk between cycles.
+public sealed class UserContextProbe
+{
+    // The spool directory is injected by BuildProbeScript rather than derived in
+    // the script, so the writer cannot disagree with the reader. See
+    // UserContextSpool.PinnedSpoolDirectory for why $env:USERPROFILE was wrong.
+    private const string SpoolDirectoryToken = "__SHOPDB_SPOOL_DIR__";
+
+    private const string ProbeScriptTemplate = """
+        $ErrorActionPreference = 'Stop'
+        $result = [ordered]@{}
+        # Injected by the agent from UserContextSpool.PinnedSpoolDirectory() so the
+        # writer and the reader resolve the same directory. Deliberately NOT
+        # $env:USERPROFILE: the tray can inherit another account's environment on a
+        # locked-down image, which silently wrote this file into the wrong profile.
+        $spool = '__SHOPDB_SPOOL_DIR__'
+        $target = Join-Path $spool 'usercontext.json'
+        $temporary = "$target.tmp"
+
+        try {
+            New-Item -ItemType Directory -Path $spool -Force | Out-Null
+
+            $netuse = @()
+            try {
+                Get-CimInstance -ClassName Win32_NetworkConnection -ErrorAction Stop |
+                    ForEach-Object {
+                        $netuse += [ordered]@{
+                            localname  = $_.LocalName
+                            remotename = $_.RemoteName
+                            status     = $_.Status
+                            username   = $_.UserName
+                            persistent = [bool]$_.Persistent
+                        }
+                    }
+            } catch {
+                $result['netuseerror'] = $_.Exception.Message
+            }
+            $result['netuse'] = $netuse
+
+            # Second, independent view of the same drives. Win32_NetworkConnection
+            # is the "net use" table and Get-SmbMapping is the SMB client's own,
+            # and they disagree: a share can be Unavailable in one and absent or
+            # OK in the other. Neither is authoritative, so both are reported as
+            # collected and the server decides what to show. Normalising them
+            # here would discard exactly the disagreement that is diagnostic.
+            $smbmapping = @()
+            try {
+                Get-SmbMapping -ErrorAction Stop |
+                    ForEach-Object {
+                        $smbmapping += [ordered]@{
+                            localpath  = $_.LocalPath
+                            remotepath = $_.RemotePath
+                            status     = [string]$_.Status
+                        }
+                    }
+            } catch {
+                # Absent on older builds and in some session types. A missing
+                # source is not a drive fault, so it is recorded and left out
+                # rather than reported as a failed mapping.
+                $result['smbmappingerror'] = $_.Exception.Message
+            }
+            $result['smbmapping'] = $smbmapping
+
+            $listeners = @()
+            try {
+                $ownprocesses = @{}
+                Get-Process -ErrorAction SilentlyContinue | ForEach-Object {
+                    $ownprocesses[$_.Id] = $_.ProcessName
+                }
+                Get-NetTCPConnection -State Listen -ErrorAction Stop |
+                    Where-Object { $ownprocesses.ContainsKey($_.OwningProcess) } |
+                    ForEach-Object {
+                        $listeners += [ordered]@{
+                            localaddress = $_.LocalAddress
+                            localport    = $_.LocalPort
+                            processid    = $_.OwningProcess
+                            processname  = $ownprocesses[$_.OwningProcess]
+                        }
+                    }
+            } catch {
+                $result['userlistenerserror'] = $_.Exception.Message
+            }
+            $result['userlisteners'] = $listeners
+
+            # Idle time must be measured inside the user's session:
+            # GetLastInputInfo is per session, so asking from the agent's
+            # session 0 would report the service's own idle time, which is
+            # meaningless. This is what distinguishes "powered on" from
+            # "someone is actually working at this machine".
+            try {
+                # Built as a single-quoted string rather than a here-string: a
+                # here-string terminator must sit at column 0, which cannot be
+                # expressed inside an indented C# raw string literal.
+                $signature = 'using System; using System.Runtime.InteropServices; ' +
+                    'public class ShopDbIdle { ' +
+                    '[StructLayout(LayoutKind.Sequential)] ' +
+                    'struct LASTINPUTINFO { public uint cbSize; public uint dwTime; } ' +
+                    '[DllImport("user32.dll")] ' +
+                    'static extern bool GetLastInputInfo(ref LASTINPUTINFO info); ' +
+                    'public static long IdleSeconds() { ' +
+                    'LASTINPUTINFO info = new LASTINPUTINFO(); ' +
+                    'info.cbSize = (uint)Marshal.SizeOf(info); ' +
+                    'if (!GetLastInputInfo(ref info)) return -1; ' +
+                    'return (long)((uint)Environment.TickCount - info.dwTime) / 1000; } }'
+                Add-Type -TypeDefinition $signature -ErrorAction Stop
+                $idle = [ShopDbIdle]::IdleSeconds()
+                if ($idle -ge 0) { $result['idleseconds'] = $idle }
+            } catch {
+                $result['idlesecondserror'] = $_.Exception.Message
+            }
+
+            $result['collectedat'] = (Get-Date).ToUniversalTime().ToString('o')
+            $result['username'] = $env:USERNAME
+
+            # Stamp the token's elevation state. The username alone does not
+            # settle it: the SAME account elevated and unelevated gets two
+            # different logon tokens and therefore two different drive tables,
+            # so a spool from an elevated ShopFloor session passes the account
+            # check while still reporting every drive as broken.
+            try {
+                $identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+                $principal = New-Object Security.Principal.WindowsPrincipal($identity)
+                $result['elevated'] = [bool] $principal.IsInRole(
+                    [Security.Principal.WindowsBuiltInRole]::Administrator)
+            } catch {
+                $result['elevatederror'] = $_.Exception.Message
+            }
+
+            # Write to a temporary name and rename into place, so the reader can
+            # never observe a half-written file and discard a good result.
+            $result | ConvertTo-Json -Depth 4 -Compress |
+                Set-Content -Path $temporary -Encoding UTF8 -NoNewline
+            Move-Item -Path $temporary -Destination $target -Force
+        } catch {
+            exit 1
+        }
+        exit 0
+        """;
+
+    // Substitute the resolved spool directory into the template. The path goes in
+    // as a PowerShell single-quoted literal, so an embedded quote is doubled and
+    // nothing else in the path is interpreted - backslashes and $ are literal
+    // inside single quotes, which is exactly what a Windows path needs.
+    private static string BuildProbeScript(string spoolDirectory)
+        => ProbeScriptTemplate.Replace(
+            SpoolDirectoryToken, spoolDirectory.Replace("'", "''"));
+
+    // How long the probe is allowed to take. Generous: this no longer runs on
+    // the telemetry path, so an unresponsive WMI call delays nothing but itself.
+    private static readonly TimeSpan ProbeTimeout = TimeSpan.FromSeconds(60);
+
+    // powershell.exe's exit code when it rejects its command line and prints
+    // usage instead of running anything. Named so the failure is recognisable.
+    private const int PowerShellStartupFailure = -196608;
+
+    private readonly ILogger<UserContextProbe> logger;
+
+    public UserContextProbe(ILogger<UserContextProbe> logger)
+    {
+        this.logger = logger;
+    }
+
+    // Run the probe in THIS process's session and write the spool file.
+    // Returns true only when the spool file is present on disk afterwards.
+    //
+    // Called from the --collect-usercontext entry point, which the tray runs as
+    // the signed-in operator. Never throws: this is background collection and a
+    // failure must not take the tray or the agent process down with it.
+    public bool Collect()
+    {
+        var spoolDirectory = UserContextSpool.PinnedSpoolDirectory();
+        var resultPath = UserContextSpool.PinnedResultPath();
+
+        try
+        {
+            // Logged before the launch, not after. When this goes wrong the
+            // interesting question is always "which directory did it target",
+            // and a failure later in this method must not take the answer with
+            // it.
+            logger.LogInformation(
+                "Running the user-context probe as {User}; spool target {Path}",
+                Environment.UserName, resultPath);
+
+            // The probe writes a .tmp beside the target and moves it into place,
+            // so the directory has to exist before powershell.exe starts. The
+            // script creates it too, but doing it here means a permission problem
+            // is reported by the agent with a real exception rather than showing
+            // up as an opaque non-zero exit code.
+            try
+            {
+                Directory.CreateDirectory(spoolDirectory);
+            }
+            catch (Exception error) when (error is IOException or UnauthorizedAccessException)
+            {
+                logger.LogWarning(error,
+                    "Could not create the user-context spool directory at {Directory}",
+                    spoolDirectory);
+                return false;
+            }
+            // Passed as -EncodedCommand rather than staged as a .ps1 and run with
+            // -File. The script used to be written into %TEMP% and executed from
+            // there, which put a dependency on that file still existing, and still
+            // being readable, at the moment powershell.exe started. On a hardened
+            // endpoint that window is not safe: endpoint protection quarantines a
+            // freshly written script in the temp directory between the write and
+            // the launch, and roaming/redirected profiles can make the path
+            // unusable outright.
+            //
+            // When powershell.exe cannot use its -File argument it prints its usage
+            // banner and exits -196608 (0xFFFD0000) WITHOUT running a single
+            // statement. That is a startup failure, not a script failure, so the
+            // script's own try/catch never runs, nothing is logged about drives,
+            // and the operator sees a silent "no mapped drives reported" while the
+            // log only shows the bare exit code. -EncodedCommand carries the script
+            // in the command line itself, so there is no file to lose and no
+            // execution-policy or quarantine step between us and the probe.
+            var encoded = Convert.ToBase64String(
+                System.Text.Encoding.Unicode.GetBytes(BuildProbeScript(spoolDirectory)));
+
+            var startInfo = new System.Diagnostics.ProcessStartInfo
+            {
+                FileName = "powershell.exe",
+                Arguments =
+                    "-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand "
+                    + encoded,
+                WorkingDirectory = Path.GetTempPath(),
+                UseShellExecute = false,
+                CreateNoWindow = true,
+            };
+
+            using var process = System.Diagnostics.Process.Start(startInfo);
+            if (process is null)
+            {
+                logger.LogWarning("The user-context probe could not be started.");
+                return false;
+            }
+
+            if (!process.WaitForExit((int)ProbeTimeout.TotalMilliseconds))
+            {
+                logger.LogWarning(
+                    "The user-context probe did not finish within {Seconds} seconds.",
+                    ProbeTimeout.TotalSeconds);
+                TryKill(process);
+                return false;
+            }
+
+            if (process.ExitCode != 0)
+            {
+                // 0xFFFD0000 is powershell.exe refusing its own command line and
+                // printing usage: the probe never ran. Called out by name because
+                // as a bare number it reads like a script error and sends the
+                // reader looking for a WMI or drive fault that is not there.
+                var detail = process.ExitCode == PowerShellStartupFailure
+                    ? " (powershell.exe rejected its command line; the probe did not run)"
+                    : string.Empty;
+                logger.LogWarning(
+                    "The user-context probe exited with code {ExitCode}.{Detail}",
+                    process.ExitCode, detail);
+                return false;
+            }
+
+            // Exit code 0 is necessary but NOT sufficient. The probe used to be
+            // trusted on its exit code alone, which meant a run that wrote its
+            // file into a different profile entirely still reported success - the
+            // log claimed a spool had been written for weeks while nothing was
+            // ever there. Confirm the file exists where the reader will look.
+            if (!File.Exists(resultPath))
+            {
+                logger.LogWarning(
+                    "The user-context probe reported success but no spool file is "
+                    + "present at {Path}.", resultPath);
+                return false;
+            }
+
+            // Byte count alone does not distinguish a healthy spool from a
+            // well-formed empty one, and "0 drives" is the exact symptom this
+            // whole path exists to diagnose. Summarising the contents means a
+            // single log line from any given task run answers whether the probe
+            // saw the operator's drives, without needing the spool itself.
+            var summary = SummariseSpool(resultPath);
+            logger.LogInformation(
+                "The user-context probe wrote {Bytes} bytes to {Path} as {User}: {Summary}",
+                new FileInfo(resultPath).Length, resultPath, Environment.UserName, summary);
+            return true;
+        }
+        catch (Exception exception)
+        {
+            logger.LogWarning(exception, "The user-context probe failed.");
+            return false;
+        }
+    }
+
+    // One-line description of what the probe actually captured, for the run log.
+    // Best-effort by design: this is diagnostic colour on an already-successful
+    // run, so a parse problem here must never turn that run into a failure.
+    private static string SummariseSpool(string resultPath)
+    {
+        try
+        {
+            using var document = System.Text.Json.JsonDocument.Parse(
+                File.ReadAllText(resultPath));
+            var root = document.RootElement;
+
+            static int CountOf(System.Text.Json.JsonElement root, string name) =>
+                root.TryGetProperty(name, out var value)
+                && value.ValueKind == System.Text.Json.JsonValueKind.Array
+                    ? value.GetArrayLength()
+                    : 0;
+
+            var user = root.TryGetProperty("username", out var stamped)
+                ? stamped.GetString()
+                : "(unstamped)";
+
+            return $"user={user} netuse={CountOf(root, "netuse")} "
+                + $"smbmapping={CountOf(root, "smbmapping")} "
+                + $"listeners={CountOf(root, "userlisteners")}";
+        }
+        catch (Exception)
+        {
+            return "(could not summarise)";
+        }
+    }
+
+    private void TryKill(System.Diagnostics.Process process)
+    {
+        try
+        {
+            process.Kill(entireProcessTree: true);
+        }
+        catch (Exception exception)
+        {
+            logger.LogDebug(exception, "Could not stop the timed-out user-context probe.");
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/UserContextRefreshChannel.cs

@@ -0,0 +1,179 @@
+using System.Runtime.Versioning;
+using System.Security.AccessControl;
+using System.Security.Principal;
+using System.Threading;
+
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// The service-to-tray request channel for an on-demand user-context refresh.
+//
+// WHY THIS EXISTS AT ALL. Mapped drives are a property of the operator's logon
+// token, not of the machine. The agent is a session-0 LocalSystem service, so it
+// CANNOT enumerate them - not by impersonation, not by CreateProcessAsUser, not
+// by starting the probe task itself. That approach was built once and reverted;
+// see the tombstone in Program.cs where UserContextProbe is deliberately kept
+// out of the service's DI container. The only process on the box that can see
+// the right drive table is one already running inside the operator's session:
+// the tray.
+//
+// So the service does not probe. It ASKS. This channel is the ask, and the
+// spool file remains the answer.
+//
+// WHY A NAMED EVENT rather than a pipe or a socket. The request carries no data
+// - it is a single bit, "please re-probe now" - and the reply already has a
+// transport (the spool file, whose collectedat stamp the service watches
+// advance). A kernel event is the smallest thing that crosses the session-0
+// boundary, needs no serialization, no port, no firewall rule, and no cleanup if
+// either side dies. A file-watcher trigger would also work but leaves litter on
+// disk when the service is killed mid-request.
+//
+// THE Global\ PREFIX IS LOAD-BEARING. Without it the name is scoped to the
+// caller's session, so the service (session 0) and the tray (session 1+) would
+// create two unrelated events with the same name and never see each other. That
+// failure is silent: both sides "work", nothing is ever refreshed.
+//
+// THE DACL IS ALSO LOAD-BEARING. The service creates the event as LocalSystem,
+// which by default produces an object a non-elevated user cannot even open. The
+// tray runs unelevated as ShopFloor by design (an ELEVATED tray is refused by
+// the probe, because it would read the wrong drive table). So the creator grants
+// Users explicit Synchronize + Modify rights, or the tray gets access-denied on
+// open and the refresh silently never happens.
+public sealed class UserContextRefreshChannel
+{
+    // Session-global so session 0 and the interactive session share one object.
+    public const string EventName = @"Global\ShopDbEndpointAgent.UserContextRefresh";
+
+    private readonly ILogger logger;
+
+    // Takes the base ILogger rather than ILogger<T>: both the service (generic
+    // host) and the tray (its own file-backed logger named "Tray") construct
+    // this, and the tray has no DI container to resolve a typed logger from.
+    public UserContextRefreshChannel(ILogger logger)
+    {
+        this.logger = logger;
+    }
+
+    // Signal the tray that a fresh probe is wanted.
+    //
+    // Returns false when the event could not be opened or created, which is the
+    // normal state on a machine with nobody signed in and no tray running. The
+    // caller treats that as "no refresh available" and reports what it already
+    // has - a stale mapped-drive list is worth strictly more than a missed
+    // heartbeat, because telemetry IS the liveness signal.
+    //
+    // AutoReset, so exactly one waiting tray is released per request and the
+    // event does not latch on for every subsequent listener iteration.
+    [SupportedOSPlatform("windows")]
+    public bool RequestRefresh()
+    {
+        try
+        {
+            using var handle = OpenOrCreate(out var created);
+            if (handle is null)
+                return false;
+
+            handle.Set();
+            logger.LogDebug(
+                "Requested a user-context refresh on {Event} (created={Created})",
+                EventName, created);
+            return true;
+        }
+        catch (Exception error)
+        {
+            // Never throws to the caller. This sits directly on the telemetry
+            // path, and a refresh is an enhancement to the report, not a
+            // precondition for sending it.
+            logger.LogDebug(error,
+                "Could not request a user-context refresh on {Event}", EventName);
+            return false;
+        }
+    }
+
+    // Tray side: block until the service asks for a refresh, the timeout expires,
+    // or the token is cancelled. Returns true only for an actual request.
+    [SupportedOSPlatform("windows")]
+    public bool WaitForRequest(TimeSpan timeout, CancellationToken token)
+    {
+        try
+        {
+            using var handle = OpenOrCreate(out _);
+            if (handle is null)
+                return false;
+
+            var index = WaitHandle.WaitAny(
+                new[] { handle, token.WaitHandle }, timeout);
+
+            // Index 1 is cancellation, WaitTimeout is the idle path; only index 0
+            // is a genuine request.
+            return index == 0;
+        }
+        catch (Exception error)
+        {
+            logger.LogDebug(error,
+                "Could not wait on the user-context refresh channel {Event}", EventName);
+            return false;
+        }
+    }
+
+    // Open the shared event, creating it if this process is first.
+    //
+    // Either side may start first - the service can boot before anyone signs in,
+    // and the tray can start before the service finishes initializing - so both
+    // sides use the same create-or-open call rather than designating an owner.
+    // Whoever wins applies the DACL; the loser opens the existing object.
+    [SupportedOSPlatform("windows")]
+    private EventWaitHandle? OpenOrCreate(out bool created)
+    {
+        created = false;
+        try
+        {
+            var security = new EventWaitHandleSecurity();
+
+            // BUILTIN\Users by SID, not by name: on a non-English Windows the
+            // group is not called "Users", and this agent ships to whatever
+            // locale the site runs. Same reasoning as the task registration.
+            var users = new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null);
+            security.AddAccessRule(new EventWaitHandleAccessRule(
+                users,
+                EventWaitHandleRights.Synchronize | EventWaitHandleRights.Modify,
+                AccessControlType.Allow));
+
+            // FullControl for SYSTEM and Administrators so the service retains
+            // ownership semantics regardless of which side created the object.
+            var system = new SecurityIdentifier(WellKnownSidType.LocalSystemSid, null);
+            security.AddAccessRule(new EventWaitHandleAccessRule(
+                system, EventWaitHandleRights.FullControl, AccessControlType.Allow));
+
+            var admins = new SecurityIdentifier(
+                WellKnownSidType.BuiltinAdministratorsSid, null);
+            security.AddAccessRule(new EventWaitHandleAccessRule(
+                admins, EventWaitHandleRights.FullControl, AccessControlType.Allow));
+
+            return EventWaitHandleAcl.Create(
+                initialState: false,
+                mode: EventResetMode.AutoReset,
+                name: EventName,
+                createdNew: out created,
+                eventSecurity: security);
+        }
+        catch (UnauthorizedAccessException)
+        {
+            // The object exists with a DACL that does not admit this caller.
+            // Retry read-side-only rights: the tray only ever needs to wait, and
+            // an event created by an older agent build may not grant Modify.
+            try
+            {
+                return EventWaitHandle.OpenExisting(EventName);
+            }
+            catch (Exception error)
+            {
+                logger.LogDebug(error,
+                    "The user-context refresh event {Event} exists but is not accessible",
+                    EventName);
+                return null;
+            }
+        }
+    }
+}

agent/ShopDbEndpointAgent.Core/UserContextSpool.cs

@@ -0,0 +1,389 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace ShopDbEndpointAgent.Core;
+
+// Reads the result file that the tray-run user-context probe writes into the
+// signed-in user's ShopDB spool folder.
+//
+// Why a file and not a return value: the agent is a session-0 LocalSystem
+// service, so anything session-scoped (mapped drives from "net use", per-user
+// network state) simply does not exist in its own context. The probe runs as the
+// operator under the tray, in a completely separate process with no pipe back to
+// the service. A file in the user's own profile is the handoff, and the user can
+// always write there without elevation.
+//
+// Freshness is judged from the 'collectedat' stamp inside the file, NOT by
+// deleting the file around each read. Writer and reader are now independent
+// processes on unrelated schedules, so a delete-then-read would race the tray
+// and usually destroy a perfectly good result before it was ever reported. The
+// file is therefore left alone and simply ignored once it ages out, which also
+// means a logged-off machine stops reporting session data instead of pinning the
+// last operator's mapped drives forever.
+public sealed class UserContextSpool
+{
+    public const string SpoolFolderName = "ShopDB";
+    public const string ResultFileName = "usercontext.json";
+
+    // The one definition of where the spool lives. Both the probe (writer) and
+    // this class (reader) call it, so the two can no longer disagree.
+    //
+    // The writer used to build its own path from $env:USERPROFILE while the
+    // reader used the pinned ShopFloor profile. On a locked-down image those are
+    // not the same directory - the tray is launched through explorer.exe by an
+    // elevated installer and can inherit another account's environment block, as
+    // the tray already documents for %TEMP%. The probe then wrote a perfectly
+    // good file into the wrong profile, exited 0, and the service found nothing:
+    // no spool ever appeared and no mapped drive was ever reported.
+    public static string PinnedSpoolDirectory()
+        => Path.Combine(FileLoggerProvider.ShopFloorProfileDirectory(), SpoolFolderName);
+
+    public static string PinnedResultPath()
+        => Path.Combine(PinnedSpoolDirectory(), ResultFileName);
+
+    // A probe result is small - a handful of mapped drives and listeners. A file
+    // larger than this is either corrupt or hostile, and we will not parse it.
+    private const long MaxResultBytes = 512 * 1024;
+
+    // A result older than this is treated as absent. Sized at roughly three tray
+    // probe intervals (30 min each), so a single missed run never blanks the card
+    // but genuinely stale session data retires quickly.
+    //
+    // This was 24h when the reader deleted the file after each read; the delete
+    // was doing the real retiring and the age check was only a backstop. Now that
+    // the spool persists, this value IS the staleness bound, so it is sized
+    // against the writer's cadence rather than the server's quiet-report window.
+    //
+    // Not read from the server: this is an offline-safe local bound, and the
+    // agent must retire stale session data even when it cannot reach ShopDB.
+    private static readonly TimeSpan MaxResultAge = TimeSpan.FromMinutes(90);
+
+    private readonly ILogger<UserContextSpool> logger;
+
+    public UserContextSpool(ILogger<UserContextSpool> logger)
+    {
+        this.logger = logger;
+    }
+
+    // Full path to the spool file. Fixed at C:\Users\ShopFloor\ShopDB, because
+    // every shop-floor endpoint signs in as the same local ShopFloor account.
+    //
+    // This used to be resolved through WTSQueryUserToken/GetUserProfileDirectory,
+    // and that lookup is precisely what fails on a hardened endpoint: querying
+    // another session's token is a privileged operation that endpoint protection
+    // blocks. When it failed the service simply reported "no session data" while
+    // the tray was writing a perfectly good file, so writer and reader silently
+    // disagreed about the location and the operator saw an empty card.
+    //
+    // The token lookup is kept ONLY as a fallback for a machine whose operator
+    // account is named something else. If both are unavailable there is no
+    // session data, which costs mapped drives and idle time but never affects
+    // telemetry, commands or inventory.
+    public string? TryGetResultPath(out string? reason)
+    {
+        var pinned = FileLoggerProvider.ShopFloorProfileDirectory();
+        if (Directory.Exists(pinned))
+        {
+            reason = null;
+            return PinnedResultPath();
+        }
+
+        var profileDirectory =
+            InteractiveProcessLauncher.TryGetActiveUserProfileDirectory(out var error);
+        if (string.IsNullOrWhiteSpace(profileDirectory))
+        {
+            reason = $"No {FileLoggerProvider.ShopFloorUserName} profile at {pinned}, "
+                + "and the interactive profile could not be resolved either: "
+                + (error ?? "unknown error");
+            return null;
+        }
+
+        reason = null;
+        return Path.Combine(profileDirectory, SpoolFolderName, ResultFileName);
+    }
+
+    // Remove a result file. Only used to discard one that is corrupt or has aged
+    // out; a valid result is left in place for the next read.
+    public void ClearStaleResult(string resultPath)
+    {
+        try
+        {
+            if (File.Exists(resultPath))
+            {
+                File.Delete(resultPath);
+                logger.LogDebug(
+                    "Removed a stale user-context spool file at {Path}", resultPath);
+            }
+        }
+        catch (Exception exception)
+        {
+            // Not fatal on its own, but it does mean we cannot trust whatever we
+            // read next, so the caller must know.
+            logger.LogWarning(exception,
+                "Could not remove the stale user-context spool file at {Path}", resultPath);
+        }
+    }
+
+    public void EnsureSpoolDirectory(string resultPath)
+    {
+        var directory = Path.GetDirectoryName(resultPath);
+        if (string.IsNullOrWhiteSpace(directory))
+            return;
+
+        try
+        {
+            Directory.CreateDirectory(directory);
+        }
+        catch (Exception exception)
+        {
+            logger.LogWarning(exception,
+                "Could not create the user-context spool directory at {Directory}", directory);
+        }
+    }
+
+    // Read the probe result without consuming it. Returns null when there is no
+    // usable, sufficiently recent result, which the caller reports as "no session
+    // data this cycle" rather than as empty data - absent and empty mean
+    // different things here.
+    public Dictionary<string, object?>? TryReadResult(string resultPath)
+    {
+        try
+        {
+            if (!File.Exists(resultPath))
+                return null;
+
+            var info = new FileInfo(resultPath);
+            if (info.Length == 0)
+            {
+                logger.LogDebug("The user-context spool file was empty.");
+                return null;
+            }
+
+            if (info.Length > MaxResultBytes)
+            {
+                logger.LogWarning(
+                    "The user-context spool file was {Bytes} bytes, above the {Limit} byte "
+                        + "limit; discarding it.",
+                    info.Length, MaxResultBytes);
+                return null;
+            }
+
+            var json = File.ReadAllText(resultPath);
+            if (string.IsNullOrWhiteSpace(json))
+                return null;
+
+            var parsed = JsonSerializer.Deserialize<Dictionary<string, object?>>(json);
+            if (parsed is null || parsed.Count == 0)
+                return null;
+
+            if (IsExpired(parsed, resultPath))
+                return null;
+
+            if (IsWrongAccount(parsed))
+                return null;
+
+            if (IsElevatedCollection(parsed))
+                return null;
+
+            return parsed;
+        }
+        catch (JsonException exception)
+        {
+            // A truncated file is the expected shape of this failure: the probe
+            // was still writing when we looked. Next cycle gets a clean one.
+            logger.LogWarning(exception,
+                "The user-context spool file was not valid JSON; discarding it.");
+            return null;
+        }
+        catch (Exception exception)
+        {
+            logger.LogWarning(exception,
+                "Could not read the user-context spool file at {Path}", resultPath);
+            return null;
+        }
+    }
+
+    // Read the spool WITHOUT removing it. The probe overwrites the file on every
+    // run (write .tmp, move into place), so the newest result always replaces the
+    // previous one and there is nothing for the reader to clean up.
+    //
+    // This used to delete the file after a successful read, to stop a dead tray
+    // re-reporting the same drives forever. The collectedat age check already
+    // does that job, and deleting created a worse problem: lastUserContext in the
+    // collector is in-memory only, so a service restart wiped the cache while the
+    // spool had already been consumed. The agent then reported NO mapped drives
+    // until the tray's next probe - and the installer restarts the service and
+    // the tray on every install, so a fresh install was guaranteed to show an
+    // empty card at exactly the moment someone looked at it.
+    //
+    // The contents are the operator's own session data, visible to them in their
+    // own context, so leaving the file in place costs nothing.
+    public Dictionary<string, object?>? ConsumeResult(string resultPath)
+        => TryReadResult(resultPath);
+
+    // The collectedat stamp on disk, or null when there is no readable stamp.
+    //
+    // This is how the service PROVES a refresh actually happened rather than
+    // assuming it. Signalling the tray is asynchronous and the probe takes a
+    // second or two, so a caller that simply slept would either send the old
+    // spool anyway or pad the delay and hope. Watching this value advance past
+    // the pre-request stamp is the only honest way to know the file in front of
+    // us is the answer to OUR request and not the previous one.
+    //
+    // Deliberately NOT routed through TryReadResult: this must report the stamp
+    // of whatever is on disk, including a spool that is expired, elevated, or
+    // from the wrong account. Those are all rejected later for reporting, but
+    // for ordering we only care whether the file was rewritten - conflating "not
+    // usable" with "not fresh" would make the service wait out the full timeout
+    // on every cycle for a machine whose spool is being rejected for some other
+    // reason.
+    //
+    // Also deliberately NOT the file's LastWriteTime, for the reason IsExpired
+    // gives: a spool can be copied or restored with a roaming profile and carry
+    // a misleading filesystem timestamp. The stamp inside the file is written by
+    // the probe itself.
+    public DateTimeOffset? TryReadCollectedAt(string resultPath)
+    {
+        try
+        {
+            if (!File.Exists(resultPath))
+                return null;
+
+            var info = new FileInfo(resultPath);
+            if (info.Length == 0 || info.Length > MaxResultBytes)
+                return null;
+
+            var json = File.ReadAllText(resultPath);
+            if (string.IsNullOrWhiteSpace(json))
+                return null;
+
+            var parsed = JsonSerializer.Deserialize<Dictionary<string, object?>>(json);
+            if (parsed is null
+                || !parsed.TryGetValue("collectedat", out var raw)
+                || raw is null)
+            {
+                return null;
+            }
+
+            if (DateTimeOffset.TryParse(
+                    raw.ToString(),
+                    System.Globalization.CultureInfo.InvariantCulture,
+                    System.Globalization.DateTimeStyles.RoundtripKind,
+                    out var collectedat))
+            {
+                return collectedat;
+            }
+
+            return null;
+        }
+        catch (Exception exception)
+        {
+            // A torn read while the probe is mid-write is the expected failure
+            // here and is not worth a warning: the caller polls, so the next
+            // attempt a moment later sees the completed file.
+            logger.LogDebug(exception,
+                "Could not read the user-context collectedat stamp at {Path}", resultPath);
+            return null;
+        }
+    }
+
+    // Reject a spool that some other account produced.
+    //
+    // Pinning the path guarantees the file lands where the reader looks, but it
+    // cannot guarantee WHO ran the probe. Mapped drives and idle time are per
+    // logon session, so a probe that ran as an administrator (for example a tray
+    // that inherited an elevated installer's environment) would enumerate that
+    // account's drive table and write it into the operator's spool. That is worse
+    // than reporting nothing, because the card would look populated and correct
+    // while showing drives the operator does not have.
+    //
+    // The probe stamps $env:USERNAME into the file, so the mismatch is checkable.
+    // Logged at warning, not debug: this is a misconfigured endpoint, not a quiet
+    // absence of data.
+    private bool IsWrongAccount(Dictionary<string, object?> parsed)
+    {
+        if (!parsed.TryGetValue("username", out var raw) || raw is null)
+        {
+            logger.LogWarning(
+                "The user-context spool has no username stamp; ignoring it because "
+                + "the session it describes cannot be confirmed.");
+            return true;
+        }
+
+        var username = raw.ToString();
+        if (string.Equals(username, FileLoggerProvider.ShopFloorUserName,
+                StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        logger.LogWarning(
+            "The user-context spool was written by {Actual}, not {Expected}; "
+            + "ignoring it. Session data is per logon session, so this would "
+            + "report the wrong account's mapped drives.",
+            username, FileLoggerProvider.ShopFloorUserName);
+        return true;
+    }
+
+    // An elevated probe runs under a different logon token to the operator's
+    // interactive one and enumerates a different, usually empty, drive table.
+    // The agent refuses to collect while elevated, so a spool stamped elevated
+    // should not exist; this rejects any that predates that guard or arrives
+    // from a hand-run --collect-usercontext in an admin shell.
+    //
+    // Note the asymmetry with IsWrongAccount: a MISSING stamp is accepted here
+    // rather than rejected. An unstamped spool is simply one written by an older
+    // agent, and treating that as elevated would blank out session data across a
+    // fleet mid-upgrade. An unstamped spool has already had to pass the username
+    // check to reach this point.
+    private bool IsElevatedCollection(Dictionary<string, object?> parsed)
+    {
+        if (!parsed.TryGetValue("elevated", out var raw) || raw is null)
+            return false;
+
+        var elevated = raw is JsonElement element
+            ? element.ValueKind == JsonValueKind.True
+            : string.Equals(raw.ToString(), "true", StringComparison.OrdinalIgnoreCase);
+
+        if (!elevated)
+            return false;
+
+        logger.LogWarning(
+            "The user-context spool was collected by an ELEVATED process; ignoring "
+            + "it. Mapped drives are per logon token, so an elevated probe reports "
+            + "the wrong drive table even under the right account. Collection should "
+            + "come from the 'ShopDB user-context probe' scheduled task, which runs "
+            + "at RunLevel Limited.");
+        return true;
+    }
+
+    // Age is taken from the stamp the probe wrote, not from the file's last
+    // write time, because the file can be copied or restored with a roaming
+    // profile and carry a misleading timestamp. A result with no readable stamp
+    // is treated as expired: we cannot prove it is current, so we will not claim
+    // it is.
+    private bool IsExpired(Dictionary<string, object?> parsed, string resultPath)
+    {
+        if (!parsed.TryGetValue("collectedat", out var raw) || raw is null
+            || !DateTimeOffset.TryParse(
+                raw.ToString(),
+                System.Globalization.CultureInfo.InvariantCulture,
+                System.Globalization.DateTimeStyles.RoundtripKind,
+                out var collectedat))
+        {
+            logger.LogDebug(
+                "The user-context spool file has no usable collectedat stamp; ignoring it.");
+            return true;
+        }
+
+        var age = DateTimeOffset.UtcNow - collectedat;
+        if (age <= MaxResultAge)
+            return false;
+
+        logger.LogDebug(
+            "The user-context spool file is {Hours} hours old, past the {Limit} hour limit.",
+            Math.Round(age.TotalHours, 1), MaxResultAge.TotalHours);
+        ClearStaleResult(resultPath);
+        return true;
+    }
+}

agent/ShopDbEndpointAgent.PolicyProbe/Program.cs

@@ -0,0 +1,148 @@
+using ShopDbEndpointAgent.Core;
+
+// Planted-violation suite for LaunchPathPolicy, run on real Windows because the
+// cases that matter (junctions, alternate data streams, 8.3 names) are
+// filesystem behaviour, not string behaviour. Linux would prove nothing.
+//
+// Builds its own fixtures under an approved root, so it exercises the same
+// shape as a real shop-floor install rather than a synthetic path.
+
+int failures = 0;
+
+void Check(string label, bool expectAccept, string candidate, LaunchPathPolicy policy)
+{
+    var ok = policy.TryValidate(candidate, out var full, out var reason);
+    var pass = ok == expectAccept;
+    if (!pass) failures++;
+    var verdict = pass ? "PASS" : "FAIL";
+    var got = ok ? $"accepted -> {full}" : $"rejected ({reason})";
+    Console.WriteLine($"{verdict}  {label}");
+    Console.WriteLine($"        want={(expectAccept ? "accept" : "reject")}  got={got}");
+}
+
+var root = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles), "LppFixture");
+var outside = Path.Combine(Path.GetTempPath(), "LppOutside");
+Directory.CreateDirectory(root);
+Directory.CreateDirectory(outside);
+
+var policy = new LaunchPathPolicy(new[] { root });
+
+// A real executable inside the approved root.
+var good = Path.Combine(root, "good.exe");
+File.WriteAllBytes(good, new byte[] { 0x4D, 0x5A });
+
+// The payload the attacker wants run, planted OUTSIDE the approved root.
+var payload = Path.Combine(outside, "payload.exe");
+File.WriteAllBytes(payload, new byte[] { 0x4D, 0x5A });
+
+// A text file inside the root, to hang an alternate data stream off.
+var carrier = Path.Combine(root, "readme.txt");
+File.WriteAllText(carrier, "notes");
+
+Console.WriteLine($"approved root : {root}");
+Console.WriteLine($"outside dir   : {outside}");
+Console.WriteLine();
+
+Check("a real exe under the approved root", true, good, policy);
+Check("wrong extension", false, carrier, policy);
+Check("file that does not exist", false, Path.Combine(root, "nope.exe"), policy);
+Check("traversal back out of the root", false,
+      Path.Combine(root, "..", "..", "Windows", "System32", "cmd.exe"), policy);
+Check("UNC path", false, @"\\attacker\share\payload.exe", policy);
+Check("sibling directory sharing the root's prefix", false, root + "Evil\\payload.exe", policy);
+Check("empty path", false, "", policy);
+
+// --- alternate data stream --------------------------------------------------
+try
+{
+    File.WriteAllBytes(carrier + ":payload.exe", new byte[] { 0x4D, 0x5A });
+    Check("alternate data stream on a file in the root", false,
+          carrier + ":payload.exe", policy);
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"SKIP  alternate data stream fixture: {ex.Message}");
+}
+
+// --- directory junction out of the root ------------------------------------
+var junction = Path.Combine(root, "logs");
+var mk = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo
+{
+    FileName = "cmd.exe",
+    Arguments = $"/c mklink /J \"{junction}\" \"{outside}\"",
+    UseShellExecute = false, RedirectStandardOutput = true, RedirectStandardError = true,
+});
+mk!.WaitForExit();
+if (mk.ExitCode == 0)
+{
+    Check("exe reached through a junction pointing out of the root", false,
+          Path.Combine(junction, "payload.exe"), policy);
+}
+else
+{
+    Console.WriteLine($"SKIP  junction fixture: mklink exit {mk.ExitCode} {mk.StandardError.ReadToEnd().Trim()}");
+}
+
+// --- 8.3 short name ---------------------------------------------------------
+// 8.3 short names used to be rejected, because the lexical prefix check could
+// not match "C:\PROGRA~1" against "C:\Program Files" - fail closed, but only by
+// accident of not understanding the path. Resolution now expands it to the real
+// directory, which IS under the approved root, so accepting is correct: the
+// check that matters runs on the resolved path either way.
+var shortRoot = Path.Combine(@"C:\PROGRA~1", "LppFixture", "good.exe");
+Check("8.3 short name resolving into the approved root", true, shortRoot, policy);
+
+// --- ScheduledTaskPolicy ----------------------------------------------------
+// Pure string logic, unlike LaunchPathPolicy: a task path names an entry in the
+// Task Scheduler namespace, not a file, so there is no disk state to plant. The
+// cases that matter are the ones where a candidate LOOKS like an approved entry
+// as a string but is not the same task.
+
+void CheckTask(string label, bool expectAccept, string candidate, ScheduledTaskPolicy policy)
+{
+    var ok = policy.TryValidate(candidate, out var full, out var reason);
+    var pass = ok == expectAccept;
+    if (!pass) failures++;
+    var verdict = pass ? "PASS" : "FAIL";
+    var got = ok ? $"accepted -> {full}" : $"rejected ({reason})";
+    Console.WriteLine($"{verdict}  {label}");
+    Console.WriteLine($"        want={(expectAccept ? "accept" : "reject")}  got={got}");
+}
+
+Console.WriteLine();
+Console.WriteLine("--- ScheduledTaskPolicy ---");
+
+var taskPolicy = new ScheduledTaskPolicy(new[] { @"\ReportIP", @"\SFLD\" });
+
+CheckTask("exact approved task", true, @"\ReportIP", taskPolicy);
+// Task Scheduler is case-insensitive, so the policy must be too, or the same
+// task typed differently would be refused.
+CheckTask("approved task, different case", true, @"\reportip", taskPolicy);
+// The operator should not have to know the rooted form.
+CheckTask("approved task without leading separator", true, "ReportIP", taskPolicy);
+CheckTask("approved task with forward slashes", true, "/ReportIP", taskPolicy);
+// The prefix-suffix confusion this policy exists to prevent: "\ReportIP" must
+// NOT authorize "\ReportIPEvil".
+CheckTask("sibling task sharing an approved prefix", false, @"\ReportIPEvil", taskPolicy);
+CheckTask("unapproved task", false, @"\Evil", taskPolicy);
+CheckTask("empty task path", false, "", taskPolicy);
+// Folder entries authorize everything beneath them, but not a sibling folder
+// whose name merely starts the same way.
+CheckTask("task inside an approved folder", true, @"\SFLD\ApplyDSCConfig", taskPolicy);
+CheckTask("folder itself", true, @"\SFLD", taskPolicy);
+CheckTask("sibling folder sharing the prefix", false, @"\SFLDEvil\Thing", taskPolicy);
+// Traversal would let an approved prefix string-match something else entirely.
+CheckTask("traversal out of an approved folder", false, @"\SFLD\..\Evil", taskPolicy);
+// Defense in depth: the invocation uses ArgumentList, but a task path with
+// these characters is not one we should be starting.
+CheckTask("argument-injection characters", false, "\\ReportIP\" & calc", taskPolicy);
+CheckTask("control character", false, "\\Report\u0000IP", taskPolicy);
+// An empty override must fall back to the shipped defaults, never to "allow
+// everything".
+var defaultPolicy = new ScheduledTaskPolicy(Array.Empty<string>());
+CheckTask("shipped default is honored when override is empty", true, @"\ReportIP", defaultPolicy);
+CheckTask("empty override does not mean allow-all", false, @"\Evil", defaultPolicy);
+
+Console.WriteLine();
+Console.WriteLine(failures == 0 ? "ALL EXPECTATIONS MET" : $"{failures} EXPECTATION(S) NOT MET");
+return failures == 0 ? 0 : 1;

agent/ShopDbEndpointAgent.PolicyProbe/README.md

@@ -0,0 +1,33 @@
+# LaunchPathPolicy probe
+
+A planted-violation probe for `LaunchPathPolicy`. It builds real fixtures under
+a real approved root - a junction pointing out of it, an alternate data stream,
+an 8.3 short name - and asserts what the policy does with each.
+
+## Why it is not a unit test in CI
+
+The cases worth testing are filesystem behaviour, not string behaviour:
+junctions, alternate data streams and 8.3 short names do not exist on Linux, and
+CI runs on Linux runners. A suite that skipped every meaningful case there would
+report green and mean nothing, which is the failure shape this repo has already
+been bitten by more than once. So it is a probe you run on Windows, by hand,
+when the policy changes.
+
+## Running it
+
+Publish from the dev box and run it in the win11 VM:
+
+    dotnet publish agent/ShopDbEndpointAgent.PolicyProbe -c Release -r win-x64 \
+        --self-contained true -p:PublishSingleFile=true -o /tmp/lpp
+
+Copy `lpp/lpptest.exe` into the VM and run it as an account that may create a
+junction under Program Files. Exit code 0 means every expectation held; it
+prints one line per case either way.
+
+## What it caught
+
+The first version of the link-resolving hardening recursed to the volume root
+and asked whether `C:\` was a link. That throws, and the caller treated a
+resolve failure as a rejection - so the policy rejected every legitimate launch
+path as well as the malicious ones. It compiled cleanly and read correctly. Only
+running it on Windows showed the agent would have failed closed on everything.

agent/ShopDbEndpointAgent.PolicyProbe/ShopDbEndpointAgent.PolicyProbe.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <!-- Planted-violation probe for LaunchPathPolicy. See README.md next to this
+       file: it is run BY HAND on Windows, not by CI, because the cases it
+       exists to catch are filesystem behaviour and CI runs on Linux.
+
+       net8.0, not net8.0-windows: the policy itself only touches System.IO, and
+       a plain target cross-publishes from the Linux dev box. -->
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <AssemblyName>lpptest</AssemblyName>
+    <RootNamespace>LppTest</RootNamespace>
+    <InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="../ShopDbEndpointAgent.Core/LaunchPathPolicy.cs" Link="LaunchPathPolicy.cs" />
+    <!-- ScheduledTaskPolicy is pure string logic with no filesystem state to
+         plant, so unlike LaunchPathPolicy it would run anywhere. It is linked
+         here anyway to keep both allowlist policies provable from one harness. -->
+    <Compile Include="../ShopDbEndpointAgent.Core/ScheduledTaskPolicy.cs" Link="ScheduledTaskPolicy.cs" />
+  </ItemGroup>
+</Project>

agent/ShopDbEndpointAgent.Tray/Program.cs

@@ -0,0 +1,45 @@
+using System.Threading;
+
+namespace ShopDbEndpointAgent.Tray;
+
+// Interactive user-session tray app (SCAFFOLD).
+// headless Windows Service: the service owns telemetry, this owns the operator
+// surface - a system-tray icon and the 5-click-max ServiceNow ticket flow
+// (DESIGN-DECISIONS-agent.md section 6). This iteration wires the tray and a
+// stubbed ticket dialog; the ServiceNow submission (direct vs server-proxied)
+// is deferred until that decision is made server-side.
+internal static class Program
+{
+    // Machine-wide single-instance guard. The installer starts the tray from an
+    // HKLM Run value for every user at logon, and an operator can also launch it
+    // from the Start Menu shortcut, so a second copy is easy to spawn. A named
+    // mutex in the Global namespace keeps exactly one tray per session: a later
+    // launch that cannot own the mutex exits immediately instead of stacking a
+    // duplicate icon. Global\ scopes across sessions on the same machine.
+    private const string SingleInstanceMutexName = @"Global\ShopDbEndpointAgentTray";
+
+    [STAThread]
+    private static void Main(string[] args)
+    {
+        // Headless icon export for the installer: `--export-icon <path>` writes
+        // the branded .ico and exits without starting the tray, so install.ps1
+        // can point the Start Menu shortcut at a real brand icon. Kept in this
+        // exe so the icon has a single source (TrayIcon) and no binary is
+        // checked into the repo.
+        if (args.Length >= 2 &&
+            string.Equals(args[0], "--export-icon", StringComparison.OrdinalIgnoreCase))
+        {
+            TrayIcon.Export(args[1]);
+            return;
+        }
+
+        using var singleInstance = new Mutex(true, SingleInstanceMutexName, out bool owned);
+        if (!owned)
+        {
+            return;
+        }
+
+        ApplicationConfiguration.Initialize();
+        Application.Run(new TrayContext());
+    }
+}

agent/ShopDbEndpointAgent.Tray/ScreenCapture.cs

@@ -0,0 +1,34 @@
+using System.Drawing.Imaging;
+
+namespace ShopDbEndpointAgent.Tray;
+
+// Captures the full virtual desktop (all monitors) to a PNG on disk, porting
+// the operator PowerShell proof of concept:
+//   CopyFromScreen over SystemInformation.VirtualScreen, then Bitmap.Save as
+//   PNG. Kept in the tray project because only the interactive tray session can
+//   see the operator's desktop; the headless service runs in session 0 and
+//   would capture a black frame.
+internal static class ScreenCapture
+{
+    // Grab every monitor in one shot. VirtualScreen spans the whole desktop so
+    // a multi-head shop-floor PC is captured intact rather than just the
+    // primary display. Returns the saved file path.
+    public static string CaptureToPng(string filePath)
+    {
+        var bounds = SystemInformation.VirtualScreen;
+        using var bitmap = new Bitmap(bounds.Width, bounds.Height,
+            PixelFormat.Format32bppArgb);
+        using (var graphics = Graphics.FromImage(bitmap))
+        {
+            graphics.CopyFromScreen(bounds.Left, bounds.Top, 0, 0,
+                bounds.Size, CopyPixelOperation.SourceCopy);
+        }
+
+        var directory = Path.GetDirectoryName(filePath);
+        if (!string.IsNullOrEmpty(directory))
+            Directory.CreateDirectory(directory);
+
+        bitmap.Save(filePath, ImageFormat.Png);
+        return filePath;
+    }
+}

agent/ShopDbEndpointAgent.Tray/ShopDbEndpointAgent.Tray.csproj

@@ -0,0 +1,88 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+	<OutputType>WinExe</OutputType>
+	<TargetFramework>net8.0-windows</TargetFramework>
+	<ImplicitUsings>enable</ImplicitUsings>
+	<Nullable>enable</Nullable>
+	<UseWindowsForms>true</UseWindowsForms>
+	<RootNamespace>ShopDbEndpointAgent.Tray</RootNamespace>
+	<AssemblyName>shopdb-endpoint-tray</AssemblyName>
+	<!-- 1.1.0: the tray now collects session-scoped user context. It invokes
+		 shopdbagent.exe with the collect-usercontext verb on a timer (once
+		 shortly after logon, then periodically) and the agent service reads the
+		 resulting spool file. The tray owns this because it is the only ShopDB
+		 process already running as the operator: mapped drives, user-owned
+		 listeners, and input idle time do not exist in the service's session 0.
+		 Requires agent 1.8.0 or newer: an older agent does not recognize the
+		 verb and falls through to starting a full host, so the tray and agent
+		 must be deployed together. -->
+	<!-- 1.0.0: first explicitly stamped tray version. The tray and the agent
+		 service version independently (they are separate exes and can be pushed
+		 apart), so the tray carries its own <Version> and the agent reports it
+		 as trayversion alongside its own agentversion (AGENT-CONTRACT.md 2). -->
+	<!-- 1.1.1: the tray now logs. Every user-context failure path was silent -
+		 a missing shopdbagent.exe returned bare, and the probe launch was
+		 wrapped in an empty catch - so "no mapped drives" produced no evidence
+		 anywhere on the machine. The tray writes
+		 C:\Users\ShopFloor\ShopDB\Logs\<datetime>-trayagent.log (the operator's
+		 own profile; it cannot write to ProgramData or Program Files) covering
+			 tray startup, agent-exe resolution, probe launch and probe exit code. -->
+		 <!-- 1.2.0: the tray stops claiming success it did not verify. The probe
+			  completion message printed a hardcoded spool path regardless of what
+			  happened, so a probe that exited 0 without writing anything read as a
+			  clean collection; it now reports the real pinned path and distinguishes
+			  spool-present, exit-0-but-no-file, and non-zero exit. Startup probe
+			  delay is chosen from session uptime: the 2-minute delay still applies at
+			  logon (drive mappings are not established yet), but a tray started into
+			  an already-running session - which is what an installer does - probes
+			  after 15 seconds instead of leaving a fresh install blind for the full
+			  30-minute cycle. A log sink that cannot open its directory raises a
+			  one-time balloon, since it cannot report its own failure through the
+			  log. Requires agent 1.9.0: the two carry the shared pinned spool path
+			  and must be deployed together. -->
+		 <!-- 1.3.0: the tray is no longer the authoritative user-context collector.
+			  The 'ShopDB user-context probe' scheduled task now owns collection,
+			  because it is the only mechanism that runs in the operator's own logon
+			  session at RunLevel Limited; the tray keeps its own probe cadence as
+			  belt-and-braces and writes the same spool. The installer no longer
+			  starts the tray directly (explorer.exe de-elevated it but did not
+			  change ACCOUNT, so an admin install produced an admin tray whose
+			  probe saw the wrong drive table). Autostart at logon is the Run key;
+			  install-time startup on a machine someone is already signed in to is
+			  a transient 'ShopDB tray first launch' scheduled task, which is the
+			  only way to enter the operator's existing session unelevated. Probe
+			  exit code 2 - the agent refusing to collect while elevated - is
+			  reported by name instead of as a bare code. Requires agent 1.10.1. -->
+		 <!-- 1.4.0: the tray answers on-demand refresh requests. A background
+			  listener waits on Global\ShopDbEndpointAgent.UserContextRefresh and
+			  runs the probe when the service asks, which is what makes a WebUI
+			  "Refresh Status" click produce current mapped drives instead of the
+			  last cadence's answer - the service cannot collect this itself at any
+			  price, since drive letters live on the operator's logon token, so the
+			  request has to be serviced HERE. Each probe is marshalled onto the UI
+			  thread: the cadence timer and a service request could otherwise both
+			  pass the in-flight guard and race the same spool file. "Send Status"
+			  now awaits a probe before invoking the once verb, because that verb
+			  reads the spool and would otherwise publish the previous probe's
+			  answer to an operator who just changed something and is watching
+			  for it. The probe
+			  body is one shared method used by all three callers rather than three
+			  copies of the exit-code handling. A tray that cannot open the channel
+			  logs and keeps its timer, so the failure mode is "refresh is not
+			  immediate", not "session data stops working". Requires agent 1.11.0. -->
+		 <Version>1.4.0</Version>
+	<InvariantGlobalization>true</InvariantGlobalization>
+	<RuntimeIdentifier>win-x64</RuntimeIdentifier>
+	<SelfContained>true</SelfContained>
+	<PublishSingleFile>true</PublishSingleFile>
+	<IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
+	<EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
+	<DebugType>none</DebugType>
+  </PropertyGroup>
+
+  <ItemGroup>
+	<ProjectReference Include="..\ShopDbEndpointAgent.Core\ShopDbEndpointAgent.Core.csproj" />
+  </ItemGroup>
+
+</Project>

agent/ShopDbEndpointAgent.Tray/TicketForm.cs

@@ -0,0 +1,110 @@
+namespace ShopDbEndpointAgent.Tray;
+
+// The operator issue reporter. Collects a free-text description and an optional
+// screenshot request, then hands the result back to TrayContext which performs
+// the capture (after this dialog closes, so it never appears in the shot) and
+// the upload via the service binary.
+//
+// Only "Other (free text)" is offered today: the fixed-reason routing from the
+// original design is not wired to a ticketing backend, so a single free-text
+// path is the one flow that works end to end. The dropdown is kept (disabled,
+// preselected) so the richer reason list can return without reworking the form.
+internal sealed class TicketForm : Form
+{
+    // Only the free-text reason is functional. Kept as a one-item list so the
+    // control and its layout stay in place for the future reason routing.
+    private static readonly string[] Reasons =
+    {
+        "Other (free text)",
+    };
+
+    private readonly ComboBox reasonBox;
+    private readonly TextBox detailBox;
+    private readonly CheckBox screenshotBox;
+
+    // Collected result, read by TrayContext after DialogResult.OK.
+    public string Reason => reasonBox.SelectedItem?.ToString() ?? "Other (free text)";
+    public string Details => detailBox.Text?.Trim() ?? string.Empty;
+    public bool IncludeScreenshot => screenshotBox.Checked;
+
+    public TicketForm()
+    {
+        Text = "Report an issue";
+        FormBorderStyle = FormBorderStyle.FixedDialog;
+        StartPosition = FormStartPosition.CenterScreen;
+        MinimizeBox = false;
+        MaximizeBox = false;
+        ClientSize = new Size(420, 260);
+
+        var reasonLabel = new Label
+        {
+            Text = "What is happening?",
+            Left = 16,
+            Top = 16,
+            Width = 388,
+        };
+        reasonBox = new ComboBox
+        {
+            Left = 16,
+            Top = 40,
+            Width = 388,
+            DropDownStyle = ComboBoxStyle.DropDownList,
+            // Disabled until the fixed-reason routing exists; free text is the
+            // only functional path, so the selection is fixed on it.
+            Enabled = false,
+        };
+        reasonBox.Items.AddRange(Reasons);
+        reasonBox.SelectedIndex = 0;
+
+        var detailLabel = new Label
+        {
+            Text = "Details",
+            Left = 16,
+            Top = 76,
+            Width = 388,
+        };
+        detailBox = new TextBox
+        {
+            Left = 16,
+            Top = 100,
+            Width = 388,
+            Height = 80,
+            Multiline = true,
+        };
+
+        screenshotBox = new CheckBox
+        {
+            Text = "Attach a screenshot of my screen",
+            Left = 16,
+            Top = 188,
+            Width = 388,
+            Checked = true,
+        };
+
+        var submit = new Button
+        {
+            Text = "Submit",
+            Left = 244,
+            Top = 220,
+            Width = 76,
+            DialogResult = DialogResult.OK,
+        };
+
+        var cancel = new Button
+        {
+            Text = "Cancel",
+            Left = 328,
+            Top = 220,
+            Width = 76,
+            DialogResult = DialogResult.Cancel,
+        };
+
+        Controls.AddRange(new Control[]
+        {
+            reasonLabel, reasonBox, detailLabel, detailBox, screenshotBox,
+            submit, cancel,
+        });
+        AcceptButton = submit;
+        CancelButton = cancel;
+    }
+}

agent/ShopDbEndpointAgent.Tray/TrayContext.cs

@@ -0,0 +1,663 @@
+using System.Diagnostics;
+using System.Reflection;
+
+using Microsoft.Extensions.Logging;
+
+using ShopDbEndpointAgent.Core;
+
+namespace ShopDbEndpointAgent.Tray;
+
+// Owns the tray icon and its context menu for the app's lifetime. Kept minimal
+// and headless-friendly: no main window, the icon is the whole UI surface until
+// the operator opens the ticket dialog.
+//
+// "Send Status now" reuses the exact production collection path by shelling out
+// to the installed shopdbagent.exe with --once. That keeps the collector key and
+// all collection logic in the service binary: the tray never holds a secret and
+// never duplicates wiring, it just asks the agent to report on demand so the
+// ShopDB monitor page reflects the box immediately instead of at next cadence.
+internal sealed class TrayContext : ApplicationContext
+{
+    // The headless agent/service executable. The tray ships next to it in the
+    // install directory, so same-dir resolution is the primary path.
+    private const string AgentExeName = "shopdbagent.exe";
+    private const string DefaultInstallDir = @"C:\Program Files\ShopDB\EndpointAgent";
+
+    private readonly NotifyIcon trayIcon;
+    private readonly Icon brandIcon;
+    private bool sending;
+
+    // Session-scoped collection. The service is LocalSystem and cannot see the
+    // operator's mapped drives, user-owned listeners, or input idle time, so the
+    // tray - which is already the operator - collects them and leaves the result
+    // in a spool file the service reads on its own cadence.
+    //
+    // Deliberately longer than the telemetry cadence: this data changes rarely
+    // (a mapped drive is mapped at logon and stays mapped), and each run spawns
+    // a short PowerShell process on a machine an operator is actively using.
+    private static readonly TimeSpan UserContextInterval = TimeSpan.FromMinutes(30);
+
+    // Logon is the worst moment to add work: drive mappings and profile setup
+    // are still settling, and a probe fired now would capture an incomplete
+    // picture while competing with everything else starting up.
+    private static readonly TimeSpan UserContextStartupDelay = TimeSpan.FromMinutes(2);
+
+    // ...but that reasoning only applies at logon. When the tray starts into a
+    // session that has been up for a while - which is what an installer restart
+    // or a manual relaunch does - nothing is settling and the full delay just
+    // extends the window where the server has no session data. The installer
+    // kills and restarts the tray on every install, so the 2-minute delay was
+    // being paid at exactly the moment someone was watching the card to see
+    // whether the install had worked.
+    private static readonly TimeSpan UserContextEstablishedDelay = TimeSpan.FromSeconds(15);
+
+    // How long the session must have been up to count as established. Comfortably
+    // past the logon storm, well short of any realistic install-to-check gap.
+    private static readonly TimeSpan EstablishedSessionUptime = TimeSpan.FromMinutes(5);
+
+    private readonly System.Windows.Forms.Timer userContextTimer;
+    private bool userContextStarted;
+    private bool collectingUserContext;
+
+    // Lets the service ask this tray to re-probe on demand, so a "Refresh
+    // Status" click in the WebUI produces genuinely current session data instead
+    // of whatever the last 30-minute tick happened to capture. The service
+    // cannot collect this itself at any price - mapped drives live on the
+    // operator's logon token - so the only way for an on-demand refresh to be
+    // accurate is for the request to end up here, in the operator's session.
+    private readonly UserContextRefreshChannel? refreshChannel;
+    private readonly CancellationTokenSource refreshCancellation = new();
+
+    // How long each wait blocks before looping. The wait returns false on
+    // timeout and the loop simply waits again, so this is not a deadline for
+    // anything - it just bounds how long the handle stays open, which lets a
+    // channel that was somehow broken get re-opened on the next pass instead of
+    // leaving the tray deaf until it restarts.
+    private static readonly TimeSpan RefreshWaitTimeout = TimeSpan.FromMinutes(5);
+
+    // The UI thread's context, captured in the constructor. The listener runs on
+    // a background thread, but every probe attempt is marshalled back here so
+    // that collectingUserContext is only ever read or written from one thread.
+    // Without this the timer tick and a service request could both pass the
+    // guard and launch two probes at the same spool file.
+    private readonly SynchronizationContext? uiContext;
+
+    // The tray logs into the operator's own profile
+    // (C:\Users\ShopFloor\ShopDB\Logs\<datetime>-trayagent.log), NOT into the
+    // service's ProgramData directory. The operator cannot write there, and the
+    // file sink fails silently when it cannot create its directory, so tray-side
+    // failures previously left no trace anywhere. Keeping the two apart means a
+    // tray problem is diagnosable from a file the operator can actually reach.
+    private readonly FileLoggerProvider logProvider;
+    private readonly ILogger logger;
+
+    public TrayContext()
+    {
+        logProvider = new FileLoggerProvider(
+            FileLoggerProvider.UserProfileLogDirectory(),
+            filePrefix: "trayagent");
+        logger = logProvider.CreateLogger("Tray");
+
+        var startupDelay = ResolveStartupDelay();
+        logger.LogInformation(
+            "Tray {Version} started; user-context probe in {Delay}, then every {Interval}.",
+            typeof(TrayContext).Assembly.GetName().Version?.ToString() ?? "unknown",
+            startupDelay, UserContextInterval);
+
+        var menu = new ContextMenuStrip();
+        menu.Items.Add("Send Status now", null, OnSendStatus);
+        menu.Items.Add("Report an issue...", null, OnReportIssue);
+        menu.Items.Add(new ToolStripSeparator());
+        menu.Items.Add("About ShopDB agent", null, OnAbout);
+        menu.Items.Add("Exit", null, OnExit);
+
+        // Branded tray icon drawn from the ShopDB WebUI favicon (see TrayIcon).
+        brandIcon = TrayIcon.Create();
+
+        trayIcon = new NotifyIcon
+        {
+            Icon = brandIcon,
+            Text = "ShopDB Endpoint Agent",
+            Visible = true,
+            ContextMenuStrip = menu,
+        };
+        trayIcon.DoubleClick += OnSendStatus;
+
+        // A dead log sink cannot report itself through the log. Complaining via
+        // the logger would write the one message that explains the silence into
+        // the sink that is swallowing messages, so the balloon is the only
+        // channel that survives. Shown once at startup and never repeated: this
+        // is a "your diagnostics are blind" notice for whoever is standing at the
+        // machine, not a recurring nag about something the operator cannot fix.
+        if (logProvider.SinkProblem is not null)
+        {
+            trayIcon.ShowBalloonTip(
+                10000,
+                "ShopDB Endpoint Agent",
+                "Tray logging is unavailable, so tray diagnostics will not be "
+                + $"recorded. {logProvider.SinkProblem}",
+                ToolTipIcon.Warning);
+        }
+
+        userContextTimer = new System.Windows.Forms.Timer
+        {
+            Interval = (int)startupDelay.TotalMilliseconds,
+        };
+        userContextTimer.Tick += OnUserContextTimer;
+        userContextTimer.Start();
+
+        uiContext = SynchronizationContext.Current;
+
+        // Best-effort. A tray that cannot open the channel still probes on its
+        // timer, so the failure mode is "refresh is not immediate", not "session
+        // data stops working" - which is why this is caught and logged rather
+        // than allowed to take the tray down at startup.
+        try
+        {
+            refreshChannel = new UserContextRefreshChannel(
+                logProvider.CreateLogger(nameof(UserContextRefreshChannel)));
+            StartRefreshListener();
+        }
+        catch (Exception exception)
+        {
+            logger.LogWarning(exception,
+                "Could not open the user-context refresh channel; on-demand "
+                + "refresh requests from the service will be ignored and session "
+                + "data will only update on the {Interval} timer.",
+                UserContextInterval);
+        }
+    }
+
+    // Waits for service refresh requests for the life of the tray.
+    //
+    // A dedicated background thread rather than a Task: this blocks on a kernel
+    // wait handle essentially forever, which is exactly the workload that should
+    // not sit on a thread-pool thread. IsBackground keeps it from holding the
+    // process open at exit.
+    private void StartRefreshListener()
+    {
+        var thread = new Thread(() =>
+        {
+            var token = refreshCancellation.Token;
+            while (!token.IsCancellationRequested)
+            {
+                try
+                {
+                    if (!refreshChannel!.WaitForRequest(RefreshWaitTimeout, token))
+                        continue;
+
+                    logger.LogInformation(
+                        "The service requested a user-context refresh.");
+
+                    // Marshalled, not awaited: the service is not waiting on a
+                    // reply through this channel, it is watching the spool file's
+                    // collectedat stamp. Our only job is to get the probe started
+                    // on the UI thread and go back to waiting.
+                    var post = uiContext;
+                    if (post is not null)
+                        post.Post(_ => _ = CollectUserContextAsync(), null);
+                    else
+                        _ = CollectUserContextAsync();
+                }
+                catch (OperationCanceledException)
+                {
+                    return;
+                }
+                catch (Exception exception)
+                {
+                    // Never let a bad wait kill the listener - if this thread
+                    // exits, on-demand refresh is silently dead for the rest of
+                    // the session with no other symptom.
+                    logger.LogWarning(exception,
+                        "The user-context refresh listener failed; retrying.");
+                    try
+                    {
+                        Thread.Sleep(TimeSpan.FromSeconds(5));
+                    }
+                    catch (Exception)
+                    {
+                        return;
+                    }
+                }
+            }
+        })
+        {
+            IsBackground = true,
+            Name = "ShopDB user-context refresh listener",
+        };
+
+        thread.Start();
+    }
+
+    // Fires once after the startup delay, then re-arms at the steady-state
+    // interval. Failures are swallowed on purpose: session data is a
+    // nice-to-have, and an operator must never see a dialog or a crashed tray
+    // because a probe could not read a drive mapping.
+    private async void OnUserContextTimer(object? sender, EventArgs e)
+    {
+        if (!userContextStarted)
+        {
+            userContextStarted = true;
+            userContextTimer.Interval = (int)UserContextInterval.TotalMilliseconds;
+        }
+
+        await CollectUserContextAsync();
+    }
+
+    // Runs the probe once and returns when the spool has been rewritten.
+    //
+    // Shared by all three callers - the cadence timer, an on-demand service
+    // request, and "Send Status now" - so there is exactly one place that knows
+    // how to invoke the probe and how to interpret its exit codes. Returns true
+    // only when a spool file is actually on disk afterwards, which is what lets
+    // Send Status decide whether it is worth waiting on.
+    private async Task<bool> CollectUserContextAsync()
+    {
+        if (collectingUserContext)
+        {
+            // Another probe is already in flight against the same spool path.
+            // Its result is at most a second or two old and satisfies whatever
+            // this caller wanted, so coalescing is correct here, not a shortcut.
+            logger.LogDebug(
+                "A user-context probe is already running; skipping this request.");
+            return false;
+        }
+
+        var agentExe = ResolveAgentExe();
+        if (agentExe is null)
+        {
+            // Previously a bare return. This is the single most likely reason for
+            // "no mapped drives" with nothing at all in any log, so it must say so.
+            logger.LogWarning(
+                "Skipping the user-context probe: {Agent} was not found beside the tray "
+                + "({Beside}) or at {Installed}.",
+                AgentExeName, AppContext.BaseDirectory, DefaultInstallDir);
+            return false;
+        }
+
+        collectingUserContext = true;
+        try
+        {
+            logger.LogInformation("Running the user-context probe: {Agent}", agentExe);
+            var exitCode = await RunAgentAsync(agentExe, "--collect-usercontext");
+
+            // Check the disk rather than announcing what the exit code implies.
+            // This line used to print a hardcoded path whenever the child exited
+            // 0, so it reported "spool written to C:\Users\ShopFloor\ShopDB" for
+            // weeks while the probe was actually writing into a different profile
+            // and the service was finding nothing.
+            var resultPath = UserContextSpool.PinnedResultPath();
+            if (exitCode == 0 && File.Exists(resultPath))
+            {
+                logger.LogInformation(
+                    "The user-context probe finished; spool present at {Spool}.",
+                    resultPath);
+                return true;
+            }
+            else if (exitCode == 0)
+            {
+                logger.LogWarning(
+                    "The user-context probe reported success but no spool file is "
+                    + "present at {Spool}.", resultPath);
+            }
+            else if (exitCode == 2)
+            {
+                // The agent refused because it was elevated. Called out by name
+                // because as a bare exit code it reads like a probe fault and
+                // sends the reader looking for a drive or WMI problem that is
+                // not there - the fix is to start the tray unelevated, or let
+                // the scheduled task do the collecting.
+                logger.LogWarning(
+                    "The user-context probe refused to run because this tray is "
+                    + "ELEVATED. Mapped drives are per logon token, so an elevated "
+                    + "probe would report the wrong drive table. Start the tray "
+                    + "unelevated, or rely on the 'ShopDB user-context probe' "
+                    + "scheduled task.");
+            }
+            else
+            {
+                logger.LogWarning(
+                    "The user-context probe exited with code {ExitCode}; expected a "
+                    + "spool at {Spool}.", exitCode, resultPath);
+            }
+
+            return false;
+        }
+        catch (Exception exception)
+        {
+            // No longer silent. The agent logs its own detail, but if the process
+            // could not even be started the agent never ran and never logged.
+            logger.LogWarning(exception, "Could not run the user-context probe.");
+            return false;
+        }
+        finally
+        {
+            collectingUserContext = false;
+        }
+    }
+
+    private async void OnReportIssue(object? sender, EventArgs e)
+    {
+        string reason;
+        string details;
+        bool includeScreenshot;
+        using (var dialog = new TicketForm())
+        {
+            if (dialog.ShowDialog() != DialogResult.OK)
+                return;
+            reason = dialog.Reason;
+            details = dialog.Details;
+            includeScreenshot = dialog.IncludeScreenshot;
+        }
+
+        var agentExe = ResolveAgentExe();
+        if (agentExe is null)
+        {
+            ShowBalloon("Report an issue", "Could not find " + AgentExeName +
+                ". Is the ShopDB Endpoint Agent installed?", ToolTipIcon.Error);
+            return;
+        }
+
+        // Capture AFTER the dialog closes so the report form is never in the
+        // shot. Stage into the interactive operator's own profile
+        // (%USERPROFILE%\ShopDBScreenshots), NOT %TEMP%: on this locked-down
+        // image the tray process's TEMP resolves to a different account's
+        // AppData that ShopFloor cannot write, and AppData/Temp are aggressively
+        // ACL'd/redirected. The profile root is owned by the operator and, by
+        // inherited ACL, readable by SYSTEM (the agent service) so the handoff
+        // works. Files are kept for the operator to show a DT/specialist later;
+        // pruning is the agent's future server-driven Capture Cleanup job.
+        var storeDir = OperatorReportStoreDir();
+        var stamp = DateTime.Now.ToString("yyyyMMdd-HHmmss");
+        string? payloadPath = null;
+        try
+        {
+            Directory.CreateDirectory(storeDir);
+            string? screenshotPath = null;
+            if (includeScreenshot)
+            {
+                screenshotPath = Path.Combine(storeDir, "screenshot-" + stamp + ".png");
+                ScreenCapture.CaptureToPng(screenshotPath);
+            }
+
+            payloadPath = Path.Combine(storeDir, "report-" + stamp + ".json");
+            OperatorReportPayload.Write(payloadPath, reason, details, screenshotPath);
+
+            ShowBalloon("Report an issue", "Sending your report to ShopDB...",
+                ToolTipIcon.Info);
+
+            int exitCode = await RunAgentAsync(agentExe, "--report \"" + payloadPath + "\"");
+            if (exitCode == 0)
+                ShowBalloon("Report an issue", "Your report was sent to ShopDB.",
+                    ToolTipIcon.Info);
+            else
+                ShowBalloon("Report an issue",
+                    "Report send failed (exit " + exitCode +
+                    "). See the agent log under ProgramData\\ShopDB.",
+                    ToolTipIcon.Warning);
+        }
+        catch (Exception error)
+        {
+            ShowBalloon("Report an issue", "Could not send the report: " +
+                error.Message, ToolTipIcon.Error);
+        }
+        finally
+        {
+            // Only the transient JSON sidecar is removed; the screenshot stays
+            // for the operator. The agent also deletes the sidecar on success,
+            // so this just covers the failure path.
+            if (payloadPath is not null)
+                TryDeleteFile(payloadPath);
+        }
+    }
+
+    // The operator-visible folder screenshots and the report sidecar are staged
+    // into, under the interactive user's profile. Resolved in the tray (running
+    // as that user) and passed to the agent as an absolute path; the agent must
+    // never re-derive it, since as SYSTEM its profile would resolve elsewhere.
+    private static string OperatorReportStoreDir()
+        => Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
+            "ShopDBScreenshots");
+
+    private static void TryDeleteFile(string filePath)
+    {
+        try
+        {
+            if (File.Exists(filePath))
+                File.Delete(filePath);
+        }
+        catch
+        {
+            // Best-effort; a leftover sidecar is harmless and the agent also
+            // removes it on a successful upload.
+        }
+    }
+
+    // Runs shopdbagent.exe --once out of process so the operator can push a
+    // fresh report without waiting for the next cadence tick. The exit code is
+    // the agent's own contract: 0 = reported OK, non-zero = failed (bad key,
+    // host removed, network) and the detail is in the rolling agent log.
+    private async void OnSendStatus(object? sender, EventArgs e)
+    {
+        if (sending)
+            return;
+
+        var agentExe = ResolveAgentExe();
+        if (agentExe is null)
+        {
+            ShowBalloon("Send Status", "Could not find " + AgentExeName +
+                ". Is the ShopDB Endpoint Agent installed?", ToolTipIcon.Error);
+            return;
+        }
+
+        sending = true;
+        trayIcon.Text = "ShopDB Endpoint Agent (sending status...)";
+        ShowBalloon("Send Status", "Sending this PC's status to ShopDB...",
+            ToolTipIcon.Info);
+
+        try
+        {
+            // Probe BEFORE reporting, and await it. The operator clicking this
+            // has just changed something - remapped a drive, signed in - and
+            // expects the result to show up. --once reads the spool file, so a
+            // probe started after it, or not awaited, would publish the previous
+            // probe's answer and the operator would click again and see the same
+            // stale card.
+            //
+            // Not fatal if it fails: a report with older session data still
+            // carries the heartbeat, inventory and events, which is most of what
+            // this button is for.
+            await CollectUserContextAsync();
+
+            int exitCode = await RunAgentAsync(agentExe, "--once");
+            if (exitCode == 0)
+                ShowBalloon("Send Status", "Status sent to ShopDB.",
+                    ToolTipIcon.Info);
+            else
+                ShowBalloon("Send Status",
+                    "Status send failed (exit " + exitCode +
+                    "). See the agent log under ProgramData\\ShopDB.",
+                    ToolTipIcon.Warning);
+        }
+        catch (Exception error)
+        {
+            ShowBalloon("Send Status", "Could not run the agent: " +
+                error.Message, ToolTipIcon.Error);
+        }
+        finally
+        {
+            sending = false;
+            trayIcon.Text = "ShopDB Endpoint Agent";
+        }
+    }
+
+    private static Task<int> RunAgentAsync(string agentExe, string arguments)
+    {
+        var startInfo = new ProcessStartInfo
+        {
+            FileName = agentExe,
+            Arguments = arguments,
+            WorkingDirectory = Path.GetDirectoryName(agentExe) ?? Environment.CurrentDirectory,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+
+        // The tray and the agent are both single-file, self-contained apps. When
+        // the tray host started, the .NET single-file bootstrapper set DOTNET_*
+        // and bundle-extraction variables in this process's environment. With
+        // UseShellExecute=false the child inherits those variables, so the
+        // freshly installed agent tries to bootstrap against the tray's stale
+        // extraction state and dies during host startup (exit 0xE0434352) before
+        // any managed code - or the file log - runs. Stripping these inherited
+        // markers gives the child the same clean host environment it gets when
+        // launched from a shell, and it also removes the need to restart the tray
+        // after every agent rebuild. The agent re-derives whatever it needs.
+        ScrubInheritedDotnetHostVariables(startInfo);
+
+        var completion = new TaskCompletionSource<int>();
+        var process = new Process { StartInfo = startInfo, EnableRaisingEvents = true };
+        process.Exited += (_, _) =>
+        {
+            completion.TrySetResult(process.ExitCode);
+            process.Dispose();
+        };
+
+        if (!process.Start())
+        {
+            process.Dispose();
+            completion.TrySetException(
+                new InvalidOperationException("failed to start " + agentExe));
+        }
+
+        return completion.Task;
+    }
+
+    // Remove the .NET host / single-file bundle markers this tray process
+    // inherited at startup so a spawned single-file child bootstraps cleanly
+    // instead of adopting the tray's extraction state. Names are matched by a
+    // DOTNET_/COREHOST_ prefix (covers DOTNET_BUNDLE_EXTRACT_BASE_DIR,
+    // DOTNET_ROOT, the internal startup hooks, etc.) so this stays correct as
+    // the runtime adds new host variables.
+    private static void ScrubInheritedDotnetHostVariables(ProcessStartInfo startInfo)
+    {
+        var toRemove = startInfo.Environment.Keys
+            .Where(key =>
+                key.StartsWith("DOTNET_", StringComparison.OrdinalIgnoreCase) ||
+                key.StartsWith("COREHOST_", StringComparison.OrdinalIgnoreCase))
+            .ToList();
+        foreach (var key in toRemove)
+            startInfo.Environment.Remove(key);
+    }
+
+    // Full delay at logon, short delay when the session is already established.
+    //
+    // Environment.TickCount64 is machine uptime, not session uptime, which is a
+    // deliberate simplification: the two differ only when someone signs out and
+    // back in without rebooting, and treating that as "established" is harmless -
+    // the profile is already built and the drives are already mapped in that
+    // case too. A failure to read it falls back to the conservative long delay.
+    private TimeSpan ResolveStartupDelay()
+    {
+        try
+        {
+            var uptime = TimeSpan.FromMilliseconds(Environment.TickCount64);
+            if (uptime >= EstablishedSessionUptime)
+            {
+                logger.LogInformation(
+                    "Session has been up {Uptime}; using the established-session probe delay.",
+                    uptime);
+                return UserContextEstablishedDelay;
+            }
+        }
+        catch (Exception exception)
+        {
+            logger.LogDebug(exception,
+                "Could not read system uptime; using the logon probe delay.");
+        }
+
+        return UserContextStartupDelay;
+    }
+
+    // Same directory first (the installer ships the tray next to the agent),
+    // then the known Program Files install directory as a fallback.
+    private static string? ResolveAgentExe()
+    {
+        var beside = Path.Combine(AppContext.BaseDirectory, AgentExeName);
+        if (File.Exists(beside))
+            return beside;
+
+        var installed = Path.Combine(DefaultInstallDir, AgentExeName);
+        if (File.Exists(installed))
+            return installed;
+
+        return null;
+    }
+
+    private void ShowBalloon(string title, string text, ToolTipIcon icon)
+    {
+        trayIcon.BalloonTipTitle = title;
+        trayIcon.BalloonTipText = text;
+        trayIcon.BalloonTipIcon = icon;
+        trayIcon.ShowBalloonTip(4000);
+    }
+
+    private void OnAbout(object? sender, EventArgs e)
+        => MessageBox.Show(
+            "ShopDB Endpoint Agent tray.\n" +
+            "Telemetry runs as the ShopDB Endpoint Agent Windows service.\n" +
+            "Send Status now reports this PC to ShopDB on demand.\n\n" +
+            "Tray version: " + TrayVersion() + "\n" +
+            "Agent version: " + AgentVersion(),
+            "About", MessageBoxButtons.OK, MessageBoxIcon.Information);
+
+    // The tray's own assembly version, the same value stamped from the csproj
+    // <Version> at build time.
+    private static string TrayVersion()
+        => Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "unknown";
+
+    // The installed agent service exe's file version, read from wherever the
+    // tray resolves it (beside the tray, then the default install dir). The
+    // service and tray can legitimately be different versions, so this is shown
+    // as its own line rather than assumed equal to the tray. Degrades to a
+    // clear note when the agent exe is not found or its version is unreadable.
+    private static string AgentVersion()
+    {
+        var agentExe = ResolveAgentExe();
+        if (agentExe is null)
+            return "not found";
+        try
+        {
+            return FileVersionInfo.GetVersionInfo(agentExe).FileVersion ?? "unknown";
+        }
+        catch (FileNotFoundException)
+        {
+            return "not found";
+        }
+    }
+
+    private void OnExit(object? sender, EventArgs e)
+    {
+        trayIcon.Visible = false;
+        ExitThread();
+    }
+
+    protected override void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            userContextTimer.Stop();
+            userContextTimer.Dispose();
+
+            // Cancel and let the listener unwind on its own. The channel opens
+            // and closes its handle inside each wait rather than holding one, so
+            // there is nothing here to dispose.
+            refreshCancellation.Cancel();
+            refreshCancellation.Dispose();
+
+            trayIcon.Dispose();
+            brandIcon.Dispose();
+        }
+        base.Dispose(disposing);
+    }
+}

agent/ShopDbEndpointAgent.Tray/TrayIcon.cs

@@ -0,0 +1,97 @@
+using System.Drawing.Drawing2D;
+using System.Drawing.Imaging;
+using System.Runtime.InteropServices;
+
+namespace ShopDbEndpointAgent.Tray;
+
+// Builds the tray icon from the ShopDB WebUI favicon (frontend/public/favicon.svg:
+// a #4181ff rounded square with a white "S") by drawing it with GDI+ at runtime.
+// Drawing it here rather than shipping a binary .ico keeps the brand in one
+// place (these values mirror the SVG) and avoids adding an SVG rasterizer or a
+// checked-in binary to the build.
+internal static class TrayIcon
+{
+    // Favicon colors (frontend/public/favicon.svg).
+    private static readonly Color Background = ColorTranslator.FromHtml("#4181ff");
+    private static readonly Color Foreground = Color.White;
+
+    // Renders the branded icon at a tray-friendly size. 32px covers standard and
+    // most high-DPI tray scaling; the OS downsamples as needed.
+    public static Icon Create(int size = 32)
+    {
+        using var bitmap = new Bitmap(size, size, PixelFormat.Format32bppArgb);
+        using (var graphics = Graphics.FromImage(bitmap))
+        {
+            graphics.SmoothingMode = SmoothingMode.AntiAlias;
+            graphics.TextRenderingHint =
+                System.Drawing.Text.TextRenderingHint.AntiAlias;
+            graphics.Clear(Color.Transparent);
+
+            // Rounded square (SVG rect rx=14 on a 64 viewport -> ~0.22 radius).
+            float inset = size * 0.03f;
+            var rect = new RectangleF(inset, inset,
+                size - inset * 2, size - inset * 2);
+            float radius = size * 0.22f;
+            using (var path = RoundedRect(rect, radius))
+            using (var fill = new SolidBrush(Background))
+                graphics.FillPath(fill, path);
+
+            // White "S", centered.
+            using var font = new Font("Arial", size * 0.58f,
+                FontStyle.Bold, GraphicsUnit.Pixel);
+            using var text = new SolidBrush(Foreground);
+            using var format = new StringFormat
+            {
+                Alignment = StringAlignment.Center,
+                LineAlignment = StringAlignment.Center,
+            };
+            graphics.DrawString("S", font, text, rect, format);
+        }
+
+        // Icon.FromHandle borrows the GDI HICON, so clone into a managed Icon
+        // and free the handle to avoid leaking one per launch.
+        IntPtr hicon = bitmap.GetHicon();
+        try
+        {
+            using var borrowed = Icon.FromHandle(hicon);
+            return (Icon)borrowed.Clone();
+        }
+        finally
+        {
+            DestroyIcon(hicon);
+        }
+    }
+
+    // Writes the branded icon to an .ico file so a Start Menu / desktop shortcut
+    // can show the brand instead of the generic exe icon. Reuses the same GDI+
+    // drawing as the tray so there is still one source of brand truth and no
+    // checked-in binary. 64px suits shortcut/large-icon views; the OS downscales.
+    public static void Export(string path, int size = 64)
+    {
+        using var icon = Create(size);
+        var directory = Path.GetDirectoryName(path);
+        if (!string.IsNullOrEmpty(directory))
+        {
+            Directory.CreateDirectory(directory);
+        }
+        using var stream = new FileStream(path, FileMode.Create, FileAccess.Write);
+        icon.Save(stream);
+    }
+
+    private static GraphicsPath RoundedRect(RectangleF rect, float radius)
+    {
+        float diameter = radius * 2;
+        var path = new GraphicsPath();
+        path.AddArc(rect.Left, rect.Top, diameter, diameter, 180, 90);
+        path.AddArc(rect.Right - diameter, rect.Top, diameter, diameter, 270, 90);
+        path.AddArc(rect.Right - diameter, rect.Bottom - diameter, diameter,
+            diameter, 0, 90);
+        path.AddArc(rect.Left, rect.Bottom - diameter, diameter, diameter, 90, 90);
+        path.CloseFigure();
+        return path;
+    }
+
+    [DllImport("user32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool DestroyIcon(IntPtr handle);
+}

agent/ShopDbEndpointAgent.slnx

@@ -0,0 +1,8 @@
+<Solution>
+  <Project Path="ShopDbEndpointAgent.Core/ShopDbEndpointAgent.Core.csproj" />
+  <Project Path="ShopDbEndpointAgent.Tray/ShopDbEndpointAgent.Tray.csproj" />
+  <Project Path="ShopDbEndpointAgent/ShopDbEndpointAgent.csproj" />
+  <Project Path="ShopDbAdoptionTool/ShopDbAdoptionTool.csproj" />
+  <!-- Run by hand on Windows, never by CI. See its README. -->
+  <Project Path="ShopDbEndpointAgent.PolicyProbe/ShopDbEndpointAgent.PolicyProbe.csproj" />
+</Solution>

agent/ShopDbEndpointAgent/Program.cs

@@ -0,0 +1,376 @@
+using System.Reflection;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using ShopDbEndpointAgent.Core;
+
+// Headless Windows Service host for the ShopDB endpoint agent. Composes the
+// Core runtime (config -> collector -> client -> worker) behind the generic
+// host, adds durable file logging and a WER-style fault monitor, and supports:
+//   (default)   run as a Windows Service (AddWindowsService)
+//   --console   run interactively in the foreground for debugging
+//   --once      collect and report exactly once, then exit (smoke test / cron)
+//   --report <path>  upload one operator issue report (JSON sidecar written by
+//                    the tray), then exit. Keeps the collector key in the
+//                    service so the tray never holds a secret.
+//
+// Secrets are never read here: AgentConfigProvider layers the registry
+// (HKLM\SOFTWARE\GE\ShopDB: CollectorKey, BaseUrl) over the shipped, non-secret
+// appsettings.json. The executable is intentionally named shopdbagent.exe so it
+// never collides with third-party agent.exe processes/services (for example the
+// MTConnect agent this same build can monitor).
+
+var runOnce = args.Any(a => string.Equals(a, "--once", StringComparison.OrdinalIgnoreCase));
+var forceConsole = args.Any(a => string.Equals(a, "--console", StringComparison.OrdinalIgnoreCase));
+var collectUserContext = args.Any(a =>
+    string.Equals(a, "--collect-usercontext", StringComparison.OrdinalIgnoreCase));
+var reportPayloadPath = ArgValue(args, "--report");
+
+var agentVersion = Assembly.GetExecutingAssembly()
+    .GetName().Version?.ToString() ?? "0.0.0";
+
+// FIRST, ahead of everything else. This verb runs as the signed-in operator (the
+// tray invokes it) and must not touch a single privileged resource on the way in.
+//
+// It used to sit below the bootstrap logger, the fault monitor, and the config
+// load, which meant the operator-context process opened the SYSTEM-owned
+// ProgramData log directory, attempted an EventLog source registration that only
+// an administrator can perform, and read CollectorKey out of HKLM - all before it
+// discovered it was only being asked to write a file into the user's own profile.
+// On an EPM-managed host (CyberArk) those are exactly the calls a broker
+// intercepts, and the registry read put the collector secret in a process that
+// has no business holding it.
+//
+// It also has no config dependency by design: it only writes into the caller's
+// own profile and never talks to the server, so it must still work on a machine
+// whose CollectorKey has not been provisioned yet - otherwise session data would
+// be missing on precisely the endpoints that are hardest to diagnose.
+if (collectUserContext)
+{
+    // First statement in this branch. The scheduled task runs this exe directly
+    // in the operator's interactive session, and shopdbagent.exe is a console
+    // app, so without this a black window flashes up on every collection cycle.
+    // Done before any logging or probing so the window is gone immediately
+    // rather than lingering for the life of the probe.
+    ConsoleWindow.Hide();
+
+    // Logs to the OPERATOR's profile, not the service's ProgramData directory.
+    // A non-privileged user cannot write to the SYSTEM-owned log directory, and
+    // the file sink degrades to a no-op when it cannot create its directory, so
+    // pointing this at the service location meant every probe failure was
+    // discarded unread - which is exactly how a broken probe looked identical to
+    // a probe that was never invoked.
+    using var probeLogProvider = new FileLoggerProvider(
+        FileLoggerProvider.UserProfileLogDirectory(),
+        filePrefix: "trayagent");
+    using var probeLoggerFactory = LoggerFactory.Create(
+        logging => logging.AddProvider(probeLogProvider));
+
+    var probeLogger = probeLoggerFactory.CreateLogger<UserContextProbe>();
+    ReportSinkProblem(probeLogProvider, "user-context probe");
+
+    // Refuse to collect from an elevated process. Drive letters are a property
+    // of the logon token, not the machine: an elevated process gets a different
+    // token to the operator's interactive one and enumerates a DIFFERENT, almost
+    // always empty, drive table. Measured on a live endpoint, the same two
+    // shares reported Unavailable from the elevated shell and OK from the
+    // operator's, in both Win32_NetworkConnection and Get-SmbMapping.
+    //
+    // Refusing here rather than filtering later is deliberate. An elevated probe
+    // does not fail - it succeeds and reports every mapped drive as broken,
+    // which is indistinguishable from a genuine outage at the far end. Better to
+    // write nothing and say why than to publish a confident wrong answer.
+    if (IsProcessElevated())
+    {
+        probeLogger.LogError(
+            "Refusing to collect user context: this process is elevated. Mapped drives " +
+            "are per-logon-token, so an elevated probe reports the wrong drive table. " +
+            "Run the '{Task}' scheduled task (RunLevel Limited) instead of invoking " +
+            "--collect-usercontext from an admin shell.",
+            "ShopDB user-context probe");
+        Console.Error.WriteLine(
+            "shopdbagent: refusing to collect user context from an elevated process; " +
+            "mapped drives would be wrong. Use the scheduled task.");
+        return 2;
+    }
+
+    var probe = new UserContextProbe(probeLogger);
+    return probe.Collect() ? 0 : 1;
+}
+
+// True when the current process holds the elevated (high-integrity) token.
+static bool IsProcessElevated()
+{
+    if (!OperatingSystem.IsWindows())
+    {
+        return false;
+    }
+
+    try
+    {
+        using var identity = System.Security.Principal.WindowsIdentity.GetCurrent();
+        var principal = new System.Security.Principal.WindowsPrincipal(identity);
+        return principal.IsInRole(System.Security.Principal.WindowsBuiltInRole.Administrator);
+    }
+    catch
+    {
+        // Cannot tell. Treat as not elevated so an unreadable token does not
+        // suppress collection on a host where the probe would have worked; the
+        // spool's own account stamp is still checked on the way back in.
+        return false;
+    }
+}
+
+// Bootstrap logger first so config loading (including the registry read that
+// CyberArk/EPM may gate) is fully diagnosable before the host starts.
+using var bootstrapFileLogger = new FileLoggerProvider(FileLoggerProvider.DefaultDirectory());
+var bootstrapLogger = bootstrapFileLogger.CreateLogger("Startup");
+ReportSinkProblem(bootstrapFileLogger, "service");
+
+var faultMonitor = new AgentFaultMonitor(bootstrapLogger);
+faultMonitor.Install();
+
+var config = AgentConfigProvider.Load(logger: bootstrapLogger);
+
+var logDirectory = string.IsNullOrWhiteSpace(config.LogPath)
+    ? FileLoggerProvider.DefaultDirectory()
+    : config.LogPath;
+
+if (!config.IsUsable())
+{
+    bootstrapLogger.LogError(
+        "Config incomplete: provision CollectorKey and BaseUrl in " +
+        "HKLM\\SOFTWARE\\GE\\ShopDB (or baseurl/apikey in appsettings.json for dev). " +
+        "See the registry lines above to tell 'missing' from 'access denied'.");
+    return 1;
+}
+
+var baseUrlProblem = config.BaseUrlProblem();
+if (baseUrlProblem is not null)
+{
+    bootstrapLogger.LogError("Config rejected: {Problem}", baseUrlProblem);
+    return 1;
+}
+
+try
+{
+    if (runOnce)
+        return await RunOnceAsync(config, agentVersion, logDirectory, faultMonitor);
+
+    if (!string.IsNullOrWhiteSpace(reportPayloadPath))
+        return await RunReportAsync(config, reportPayloadPath, logDirectory, faultMonitor);
+
+    await RunHostAsync(config, agentVersion, logDirectory, forceConsole);
+    return 0;
+}
+catch (Exception error)
+{
+    faultMonitor.ReportFatal("host", error);
+    return 1;
+}
+
+static async Task RunHostAsync(AgentConfig config, string agentVersion,
+    string logDirectory, bool forceConsole)
+{
+    var builder = Host.CreateApplicationBuilder();
+
+    if (!forceConsole)
+        builder.Services.AddWindowsService(options =>
+            options.ServiceName = "ShopDbEndpointAgent");
+
+    ConfigureLogging(builder.Logging, logDirectory);
+    RegisterCoreServices(builder.Services, config, agentVersion);
+    builder.Services.AddHostedService(sp => sp.GetRequiredService<TelemetryWorker>());
+    builder.Services.AddHostedService(sp => sp.GetRequiredService<CommandWorker>());
+
+    await builder.Build().RunAsync();
+}
+
+static async Task<int> RunOnceAsync(AgentConfig config, string agentVersion,
+    string logDirectory, AgentFaultMonitor faultMonitor)
+{
+    using var services = BuildOnceServices(config, agentVersion, logDirectory);
+    var worker = services.GetRequiredService<TelemetryWorker>();
+    var logger = services.GetRequiredService<ILogger<TelemetryWorker>>();
+    try
+    {
+        var result = await worker.RunOnceAsync(config.AdoptOnFirstRun, CancellationToken.None);
+        logger.LogInformation("Single report complete: action={Action}", result.Action);
+        return 0;
+    }
+    catch (Exception error)
+    {
+        faultMonitor.ReportFatal("--once", error);
+        return 1;
+    }
+}
+
+// Uploads one operator issue report described by a tray-written JSON sidecar,
+// then deletes the payload folder. Runs out of process from the tray so the
+// collector key stays in the service binary. The exit code is the tray's
+// contract: 0 = uploaded, non-zero = failed (detail in the agent log).
+static async Task<int> RunReportAsync(AgentConfig config, string payloadPath,
+    string logDirectory, AgentFaultMonitor faultMonitor)
+{
+    using var services = BuildOnceServices(config, "0.0.0", logDirectory);
+    var client = services.GetRequiredService<CollectorClient>();
+    var logger = services.GetRequiredService<ILogger<CollectorClient>>();
+    try
+    {
+        var payload = OperatorReportPayload.Read(payloadPath);
+        var response = await client.UploadOperatorReportAsync(
+            payload.Reason, payload.Details, payload.ScreenshotPath,
+            Environment.MachineName, CancellationToken.None);
+        logger.LogInformation("Operator report uploaded: id={ReportId}",
+            response?.OperatorReportId);
+        return 0;
+    }
+    catch (Exception error)
+    {
+        faultMonitor.ReportFatal("--report", error);
+        return 1;
+    }
+    finally
+    {
+        // Remove only the transient JSON sidecar. The screenshot lives in the
+        // operator's %USERPROFILE%\ShopDBScreenshots folder and is deliberately
+        // KEPT so the operator can show it to a DT/specialist later; pruning it
+        // is the future server-driven Capture Cleanup job, not this path. (The
+        // sidecar previously sat in a throwaway temp folder we deleted whole;
+        // now it shares the operator's folder, so a recursive delete here would
+        // wipe saved screenshots.)
+        try
+        {
+            if (File.Exists(payloadPath))
+                File.Delete(payloadPath);
+        }
+        catch { /* best-effort; the tray also removes the sidecar */ }
+    }
+}
+
+// Read the value following a flag (e.g. --report C:\path\report.json). Returns
+// null when the flag is absent or has no following token.
+static string? ArgValue(string[] args, string flag)
+{
+    for (int i = 0; i < args.Length - 1; i++)
+    {
+        if (string.Equals(args[i], flag, StringComparison.OrdinalIgnoreCase))
+            return args[i + 1];
+    }
+    return null;
+}
+
+static ServiceProvider BuildOnceServices(AgentConfig config, string agentVersion,
+    string logDirectory)
+{
+    var services = new ServiceCollection();
+    services.AddLogging(logging => ConfigureLogging(logging, logDirectory));
+    RegisterCoreServices(services, config, agentVersion);
+    return services.BuildServiceProvider();
+}
+
+static void RegisterCoreServices(IServiceCollection services, AgentConfig config,
+    string agentVersion)
+{
+    services.AddSingleton(config);
+
+    // Shared wake used by the command worker to trigger an immediate telemetry
+    // collect after a command changes endpoint state (e.g. MTConnect toggle).
+    services.AddSingleton<CollectSignal>();
+
+    if (!string.IsNullOrWhiteSpace(config.UtilitiesPath) &&
+        Directory.Exists(config.UtilitiesPath))
+    {
+        services.AddSingleton<IAgentUtilityRunner>(sp =>
+            new PowerShellUtilityRunner(config.UtilitiesPath,
+                sp.GetRequiredService<ILogger<PowerShellUtilityRunner>>()));
+    }
+
+    // Persisted per-channel event watermark so each Windows event record is
+    // reported exactly once, instead of re-sending the newest window of every
+    // channel on every cadence tick.
+    services.AddSingleton(sp => new EventWatermarkStore(
+        sp.GetRequiredService<ILogger<EventWatermarkStore>>()));
+
+    // Session-scoped collection. The agent is LocalSystem, so mapped drives and
+    // user-owned listeners are invisible to it. The tray, which already runs as
+    // the operator, writes the spool file; the service only reads it.
+    //
+    // UserContextProbe is deliberately NOT registered here. The service must
+    // never run the probe: descending into the session with CreateProcessAsUser
+    // is the reverted design, and leaving a resolvable dependency in the
+    // container is an invitation to reintroduce it. The probe is constructed
+    // only on the --collect-usercontext path, which the tray invokes.
+    services.AddSingleton(sp => new UserContextSpool(
+        sp.GetRequiredService<ILogger<UserContextSpool>>()));
+
+    // The ask-the-tray side of the same split. Registering this is NOT a
+    // loophole around the paragraph above: the service still cannot collect
+    // session data, it can only request that the process which can does so, and
+    // then read the file that appears. The probe stays out of this container.
+    services.AddSingleton(sp => new UserContextRefreshChannel(
+        sp.GetRequiredService<ILogger<UserContextRefreshChannel>>()));
+
+    services.AddSingleton<ICollector>(sp => new EndpointCollector(
+        sp.GetRequiredService<ILogger<EndpointCollector>>(),
+        config,
+        sp.GetService<IAgentUtilityRunner>(),
+        sp.GetRequiredService<EventWatermarkStore>(),
+        sp.GetRequiredService<UserContextSpool>()));
+
+    services.AddSingleton(sp => new CollectorClient(
+        config, sp.GetRequiredService<ILogger<CollectorClient>>()));
+
+    services.AddSingleton(sp => new TelemetryWorker(
+        sp.GetRequiredService<ICollector>(),
+        sp.GetRequiredService<CollectorClient>(),
+        config,
+        agentVersion,
+        sp.GetRequiredService<ILogger<TelemetryWorker>>(),
+        sp.GetService<IAgentUtilityRunner>(),
+        sp.GetRequiredService<CollectSignal>(),
+        sp.GetRequiredService<UserContextSpool>(),
+        sp.GetRequiredService<UserContextRefreshChannel>()));
+
+    // Command channel: outbound long-poll for allowlisted WebUI commands, run
+    // through the fail-closed executor. Hosted alongside telemetry but on its
+    // own loop so a held-open poll never delays a report.
+    services.AddSingleton(sp => new CommandClient(
+        config, sp.GetRequiredService<ILogger<CommandClient>>()));
+
+    services.AddSingleton(sp => new CommandExecutor(
+        sp.GetRequiredService<ILogger<CommandExecutor>>(),
+        config));
+
+    services.AddSingleton(sp => new CommandWorker(
+        sp.GetRequiredService<CommandClient>(),
+        sp.GetRequiredService<CommandExecutor>(),
+        sp.GetRequiredService<ILogger<CommandWorker>>(),
+        sp.GetRequiredService<CollectSignal>()));
+}
+
+static void ConfigureLogging(ILoggingBuilder logging, string logDirectory)
+{
+    logging.ClearProviders();
+    logging.AddProvider(new FileLoggerProvider(logDirectory));
+    logging.SetMinimumLevel(LogLevel.Information);
+}
+
+// Say so, loudly, when a file sink could not open its directory.
+//
+// FileLoggerProvider never throws on construction and silently drops lines when
+// its directory is unusable. That is the right behaviour - logging must not take
+// the agent down - but it made two different failures indistinguishable: a probe
+// that ran and failed, and a probe whose log had nowhere to go. The provider
+// records the reason; this is the part that was missing, the caller actually
+// asking for it. stderr is the only sink guaranteed to exist at this point, so
+// that is where the complaint goes.
+static void ReportSinkProblem(FileLoggerProvider provider, string which)
+{
+    if (provider.SinkProblem is null)
+        return;
+
+    Console.Error.WriteLine(
+        $"shopdbagent: the {which} log sink is unusable and log lines will be "
+        + $"dropped - {provider.SinkProblem}");
+}

agent/ShopDbEndpointAgent/ShopDbEndpointAgent.csproj

@@ -0,0 +1,179 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+	<OutputType>Exe</OutputType>
+	<TargetFramework>net8.0-windows</TargetFramework>
+	<ImplicitUsings>enable</ImplicitUsings>
+	<Nullable>enable</Nullable>
+	<RootNamespace>ShopDbEndpointAgent</RootNamespace>
+	<AssemblyName>shopdbagent</AssemblyName>
+	<!-- 1.10.1: the collect-usercontext verb hides its console window. The agent
+		 is a console exe, which the tray used to mask by launching the probe with
+		 CreateNoWindow; the scheduled task runs the exe directly in the operator's
+		 session, so a black window appeared on every 30-minute collection. -->
+	<!-- 1.10.0: user context is collected by a scheduled task in the operator's
+		 own logon session, not by a process the elevated installer launches.
+		 Drive letters are per logon token: an elevated probe enumerates a
+		 different, usually empty, drive table, so an install performed by an
+		 admin produced a spool reporting every mapped drive as Unavailable while
+		 the operator's own session showed OK. The installer no longer starts the
+		 tray via explorer.exe (which de-elevates but does NOT change account) and
+		 instead registers 'ShopDB user-context probe' against BUILTIN\Users at
+		 RunLevel Limited, verifies it by reading the task back, and records the
+		 outcome in the install ledger. The collect-usercontext verb now refuses
+		 to run elevated (exit 2) rather than writing a confident wrong answer,
+		 the probe stamps its token elevation, and the service rejects any spool
+		 stamped elevated. Probe runs log the drive and listener counts. -->
+	<!-- 1.9.0: the spool is finally written where the service looks for it. The
+		 probe script resolved its output directory from $env:USERPROFILE while
+		 the reader used the pinned C:\Users\ShopFloor path; under a brokered or
+		 re-parented tray launch those differ, so the probe reported success and
+		 wrote the file somewhere the service never read. Both sides now derive
+		 the path from one helper (UserContextSpool.PinnedResultPath). Collect()
+		 verifies the file exists on disk before reporting success, because a
+		 zero exit code from powershell.exe proved nothing about the write.
+		 Minor rather than patch because the spool handoff itself changed shape
+		 (AGENT-CONTRACT.md 5): the spool is now PERSISTED and overwritten each
+		 run rather than consumed on read. The collector cache is in-memory only,
+		 so consume-on-read plus a service restart blanked mapped drives until the
+		 next tray cycle. Max age tightened 24h -> 90m now that staleness, not
+		 deletion, is the retirement mechanism. A spool whose username stamp is
+		 absent or not ShopFloor is rejected outright - wrong-session drive data
+		 is worse than none.
+		 The collect-usercontext branch moved to the top of Program.cs: it used to
+		 open the SYSTEM-owned log directory, register an EventLog source, and
+		 read CollectorKey out of HKLM before discovering it only needed to write
+		 a file into the caller's own profile - all as the operator, and all
+		 exactly what an EPM broker intercepts. Log filenames unified on
+		 <date>-<component>.log across service, tray, and installer. A log sink
+		 that cannot open its directory now says so on stderr instead of
+		 discarding every line unread. Pairs with tray 1.2.0. -->
+	<!-- 1.8.1: user-context logging and spool location are split from the
+		 service's. The probe runs as the signed-in operator but logged into
+		 %ProgramData%\ShopDB\EndpointAgent\logs, which is SYSTEM-owned and not
+		 writable from a user session; the file sink swallows that failure, so a
+		 probe that failed and a probe that never ran looked identical - no log
+		 line either way. The probe and the tray now log to
+		 C:\Users\ShopFloor\ShopDB\Logs\<datetime>-trayagent.log, which the
+		 operator owns. The spool path is pinned to C:\Users\ShopFloor\ShopDB
+		 instead of being resolved through WTSQueryUserToken (a privileged call
+		 endpoint protection blocks, after which writer and reader disagreed
+		 silently about the location). The service now CONSUMES the spool -
+		 removing it after a successful parse - so a dead tray stops re-reporting
+		 stale drives instead of pinning them forever. The probe itself is
+		 launched with -EncodedCommand rather than a staged .ps1 run via -File:
+		 a quarantined or missing temp script makes powershell.exe print usage
+		 and exit -196608 without running a statement. -->
+	<!-- 1.8.0: user-context collection is inverted. The service no longer
+		 descends into the operator's session with CreateProcessAsUser to run the
+		 probe; that path needs to duplicate a token, is what endpoint protection
+		 watches for, and produced no spool file at all on a live endpoint. The
+		 tray, which is already running as the operator, now invokes
+		 shopdbagent.exe with the collect-usercontext verb on its own cadence and
+		 the service only reads the spool. Requires the 1.1.0 tray: an older tray
+		 the new verb, so usercontext stays null until the tray is updated.
+		 Spool freshness moved from delete-around-read to the in-file collectedat
+		 stamp with a max age, because writer and reader are now independent
+		 processes and a delete-then-read would race the tray and discard good
+		 results. -->
+	<!-- 1.7.0: curated events are harvested against a persisted per-channel
+		 Windows record-id watermark and carry eventrecordid, so one real event
+		 is reported and stored exactly once instead of once per cadence tick
+		 for as long as it stayed in the newest-25 window. Adds WER 1000/1002,
+		 event XML fields, listening ports, an on-demand network_connections
+		 command, pendingreboot, disk freepercent, and populates cpupercent/
+		 memorypercent/idleseconds (previously declared but always null).
+		 Session-scoped data (mapped drives, user-owned listeners, idle time)
+		 comes from a probe run in the interactive user's session via a spool
+		 file, because none of it exists in the agent's LocalSystem session 0.
+		 run_script user-context waits are now bounded; the previous Infinite
+		 wait could pin the command worker on a hung script.
+		 1.6.3: operator issue reports stage under the interactive operator's
+		 %USERPROFILE%\ShopDBScreenshots (resolved in the ShopFloor tray session)
+		 instead of %TEMP%, which on locked-down endpoints redirected to another
+		 user's AppData\Local\Temp and left the SYSTEM-context report upload
+		 reading an inaccessible path. Screenshots use flat timestamped names and
+		 are KEPT after a successful upload for operator review; only the transient
+		 JSON sidecar is pruned, so the report path no longer recursively deletes
+		 the shared folder. AgentFaultMonitor.ReportFatal now mirrors fatal report
+		 failures to the rolling file log so unelevated tray-launched runs surface
+		 a cause instead of exiting 1 silently.
+		 1.6.2: command channel retires pooled TLS connections faster than the
+		 server keep-alive (SocketsHttpHandler PooledConnectionIdleTimeout 1s,
+		 PooledConnectionLifetime 2m). Fixes intermittent "unexpected EOF or 0
+		 bytes from the transport stream" on the long-poll claim when the pool
+		 reused a socket the server had already closed between hold windows.
+		 Telemetry was unaffected; this only touched CommandClient.
+		 1.6.1: republished against the current source so both site packages
+		 (Wilmington and West Jefferson) carry the same vetted build. No agent
+		 behavior change; the server now computes warn-only drift from the
+		 service/process state the agent already reports each cycle.
+		 1.6.0: a policy-attached process monitor may carry a launch path set by
+		 a site leader in the WebUI; it rides the /monitors/resolved payload and
+		 the agent honors it only after LaunchPathPolicy validates it (approved
+		 root, exists, launchable extension). A local appsettings.json launchpaths
+		 entry still wins; an unvalidated path is dropped and process_start fails
+		 closed.
+		 1.5.0: the agent fetches its watch list from server policy each
+		 telemetry cycle (GET /api/endpoints/monitors/resolved) and merges it
+		 over local appsettings.json, so a policy-attached process/service
+		 monitor is enumerated and reported without editing the box. Fail-closed:
+		 a failed fetch keeps the local list.
+		 1.4.1: run_script/update_app stage into a fixed, Defender-excludable
+		 folder (C:\ProgramData\ShopDB\EndpointAgent) instead of the LocalSystem
+		 temp path, and run_script user-context waits for exit and reports the
+		 real exit code instead of fire-and-forget "launched".
+		 1.4.0: run_script fetches a ShopDB-hosted script by digest and runs it
+		 in the script's configured context (system or the interactive user),
+		 replacing the local scriptpaths allowlist; update_app resolves an app-
+		 level or version-level install source.
+		 1.2.0: process_start launches via a per-image path allowlist
+		 (AgentConfig.LaunchPaths, shipped defaults overridable per site).
+		 1.1.0: generic, data-driven service_*/process_* actions carry their
+		 target over the wire, so new policies/apps need no agent rebuild. -->
+	<!-- 1.11.0: on-demand user-context refresh. "Refresh Status" (collect_now)
+		 and the tray's "Send Status" re-sent whatever was already in the spool,
+		 so a drive the operator had just unmapped kept reporting OK until the
+		 next 30-minute probe and no amount of clicking changed it. The service
+		 still does not - and must not - collect session data itself; it signals
+		 Global\ShopDbEndpointAgent.UserContextRefresh and waits up to 12s for the
+		 spool's collectedat stamp to ADVANCE before collecting, which is the only
+		 proof the file in front of it answers this request and not the previous
+		 one. The wait is bounded and non-fatal by design: telemetry is the
+		 liveness signal, so a timeout reports slightly stale session data rather
+		 than skipping the report. UserContextSpool.TryReadCollectedAt reads the
+		 stamp outside the usability gates, so a spool rejected as expired or
+		 wrong-account does not burn the full timeout every cycle. Minor because
+		 the spool handoff gains a second channel (AGENT-CONTRACT.md 5) and
+		 because the installer now registers the probe task to the ShopFloor USER
+		 rather than BUILTIN\Users: a group-principal task cannot be started by a
+		 member of that group, so Start-ScheduledTask returned access denied and
+		 the task only ever ran on its own trigger. Requires tray 1.4.0 - the tray
+		 is the side that listens, so an older tray simply never answers. -->
+	<Version>1.11.0</Version>
+	<InvariantGlobalization>true</InvariantGlobalization>
+	<RuntimeIdentifier>win-x64</RuntimeIdentifier>
+	<SelfContained>true</SelfContained>
+	<PublishSingleFile>true</PublishSingleFile>
+	<IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
+	<EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
+	<DebugType>none</DebugType>
+  </PropertyGroup>
+
+  <ItemGroup>
+	<PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
+	<PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="8.0.0" />
+	<PackageReference Include="Microsoft.Extensions.Logging.EventLog" Version="8.0.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+	<ProjectReference Include="..\ShopDbEndpointAgent.Core\ShopDbEndpointAgent.Core.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+	<None Update="appsettings.json">
+	  <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+	</None>
+  </ItemGroup>
+
+</Project>

agent/ShopDbEndpointAgent/appsettings.json

@@ -0,0 +1,16 @@
+{
+  "baseurl": "",
+  "apikey": "REPLACE_WITH_COLLECTOR_KEY",
+  "cadenceseconds": 900,
+  "jitterseconds": 60,
+  "adoptonfirstrun": true,
+  "utilitiespath": "",
+  "logpath": "",
+  "monitors": {
+    "processes": [],
+    "services": []
+  },
+  "launchpaths": {}
+}
+
+

agent/utilities/shopdb-dellupdates.ps1

@@ -0,0 +1,119 @@
+<#
+.SYNOPSIS
+	ShopDB agent utility: reports pending Dell Command | Update items.
+
+.DESCRIPTION
+	Discovered and executed by PowerShellUtilityRunner on the telemetry cadence.
+	Emits a single JSON object on stdout, which the agent attaches to the report
+	as `dellupdates`. Never throws and never writes anything but JSON: a failure
+	here must not break a telemetry run, so every error path still emits a valid
+	object with a `status` explaining why the list is empty.
+
+	THIS SCRIPT DOES NOT SCAN. It only reads the log a previous scan wrote. The
+	scan itself is fired by the \ShopDB-DellCommandScan scheduled task, which is
+	what pins dcu-cli.exe's -outputLog to the path below. Keeping the two apart
+	is deliberate: a telemetry collector that shelled out to dcu-cli would block
+	the cadence for minutes and hammer Dell's servers every 15 minutes.
+
+	OUTPUT CONTRACT (keep in sync with plugins/endpoints/plugin.py):
+		status    unknown | ok | error - "unknown" means no scan has ever run,
+				  which is NOT the same as "ok" with an empty list (known clean).
+		scannedat ISO-8601 UTC timestamp of the scan log's last write, or null.
+		count     total pending updates found.
+		updates   up to $MaxUpdates entries of { name, severity, version }.
+		truncated true when count exceeded $MaxUpdates.
+
+	Dell's own long description text is deliberately NOT carried: it is
+	sentence-length marketing prose per update, which would add roughly an order
+	of magnitude to every report for no operational value. Name plus severity is
+	what an operator decides on.
+#>
+
+$ErrorActionPreference = 'Stop'
+
+# Cap the list rather than the payload. A machine that is years behind can have
+# dozens of pending updates, and an unbounded list would bloat every report on
+# the cadence. Mirrors the MaxReportedConnections precedent in CommandExecutor:
+# a truncated answer is more useful than a rejected payload.
+$MaxUpdates = 25
+
+# Must match the -outputLog path set in the \ShopDB-DellCommandScan task
+# definition. ShopDB-initiated scans write HERE rather than to Dell's default
+# location, which is what keeps them distinguishable from the corporate-managed
+# DCU tasks that also run on these machines.
+$ScanLog = Join-Path $env:ProgramData 'ShopDB\EndpointAgent\dellcommand\scan.xml'
+
+function Write-Result {
+	param($Status, $ScannedAt, $Count, $Updates, $Truncated)
+	# Compress so the payload carries no pretty-printing whitespace. Depth 3
+	# covers the nested updates array.
+	[pscustomobject]@{
+		status    = $Status
+		scannedat = $ScannedAt
+		count     = $Count
+		updates   = @($Updates)
+		truncated = [bool]$Truncated
+	} | ConvertTo-Json -Depth 3 -Compress
+}
+
+try {
+	if (-not (Test-Path -LiteralPath $ScanLog)) {
+		# No scan has run yet. This is the normal state for a freshly adopted
+		# endpoint, not an error, but it must stay distinct from "scanned and
+		# found nothing" or the UI would claim a machine is up to date when
+		# nobody has ever checked.
+		Write-Result -Status 'unknown' -ScannedAt $null -Count 0 -Updates @() -Truncated $false
+		return
+	}
+
+	$logFile = Get-Item -LiteralPath $ScanLog
+	$scannedAt = $logFile.LastWriteTimeUtc.ToString('o')
+
+	[xml]$report = Get-Content -LiteralPath $ScanLog -Raw
+
+	# dcu-cli's scan report shape has varied across DCU versions, so select the
+	# update nodes by name anywhere in the tree rather than by a fixed path.
+	$nodes = @($report.SelectNodes('//update'))
+	if ($nodes.Count -eq 0) {
+		$nodes = @($report.SelectNodes('//Update'))
+	}
+
+	$updates = foreach ($node in $nodes) {
+		# Attribute casing also varies by version; take whichever is present and
+		# fall back rather than emitting a null-filled row.
+		$name = $node.name
+		if (-not $name) { $name = $node.Name }
+		if (-not $name) { $name = $node.display }
+		if (-not $name) { continue }
+
+		$severity = $node.urgency
+		if (-not $severity) { $severity = $node.Urgency }
+		if (-not $severity) { $severity = $node.criticality }
+
+		$version = $node.version
+		if (-not $version) { $version = $node.Version }
+
+		[pscustomobject]@{
+			name     = [string]$name
+			severity = if ($severity) { [string]$severity } else { 'unknown' }
+			version  = if ($version) { [string]$version } else { $null }
+		}
+	}
+
+	$updates = @($updates)
+	$count = $updates.Count
+	$truncated = $count -gt $MaxUpdates
+	if ($truncated) {
+		$updates = $updates[0..($MaxUpdates - 1)]
+	}
+
+	Write-Result -Status 'ok' -ScannedAt $scannedAt -Count $count `
+				 -Updates $updates -Truncated $truncated
+}
+catch {
+	# Emit a valid object rather than failing: the runner would log a non-JSON
+	# utility and drop it, which looks identical to "never ran" on the server.
+	# An explicit error status tells an operator the scan log exists but could
+	# not be read, which is a different problem from no scan at all.
+	Write-Result -Status 'error' -ScannedAt $null -Count 0 -Updates @() -Truncated $false
+}

deploy/ci/buildkit-remote.yaml

@@ -0,0 +1,123 @@
+# Persistent, non-privileged BuildKit for the publish-images workflow.
+#
+# WHY this exists: the arc-runner-set runner pods have the docker/buildx CLIs
+# but no Docker daemon and cannot run a privileged DinD sidecar under cluster
+# policy. So image builds are delegated to this standalone buildkitd Service.
+# The workflow (.github/workflows/publish-images.yml) points Buildx at it with
+#   driver: remote
+#   endpoint: ${{ secrets.BUILDKIT_ENDPOINT }}
+# where BUILDKIT_ENDPOINT is set to:
+#   tcp://buildkit.buildkit.svc.cluster.local:1234
+#
+# This runs rootless buildkitd, so it needs NO privileged: true. It only needs
+# a few unconfined-ish knobs the rootless image documents. A persistent
+# Deployment (not a per-job container) means the build cache in the PVC survives
+# across runs, so the heavy frontend npm build is only paid in full once.
+#
+# Cameron: apply once with `kubectl apply -f deploy/ci/buildkit-remote.yaml`.
+# This changes cluster infra only. It does NOT modify any application code or
+# any branch of the repo.
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: buildkit
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: buildkit
+  namespace: buildkit
+  labels:
+    app: buildkit
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: buildkit
+  template:
+    metadata:
+      labels:
+        app: buildkit
+      annotations:
+        # Required by rootless buildkitd to unshare user/network namespaces
+        # without full privilege. These are the values from the upstream
+        # rootless example; they are far weaker than privileged: true.
+        container.apparmor.security.beta.kubernetes.io/buildkitd: unconfined
+    spec:
+      containers:
+        - name: buildkitd
+          image: moby/buildkit:v0.16.0-rootless
+          args:
+            - --addr
+            - unix:///run/user/1000/buildkit/buildkitd.sock
+            - --addr
+            - tcp://0.0.0.0:1234
+            # TLS is terminated in-cluster; the Service is only reachable from
+            # runner pods on the internal network. If you want mTLS between the
+            # runner and buildkitd, mount certs here and add --tlscacert etc,
+            # then set the endpoint secret to the tcp:// address with certs.
+            - --oci-worker-no-process-sandbox
+          readinessProbe:
+            exec:
+              command:
+                - buildctl
+                - debug
+                - workers
+            initialDelaySeconds: 5
+            periodSeconds: 30
+          livenessProbe:
+            exec:
+              command:
+                - buildctl
+                - debug
+                - workers
+            initialDelaySeconds: 5
+            periodSeconds: 30
+          securityContext:
+            # Rootless: no privilege escalation, runs as uid 1000. The seccomp
+            # and AppArmor unconfined settings below are what rootless needs in
+            # place of privileged: true.
+            runAsUser: 1000
+            runAsGroup: 1000
+            allowPrivilegeEscalation: false
+            seccompProfile:
+              type: Unconfined
+          ports:
+            - containerPort: 1234
+              name: buildkit
+          volumeMounts:
+            - name: buildkit-cache
+              mountPath: /home/user/.local/share/buildkit
+      volumes:
+        - name: buildkit-cache
+          persistentVolumeClaim:
+            claimName: buildkit-cache
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: buildkit-cache
+  namespace: buildkit
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      # Layer + build cache for the app image. Bump if the cache fills.
+      storage: 20Gi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: buildkit
+  namespace: buildkit
+spec:
+  selector:
+    app: buildkit
+  ports:
+    - name: buildkit
+      port: 1234
+      targetPort: 1234
+  # ClusterIP only: reachable from runner pods, not exposed outside the cluster.
+  type: ClusterIP

deploy/site-profile-universal.json

@@ -0,0 +1,24 @@
+{
+  "site": "universal",
+  "plugins": [
+    "backups",
+    "computers",
+    "employees",
+    "endpoints",
+    "geenforce",
+    "guides",
+    "knowledgebase",
+    "machines",
+    "measuringtools",
+    "network",
+    "notifications",
+    "printedparts",
+    "printers",
+    "slides",
+    "tools",
+    "usb",
+    "warranty"
+  ],
+  "locked": [],
+  "_comment": "The profile the released Windows installer is built from. Every bundled plugin that carries a manifest, so ONE exe serves any site: the wizard offers all of them and the operator ticks what that site uses. Plugins left unticked are never installed, and 'flask plugin prune-schema' drops their tables at provisioning (ADR-014). 'applications' is deliberately absent - it is manifest-less core and always ships. Build with: deploy/windows/installer/build-installer.sh deploy/site-profile-universal.json <repo>. Use site-profile.example.json instead only when a site genuinely needs a lean build; see ADR-013."
+}

deploy/site-profile.example.json

@@ -0,0 +1,11 @@
+{
+  "site": "example-site",
+  "plugins": [
+    "machines",
+    "computers",
+    "printers",
+    "network"
+  ],
+  "locked": [],
+  "_comment": "Declarative plugin selection for a site (ADR-013). Apply with: flask plugin apply-profile deploy/site-profile.example.json. 'plugins' is the set this site wants; their hard dependencies are pulled in automatically and everything installs + enables in dependency order (idempotent). Naming a plugin not on disk fails loudly. 'locked' is reserved for a future guard against removing a site-mandated plugin. apply-profile never removes plugins absent from the list - removal stays an explicit flask plugin uninstall. Run flask plugin upgrade-all after applying, then restart."
+}

deploy/windows/installer/.gitignore

@@ -0,0 +1,6 @@
+# Build output and staged payload - regenerable, and ~220MB.
+bundle/
+Output/
+# Generated by build-installer.sh from the staged bundle.
+plugins.iss
+version.iss

deploy/windows/installer/README.md

@@ -0,0 +1,247 @@
+# Windows installer
+
+Builds a single self-contained `.exe` that installs ShopDB-Flask on an
+**air-gapped** Windows Server. Nothing here ever touches the network at install
+time: Python, the wheels, the SPA and (optionally) MySQL all ship inside it.
+
+Lives with the application on purpose. The installer depends on app internals -
+`flask plugin` verbs, `site-profile.json`, `MOUNT_PATH`, the plugin registry -
+so a separate repo would drift out of step with the thing it installs.
+
+## Files
+
+| File | What it is |
+|---|---|
+| `shopdb-preflight.ps1` | Stage 1. Read-only. Changes nothing, reports what this server is missing. |
+| `shopdb-install.ps1` | Stages 0 and 2-5 plus `uninstall`. All the actual work. |
+| `shopdb-admin.ps1` | Operator console installed alongside the app: status, restart, logs, backup, plugins. |
+| `ShopDBFlask.iss` | Inno Setup wizard. A thin wrapper - it collects input and runs the stages. |
+| `build-installer.sh` | Stages the bundle from a site profile. |
+| `make-branding.py` | Generates wizard artwork and the icon from `frontend/public/*.svg`. |
+| `*.bmp`, `shopdb.ico` | Generated artwork, committed so a Windows build box needs no Python. |
+| `build-installer.ps1` | The same build, natively on Windows. No Bash needed. |
+| `bundle-lock.json` | The exact third-party payload this installer ships. Reviewed by commit. |
+| `bundle-lock.ps1` | Creates and checks that lock. Also runs on the target server. |
+| `refresh-bundle-lock.ps1` | Regenerates the lock, after showing what changed. |
+| `verify_bundle_lock.py` | The same check for the Bash builder, so Linux needs no pwsh. |
+
+## Building
+
+Two builders, same result. Use whichever machine you are on - `build-installer.ps1`
+does the whole job natively so a Windows work PC needs no Bash.
+
+```bash
+# Linux / WSL
+./build-installer.sh ../../site-profile.example.json
+```
+
+```powershell
+# Windows
+.\build-installer.ps1 -Profile ..\..\site-profile.example.json
+```
+
+Both stage the app tree, build the SPA twice, write `plugins.iss`, copy the
+installer scripts **from this directory**, and then verify the third-party
+payload against `bundle-lock.json`. They exit non-zero if it does not match.
+
+The payload itself is added by hand, and no longer needs Windows to produce:
+
+```
+bundle/wheels/               pip download -r requirements.txt --only-binary=:all: \
+                               --platform win_amd64 --python-version 314 \
+                               --implementation cp --abi cp314 -d wheels
+bundle/python/               python-3.14.x-amd64.exe
+bundle/httpplatformhandler/  httpPlatformHandler_amd64.msi
+bundle/urlrewrite/           rewrite_amd64.msi        (client-IP rule; see below)
+bundle/vcredist/             VC_redist.x64.exe        (MySQL will not install without it)
+bundle/mysql/                mysql-8.4.x-winx64.msi   (bundled-database option only)
+bundle/mysqlclient/          mysql.exe, mysqldump.exe + libcrypto/libssl (backups)
+```
+
+Then compile on Windows:
+
+```
+iscc ShopDBFlask.iss
+```
+
+**Inno Setup 6.6.0 or newer.** The wizard uses the built-in `windows11` custom
+style, which earlier versions reject. The script fails at compile time with that
+sentence rather than with a bare "WizardStyle is invalid".
+
+The wheelhouse is **cp314-locked**. A different Python minor version means a
+different wheelhouse; the installer will not use a Python it did not install.
+
+## What is pinned, and where
+
+Three layers, because no one of them covers the whole problem.
+
+| Layer | Covers | Enforced |
+|---|---|---|
+| `requirements.txt` sha256 per package | every wheel is genuinely what upstream published | `pip --require-hashes` at install; aborts on mismatch |
+| `bundle-lock.json` | the EXACT payload: wheels, Python installer, MSIs | both builders, and again on the server before anything runs |
+| git | the application tree | code review |
+
+`--require-hashes` alone is not enough. pip lists every artifact of a pinned
+version - `cffi 2.1.0` has 100 hashes - so it proves the wheel is genuine, not
+that it is the wheel this bundle was built and tested with. It also ignores
+extra files in the wheelhouse, and says nothing about the Python installer or
+the MSIs, all of which run as SYSTEM on the target server.
+
+So `bundle-lock.json` records an exact file set with a sha256 and a byte size
+each, and verification is **set equality**: a missing file, an unexpected extra
+file, or changed content all fail. There is no install-time override.
+
+The lockfile is `--universal`, so one file serves Linux (dev, Docker, CI) and the
+Windows wheelhouse. A Linux-only resolve had silently omitted `colorama`, a
+win32-only dependency of `click` - which in hash-checking mode is a hard error
+rather than a quiet omission.
+
+### Verifying the installer itself
+
+`bundle-lock.json` is **inside** the thing it describes, so it proves the payload
+was not altered between build and install - not that the `.exe` you received is
+the one that was built. That needs something out of band. Two options, in order
+of preference:
+
+1. **Authenticode-sign the `.exe`** with a GE code-signing certificate. Windows
+   then shows a real publisher instead of "Unknown", which is also what stops an
+   operator learning to click through the SmartScreen warning.
+2. **Publish a sha256 per release** through a different channel than the file
+   itself, and have the receiving site check it:
+   `Get-FileHash ShopDBFlask_Installer_*.exe -Algorithm SHA256`
+
+Neither is wired up yet. Until one is, an installer is only as trustworthy as
+the share it arrived on.
+
+### Changing what ships
+
+```powershell
+.\refresh-bundle-lock.ps1        # show what changed, write nothing
+.\refresh-bundle-lock.ps1 -Yes   # write it
+```
+
+Then **commit `bundle-lock.json`**. That commit is the review - it is the only
+place a change to what runs as SYSTEM on a customer's server becomes visible to
+a human. `refresh-bundle-lock.ps1` refuses to overwrite an existing lock until
+you have seen the diff, for that reason.
+
+To stage a bundle before its lock exists: `ALLOW_UNLOCKED=1` (Bash) or
+`-AllowUnlocked` (PowerShell). Bundles built that way must not be shipped.
+
+Verifying a live server, months later and offline:
+
+```powershell
+shopdb-admin.ps1 verify
+```
+
+## Servers this installer did not build
+
+It is built for greenfield: its own Python, its own venv, its own IIS objects.
+Its upgrade path assumes the thing being upgraded came out of a previous run.
+Two guards keep it from damaging a server that was deployed by hand.
+
+**Python minor version.** An existing venv is reused, which is right for a repair
+or an upgrade. It is wrong when the venv belongs to a different Python - the
+wheelhouse is tagged for one minor version, so pip would die at the first
+compiled package, *after* Python was installed and the app tree replaced. The
+installer compares the two up front and stops with both version numbers.
+
+**IIS objects.** Switching deployment method removes the other method's artifact,
+which is correct when the installer owns both and dangerous when it does not: a
+wrong `-MountAlias` would delete a live mount with no prompt. It now refuses
+unless there is a version stamp proving it made the install, or you pass
+`-AdoptExisting`. The refusal lists exactly what it would have removed.
+
+An existing `web.config` is never overwritten in either case.
+
+For the West Jefferson production server specifically, this is a **migration, not
+an upgrade** - prod runs Python 3.13 against a hand-built deployment, so it needs
+a deliberate window, a database backup, and web.config reconciled by hand.
+
+## Bill of materials
+
+Every build stages a CycloneDX 1.6 SBOM at `sbom.cdx.json`, inside the
+application tree, so it installs onto the server with the app. Both ecosystems,
+in one document:
+
+- **Python** - every pin in `requirements.txt`, with the sha256 the installer
+  enforces. Environment markers are ignored: a `sys_platform == 'win32'`
+  dependency still installs on the target.
+- **npm** - every package in `frontend/package-lock.json`. Build-only packages
+  are marked `scope: excluded` rather than dropped, so "not here" is
+  distinguishable from "not looked for".
+
+It ships to the server because an air-gapped site cannot be scanned from
+anywhere else. When a CVE lands, the answer is already on the box:
+
+```powershell
+shopdb-admin.ps1 verify                 # counts, and which bundle this is
+shopdb-admin.ps1 verify -Path leaflet   # is that component here, at what version
+```
+
+Generated by `scripts/generate_sbom.py` from files that are already pinned and
+committed, so it is a translation rather than a scan - no network, no extra
+toolchain on the build box, and byte-identical output for the same inputs. It is
+deliberately not in `bundle-lock.json`: its provenance is git, not the payload.
+
+## Client IP addresses
+
+IIS does not set `X-Forwarded-For` on its own, and HttpPlatformHandler connects
+from loopback. Without a rule, **every client reads as 127.0.0.1** - so the
+GE-Enforce IP allowlist, the dashboard's visitor-location lookup and per-host
+login rate limiting all stop working, silently.
+
+The wizard asks, because the two answers are mutually exclusive:
+
+- **Clients connect directly** (`-ClientIpSource direct`, the default) - installs
+  URL Rewrite from the bundle and sets `X-Forwarded-For` from `REMOTE_ADDR`.
+  Overwriting the header is what stops a client spoofing its own.
+- **A proxy sits in front** (`-ClientIpSource proxy`) - leaves the rule off.
+  Behind ARR or a load balancer `REMOTE_ADDR` is the *proxy*, so applying the
+  rule would discard the real client IP.
+
+An existing `web.config` is never overwritten - it is the one file on a server
+that legitimately carries hand-edits. The installer reports what it found
+instead.
+
+## Deployment methods
+
+Chosen in the wizard, and the bundle carries a SPA build for each because Vite
+compiles the base path in - it cannot be switched at install time.
+
+- **Its own site** on a port (default 8090).
+- **Subpath** under an existing site, e.g. `http://<server-fqdn>/shopdb/`. Needs
+  no new DNS record. Three things must agree - the IIS application alias,
+  `MOUNT_PATH` in `.env`, and the SPA's build-time base - so the alias is fixed
+  per bundle (`SUBPATH_ALIAS`, default `shopdb`) and the installer refuses if the
+  bundle's build does not match what was asked for.
+
+Switching between methods removes the other one's IIS artifact and reconciles
+`MOUNT_PATH` and `CORS_ORIGINS`, so a server never ends up with both.
+
+## Upgrades
+
+Run a newer installer over an existing install. It:
+
+- backs the database up first, **verifies** the dump is complete, and refuses to
+  migrate if it cannot;
+- restores from that backup if migrations fail, and reports honestly that DDL
+  the failed migration committed cannot be undone;
+- refuses to run a bundle older than what is installed;
+- keeps `.env` unless new credentials are supplied, and copies it aside first;
+- stops the app pool before replacing files, then starts it again.
+
+Whether a run is an upgrade is decided by probing the **target database**, not by
+whether the app directory exists - a rebuilt server pointed at an existing
+database is an upgrade, and treating it as fresh would drop tables.
+
+## Testing notes
+
+Verified end to end on Windows Server 2025 against both a bundled MySQL 8.4 LTS and
+an existing MySQL 5.6: fresh install, upgrade, re-run idempotency, failure and
+rollback, uninstall, and both deployment methods including switching between
+them.
+
+**Not yet verified:** a fully air-gapped run with the network disabled at the
+hypervisor, and any load in a real browser (all HTTP checks so far used curl,
+which sends no `Origin` header - so `CORS_ORIGINS` is untested in anger).

deploy/windows/installer/build-installer.ps1

@@ -0,0 +1,301 @@
+<#
+.SYNOPSIS
+    Stage a lean per-site installer bundle on Windows, and verify its third-party
+    payload against bundle-lock.json.
+
+.DESCRIPTION
+    The Windows equivalent of build-installer.sh, for a work PC with no Bash. It
+    does the whole job natively - it does NOT shell out to build-site.sh - so the
+    only tools needed are Python, Node and (to compile) Inno Setup.
+
+    What it does, in order:
+
+      1. Resolves the site's plugin closure from its profile.
+      2. Builds the SPA twice, because Vite compiles the base path in and it
+         therefore cannot be chosen at install time: once for /<alias> (subpath
+         deployment) and once for / (its own site).
+      3. Stages the backend tree: core, the chosen plugins only, and the runtime
+         files a deployable tree needs.
+      4. Writes plugins.iss so the wizard's plugin page matches the payload.
+      5. Copies the installer scripts from THIS directory.
+      6. Verifies wheels\, python\ and the MSIs against bundle-lock.json, and
+         FAILS if the bundle is not exactly what the lock describes.
+
+    Step 6 is the point of the script. A bundle that does not match its lock is
+    not shipped, and "the wheelhouse was missing" is caught here rather than by
+    an operator halfway through installing on a server with no network.
+
+.PARAMETER Profile
+    Path to the site profile (see deploy\site-profile.example.json).
+
+.PARAMETER RepoRoot
+    The repository. Defaults to four levels up from this script, which is correct
+    for a normal checkout.
+
+.PARAMETER SkipFrontend
+    Reuse the SPA builds already staged in the bundle. For iterating on the
+    installer itself, where two Vite builds per run is most of the wall clock.
+    Never use it for a bundle you intend to ship.
+
+.PARAMETER AllowUnlocked
+    Stage the bundle and report payload problems WITHOUT failing. For assembling
+    a bundle before its lock exists. A bundle built this way must not be shipped;
+    run refresh-bundle-lock.ps1, commit the lock, then build again without this.
+
+.EXAMPLE
+    .\build-installer.ps1 -Profile ..\..\site-profile.example.json
+    .\build-installer.ps1 -Profile C:\sites\wjf.json -SkipFrontend
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)] [string] $Profile,
+    [string] $RepoRoot     = (Resolve-Path (Join-Path $PSScriptRoot '..\..\..')).Path,
+    [string] $BundleRoot   = (Join-Path $PSScriptRoot 'bundle'),
+    [string] $SubpathAlias = 'shopdb',
+    [switch] $SkipFrontend,
+    [switch] $AllowUnlocked
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'bundle-lock.ps1')
+
+function Say  { param($m, $c = 'Gray') Write-Host $m -ForegroundColor $c }
+function Step { param($m) Write-Host ''; Write-Host "==> $m" -ForegroundColor Cyan }
+function Die  { param($m, $fix = '') Write-Host ''; Write-Host "  $m" -ForegroundColor Red
+                if ($fix) { Write-Host "  $fix" -ForegroundColor Yellow }; exit 1 }
+
+function Invoke-Tool {
+    # Runs a build tool and stops on a non-zero exit. npm writes progress to
+    # stderr on SUCCESS, so stderr alone must never be treated as failure.
+    param([string] $Exe, [string[]] $Arguments, [string] $WorkDir, [string] $What)
+    Push-Location $WorkDir
+    try {
+        $prev = $ErrorActionPreference
+        $ErrorActionPreference = 'Continue'
+        & $Exe @Arguments 2>&1 | ForEach-Object { Say "    $_" 'DarkGray' }
+        $code = $LASTEXITCODE
+        $ErrorActionPreference = $prev
+        if ($code -ne 0) { Die "$What failed (exit $code)" }
+    } finally { Pop-Location }
+}
+
+if (-not (Test-Path $Profile))  { Die "profile not found: $Profile" }
+if (-not (Test-Path $RepoRoot)) { Die "repo not found: $RepoRoot" }
+$Profile  = (Resolve-Path $Profile).Path
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+$AppOut   = Join-Path $BundleRoot 'app'
+
+$python = (Get-Command python -ErrorAction SilentlyContinue)
+if (-not $python) { $python = Get-Command py -ErrorAction SilentlyContinue }
+if (-not $python) { Die 'Python not found on PATH' 'Install Python 3.14 and re-open the shell.' }
+$npm = Get-Command npm.cmd -ErrorAction SilentlyContinue
+if (-not $npm -and -not $SkipFrontend) { Die 'npm not found on PATH' 'Install Node, or pass -SkipFrontend to reuse the staged SPA.' }
+
+Say ''
+Say "  repo    : $RepoRoot"
+Say "  profile : $Profile"
+Say "  bundle  : $BundleRoot"
+
+# --- 1. plugin closure ------------------------------------------------------
+# Same resolver the Linux builder uses, so both produce the same set from one
+# profile instead of two implementations of the closure rules.
+Step 'Resolving plugin closure'
+$closure = (& $python.Source (Join-Path $RepoRoot 'scripts\resolve_plugin_closure.py') $Profile $RepoRoot)
+if ($LASTEXITCODE -ne 0 -or -not $closure) { Die 'could not resolve the plugin closure from the profile' }
+$closure = $closure.Trim()
+Say "    $closure" 'White'
+
+# --- 2. frontend ------------------------------------------------------------
+$frontend  = Join-Path $RepoRoot 'frontend'
+$subStaged = Join-Path $BundleRoot 'spa-subpath'
+$rootStaged= Join-Path $BundleRoot 'spa-root'
+
+if ($SkipFrontend) {
+    if (-not (Test-Path $subStaged) -or -not (Test-Path $rootStaged)) {
+        Die '-SkipFrontend was passed but no SPA build is staged' 'Run once without it.'
+    }
+    Say ''
+    Say '  Reusing the staged SPA builds (-SkipFrontend). NOT shippable if the frontend changed.' 'Yellow'
+} else {
+    Step "Building the SPA for /$SubpathAlias/"
+    $env:SITE_PLUGINS    = $closure
+    $env:VITE_BASE_PATH  = "/$SubpathAlias/"
+    try   { Invoke-Tool $npm.Source @('run','build','--silent') $frontend 'subpath frontend build' }
+    finally { Remove-Item Env:\VITE_BASE_PATH -ErrorAction SilentlyContinue }
+    Remove-Item $subStaged -Recurse -Force -ErrorAction SilentlyContinue
+    Copy-Item (Join-Path $frontend 'dist') $subStaged -Recurse -Force
+    # The alias is fixed at BUILD time; the installer reads this and refuses to
+    # publish under a different one rather than serving a page that cannot load
+    # its own assets.
+    Set-Content -Path (Join-Path $subStaged '.alias') -Value $SubpathAlias -Encoding ASCII
+
+    # Root build LAST, so frontend\dist is left in the state a developer expects.
+    Step 'Building the SPA for /'
+    try   { Invoke-Tool $npm.Source @('run','build','--silent') $frontend 'root frontend build' }
+    finally { Remove-Item Env:\SITE_PLUGINS -ErrorAction SilentlyContinue }
+    Remove-Item $rootStaged -Recurse -Force -ErrorAction SilentlyContinue
+    Copy-Item (Join-Path $frontend 'dist') $rootStaged -Recurse -Force
+}
+
+# --- 3. backend tree --------------------------------------------------------
+Step "Staging the application tree"
+Remove-Item $AppOut -Recurse -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Path (Join-Path $AppOut 'plugins') -Force | Out-Null
+
+Copy-Item (Join-Path $RepoRoot 'shopdb') $AppOut -Recurse -Force
+foreach ($name in $closure.Split(',')) {
+    $src = Join-Path $RepoRoot ('plugins\' + $name.Trim())
+    if (-not (Test-Path $src)) { Die "plugin in the closure is not on disk: $name" }
+    Copy-Item $src (Join-Path $AppOut 'plugins') -Recurse -Force
+}
+
+# Runtime files a deployable tree needs beyond the Python packages. Without
+# these the tree imports but cannot be run or migrated.
+foreach ($f in @('wsgi.py', 'requirements.txt')) {
+    Copy-Item (Join-Path $RepoRoot $f) $AppOut -Force
+}
+Copy-Item (Join-Path $RepoRoot 'migrations') $AppOut -Recurse -Force
+# ONLY web.config, not all of deploy\. The bundle is staged INSIDE deploy\, so
+# copying the whole tree would recurse into its own output, and the rest of
+# deploy\ is installer source that has no business on an application server.
+# shopdb-install.ps1 reads it from exactly this path.
+$cfgSrc = Join-Path $RepoRoot 'deploy\windows\web.config'
+if (Test-Path $cfgSrc) {
+    New-Item -ItemType Directory -Path (Join-Path $AppOut 'deploy\windows') -Force | Out-Null
+    Copy-Item $cfgSrc (Join-Path $AppOut 'deploy\windows') -Force
+}
+
+# A CycloneDX SBOM of everything this tree depends on, Python and npm together.
+# Staged INTO the tree so it installs onto the server with the application: an
+# air-gapped site cannot be scanned remotely, so the only way to answer "are we
+# exposed to this CVE, and where" is for the answer to be sitting on the box.
+Step 'Generating SBOM'
+& $python.Source (Join-Path $RepoRoot 'scripts\generate_sbom.py') $RepoRoot `
+    -o (Join-Path $AppOut 'sbom.cdx.json') | ForEach-Object { Say "    $_" 'White' }
+if ($LASTEXITCODE -ne 0) { Die 'SBOM generation failed' }
+
+# Docs the running site serves, plus the runbooks an air-gapped server has no
+# other way to reach. Without openapi.json and llms.txt the self-hosted /api/docs
+# page is broken on every installed server.
+Step 'Staging docs'
+$docsOut = Join-Path $AppOut 'docs'
+New-Item -ItemType Directory -Path $docsOut -Force | Out-Null
+foreach ($doc in @('openapi.json', 'llms.txt', 'api-inventory.json',
+                   'INSTALL-WINDOWS.md', 'OPERATE-WINDOWS.md',
+                   'BACKUP-RESTORE.md', 'UPGRADE.md')) {
+    $src = Join-Path $RepoRoot ('docs\' + $doc)
+    if (Test-Path $src) { Copy-Item $src $docsOut -Force; Say "    $doc" }
+}
+
+# Stage the profile INTO the tree: `flask plugin apply-profile` at provisioning
+# reads the same profile the tree was staged from, so the installed plugin set
+# and the shipped plugin code cannot drift.
+Copy-Item $Profile (Join-Path $AppOut 'site-profile.json') -Force
+
+# The installer expects frontend\dist and frontend\dist-subpath.
+$feOut = Join-Path $AppOut 'frontend'
+New-Item -ItemType Directory -Path $feOut -Force | Out-Null
+Copy-Item $rootStaged (Join-Path $feOut 'dist')         -Recurse -Force
+Copy-Item $subStaged  (Join-Path $feOut 'dist-subpath') -Recurse -Force
+
+Get-ChildItem $AppOut -Recurse -Directory -Filter '__pycache__' -ErrorAction SilentlyContinue |
+    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
+Get-ChildItem $AppOut -Recurse -File -Filter '*.pyc' -ErrorAction SilentlyContinue |
+    Remove-Item -Force -ErrorAction SilentlyContinue
+
+# --- 4. plugins.iss ---------------------------------------------------------
+Step 'Writing plugins.iss'
+$shipped = (Get-ChildItem (Join-Path $AppOut 'plugins') -Directory | Select-Object -ExpandProperty Name) -join ','
+$aliasBuilt = ''
+$aliasFile  = Join-Path $feOut 'dist-subpath\.alias'
+if (Test-Path $aliasFile) { $aliasBuilt = (Get-Content $aliasFile -TotalCount 1).Trim() }
+@"
+; GENERATED by build-installer.ps1 - do not edit.
+; The plugins present in bundle\app\plugins at build time.
+#define AvailablePlugins "$shipped"
+; The alias the subpath SPA was built for, or empty if this bundle has no
+; subpath build - in which case the wizard must not offer that option.
+#define SubpathAlias "$aliasBuilt"
+"@ | Set-Content -Path (Join-Path $PSScriptRoot 'plugins.iss') -Encoding ASCII
+Say "    $shipped" 'White'
+
+# The product version, read from the code rather than restated in the .iss.
+Step 'Writing version.iss'
+$initText = Get-Content (Join-Path $RepoRoot 'shopdb\__init__.py') -Raw
+if ($initText -notmatch "(?m)^__version__\s*=\s*'([^']+)'") { Die 'could not read __version__ from shopdb\__init__.py' }
+$appVersion = $Matches[1]
+@"
+; GENERATED by build-installer.ps1 from shopdb/__init__.py - do not edit.
+#define AppVersion "$appVersion"
+"@ | Set-Content -Path (Join-Path $PSScriptRoot 'version.iss') -Encoding ASCII
+Say "    $appVersion" 'White'
+
+# --- 5. installer scripts ---------------------------------------------------
+# From THIS directory, which is the reviewed copy under version control. They
+# used to be copied from a downloads folder, so the logic that shipped was not
+# the logic that was committed and the build only worked on one machine.
+Step 'Copying installer scripts'
+foreach ($f in @('shopdb-install.ps1', 'shopdb-preflight.ps1', 'bundle-lock.ps1')) {
+    $src = Join-Path $PSScriptRoot $f
+    if (-not (Test-Path $src)) { Die "installer script missing from the repo: $f" }
+    Copy-Item $src $BundleRoot -Force
+    Say "    $f"
+}
+
+# --- 6. payload verification ------------------------------------------------
+Step 'Verifying the third-party payload against bundle-lock.json'
+$lockPath = Join-Path $PSScriptRoot 'bundle-lock.json'
+$lock = Read-BundleLock $lockPath
+if (-not $lock) {
+    $msg = "no bundle-lock.json at $lockPath"
+    if ($AllowUnlocked) { Say "  $msg - continuing because -AllowUnlocked was passed" 'Yellow' }
+    else {
+        Die $msg @'
+Add the wheels and installers to the bundle, then:
+    .\refresh-bundle-lock.ps1        (review the list)
+    .\refresh-bundle-lock.ps1 -Yes   (write it)
+and commit bundle-lock.json. Pass -AllowUnlocked to stage a bundle without one -
+it must not be shipped.
+'@
+    }
+} else {
+    $problems = Test-BundleLock -BundleRoot $BundleRoot -Lock $lock
+    if ($problems.Count -eq 0) {
+        Say ("    payload matches the lock ({0}, {1})" -f `
+             (Get-JsonProperty $lock 'pythontag' 'unknown'), (Get-JsonProperty $lock 'platform' 'unknown')) 'Green'
+        # Ships WITH the bundle: the installer re-checks the payload on the
+        # target server before running any of it, so tampering between build and
+        # install is caught too.
+        Copy-Item $lockPath $BundleRoot -Force
+    } else {
+        Say ''
+        foreach ($p in $problems) { Say "    $p" 'Red' }
+        Say ''
+        if ($AllowUnlocked) {
+            Say '  -AllowUnlocked: continuing anyway. DO NOT SHIP this bundle.' 'Yellow'
+        } else {
+            Die ("{0} payload problem(s) - the bundle is not what the lock describes" -f $problems.Count) @'
+Either the payload is wrong (fix the bundle) or it changed on purpose (run
+refresh-bundle-lock.ps1, read the diff, and commit the new lock).
+'@
+        }
+    }
+}
+
+# --- summary ----------------------------------------------------------------
+Write-Host ''
+Say "  Bundle staged at: $BundleRoot" 'White'
+foreach ($d in @('app', 'wheels', 'python', 'httpplatformhandler', 'urlrewrite', 'vcredist', 'mysqlclient', 'mysql')) {
+    $p = Join-Path $BundleRoot $d
+    if (Test-Path $p) {
+        $mb = ((Get-ChildItem $p -Recurse -File | Measure-Object Length -Sum).Sum / 1MB)
+        Say ("    {0,-22} {1,8:N1} MB" -f $d, $mb)
+    } else {
+        Say ("    {0,-22} {1}" -f $d, 'absent') 'DarkGray'
+    }
+}
+Write-Host ''
+Say '  Compile with:  iscc ShopDBFlask.iss' 'White'
+Say '  (Inno Setup 6.6.0 or newer - the wizard uses the windows11 custom style.)' 'DarkGray'
+Write-Host ''

deploy/windows/installer/build-installer.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# Stage a lean per-site bundle next to ShopDBFlask.iss, ready for Inno Setup.
+#
+# The bundle is built FOR ONE SITE from its plugin profile (ADR-013): plugins the
+# site did not choose are absent from the payload entirely. Build one installer
+# per site, not one universal installer.
+#
+# Usage: build-installer.sh <site-profile.json> [repo-path]
+#
+# The wheelhouse cannot be built here. Wheels are cp314 win_amd64 and must be
+# produced ON Windows with the matching Python:
+#   pip download -r requirements.txt -d wheels --only-binary=:all:
+# Copy that wheels\ directory in before compiling.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROFILE="${1:?usage: build-installer.sh <site-profile.json> [repo-path]}"
+REPO="${2:-$HOME/projects/shopdb-flask}"
+BUNDLE="$HERE/bundle"
+
+[ -f "$PROFILE" ] || { echo "profile not found: $PROFILE"; exit 1; }
+[ -d "$REPO" ]    || { echo "repo not found: $REPO"; exit 1; }
+
+echo "==> Staging lean app tree from $PROFILE"
+rm -rf "$BUNDLE/app"
+bash "$REPO/scripts/build-site.sh" "$PROFILE" "$BUNDLE/app"
+
+# build-site.sh emits the SPA as frontend-dist; the installer's web.config and
+# static route expect frontend\dist.
+if [ -d "$BUNDLE/app/frontend-dist" ]; then
+    mkdir -p "$BUNDLE/app/frontend"
+    rm -rf "$BUNDLE/app/frontend/dist"
+    mv "$BUNDLE/app/frontend-dist" "$BUNDLE/app/frontend/dist"
+fi
+# The /shopdb-based build, used when the operator picks the subpath deployment.
+if [ -d "$BUNDLE/app/frontend-dist-subpath" ]; then
+    rm -rf "$BUNDLE/app/frontend/dist-subpath"
+    mv "$BUNDLE/app/frontend-dist-subpath" "$BUNDLE/app/frontend/dist-subpath"
+fi
+
+# Tell the .iss which plugins this bundle actually carries, so the wizard's
+# plugin page always matches the payload instead of a hand-maintained list.
+echo "==> Writing plugins.iss"
+PLUGINS=$(ls "$BUNDLE/app/plugins" 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+# The subpath SPA is built with its base path compiled in, so whether the wizard
+# can OFFER a subpath install is a property of the bundle, not a runtime choice.
+SUBPATH_ALIAS_BUILT=""
+if [ -f "$BUNDLE/app/frontend/dist-subpath/.alias" ]; then
+    SUBPATH_ALIAS_BUILT="$(cat "$BUNDLE/app/frontend/dist-subpath/.alias")"
+fi
+
+cat > "$HERE/plugins.iss" <<EOF
+; GENERATED by build-installer.sh - do not edit.
+; The plugins present in bundle\\app\\plugins at build time.
+#define AvailablePlugins "$PLUGINS"
+; The alias the subpath SPA was built for, or empty if this bundle has no
+; subpath build - in which case the wizard must not offer that option.
+#define SubpathAlias "$SUBPATH_ALIAS_BUILT"
+EOF
+echo "    $PLUGINS"
+
+# The product version, read from the code rather than restated here. A hardcoded
+# AppVersion in the .iss had drifted two minor versions from shopdb/__init__.py.
+echo "==> Writing version.iss"
+APPVERSION=$(sed -n "s/^__version__ = '\\(.*\\)'/\\1/p" "$REPO/shopdb/__init__.py" | head -1)
+[ -n "$APPVERSION" ] || { echo "could not read __version__ from shopdb/__init__.py"; exit 1; }
+cat > "$HERE/version.iss" <<EOF
+; GENERATED by build-installer.sh from shopdb/__init__.py - do not edit.
+#define AppVersion "$APPVERSION"
+EOF
+echo "    $APPVERSION"
+
+# From THIS directory, which is the reviewed copy under version control. These
+# used to be copied from $HOME/Downloads, so the installer logic that shipped was
+# not the logic that was committed, and the build only worked on one machine.
+echo "==> Copying installer scripts"
+mkdir -p "$BUNDLE"
+for f in shopdb-install.ps1 shopdb-preflight.ps1 bundle-lock.ps1; do
+    [ -f "$HERE/$f" ] || { echo "installer script missing from the repo: $f"; exit 1; }
+    cp "$HERE/$f" "$BUNDLE/"
+done
+
+echo ""
+echo "Bundle staged at: $BUNDLE"
+for d in app wheels python httpplatformhandler urlrewrite vcredist mysqlclient mysql; do
+    if [ -d "$BUNDLE/$d" ]; then
+        printf '  %-20s %s\n' "$d" "$(du -sh "$BUNDLE/$d" | cut -f1)"
+    else
+        printf '  %-20s absent\n' "$d"
+    fi
+done
+echo ""
+echo "  plugins shipped: $(ls "$BUNDLE/app/plugins" 2>/dev/null | tr '\n' ' ')"
+
+# --- payload verification ---------------------------------------------------
+# The third-party payload is the part git does not record: the wheels, the Python
+# installer and the MSIs that run as SYSTEM on the target server. It must be
+# EXACTLY what bundle-lock.json describes - no missing file, no stale extra wheel
+# left over from a previous build, no changed content - or this is not a bundle
+# anyone reviewed. Previously a missing wheelhouse printed MISSING and the script
+# still exited 0, so an empty bundle compiled into a shippable installer and the
+# failure surfaced on an air-gapped server with no way to fix it.
+#
+# ALLOW_UNLOCKED=1 downgrades this to a warning, for assembling a bundle before
+# its lock exists. A bundle built that way must not be shipped.
+echo ""
+echo "==> Verifying the third-party payload against bundle-lock.json"
+if python3 "$HERE/verify_bundle_lock.py" "$BUNDLE" "$HERE/bundle-lock.json"; then
+    echo "  payload matches the lock"
+    # Ships WITH the bundle: the installer re-checks the payload on the target
+    # server before running any of it, so tampering between build and install is
+    # caught too.
+    cp "$HERE/bundle-lock.json" "$BUNDLE/"
+elif [ "${ALLOW_UNLOCKED:-0}" = "1" ]; then
+    echo ""
+    echo "  ALLOW_UNLOCKED=1: continuing anyway. DO NOT SHIP this bundle."
+else
+    echo ""
+    echo "  The bundle is not what the lock describes."
+    echo ""
+    echo "  Add the missing pieces by hand:"
+    echo "    wheels/              pip download -r requirements.txt --only-binary=:all: \\"
+    echo "                           --platform win_amd64 --python-version 314 \\"
+    echo "                           --implementation cp --abi cp314 -d wheels"
+    echo "    python/              python-3.14.x-amd64.exe"
+    echo "    httpplatformhandler/ httpPlatformHandler_amd64.msi"
+    echo "    urlrewrite/          rewrite_amd64.msi       (client-IP rule; see README)"
+    echo "    vcredist/            VC_redist.x64.exe       (MySQL requires it)"
+    echo "    mysql/               mysql-8.4.x-winx64.msi  (bundled-database option only)"
+    echo ""
+    echo "  If the payload changed ON PURPOSE, regenerate and COMMIT the lock:"
+    echo "    pwsh ./refresh-bundle-lock.ps1        # review the diff"
+    echo "    pwsh ./refresh-bundle-lock.ps1 -Yes   # write it"
+    echo ""
+    echo "  To stage a bundle before its lock exists:  ALLOW_UNLOCKED=1 $0 ..."
+    exit 1
+fi
+
+echo ""
+echo "Then compile on Windows:  iscc ShopDBFlask.iss"
+echo "(Inno Setup 6.6.0 or newer - the wizard uses the windows11 custom style.)"

deploy/windows/installer/bundle-lock.json

@@ -0,0 +1,240 @@
+{
+  "schema": 1,
+  "generated": "2026-08-04T23:11:22Z",
+  "pythontag": "cp314",
+  "platform": "win_amd64",
+  "note": "Exact third-party payload of the installer bundle. Regenerate with refresh-bundle-lock.ps1 and COMMIT the change as a reviewed dependency bump.",
+  "payloads": {
+    "httpplatformhandler": {
+      "files": {
+        "httpPlatformHandler_amd64.msi": {
+          "sha256": "90f8d4905a0ab4f2c95223b3c79e2807a0b74507747d240e43c4302e8db4b5ef",
+          "size": 557056
+        }
+      },
+      "required": true
+    },
+    "python": {
+      "files": {
+        "python-3.14.6-amd64.exe": {
+          "sha256": "14b3e9a710a3fcf0bd9b55ab6b60412bd91227563f813fc49040cabc0209e0bd",
+          "size": 30774112
+        }
+      },
+      "required": true
+    },
+    "vcredist": {
+      "files": {
+        "VC_redist.x64.exe": {
+          "sha256": "cc0ff0eb1dc3f5188ae6300faef32bf5beeba4bdd6e8e445a9184072096b713b",
+          "size": 25635768
+        }
+      },
+      "required": false
+    },
+    "mysql": {
+      "files": {
+        "mysql-8.4.6-winx64.msi": {
+          "sha256": "868885b2e221409f0170729bb30b2b2ce83440a1a4c735d19b3c225b51045762",
+          "size": 135081984
+        }
+      },
+      "required": false
+    },
+    "wheels": {
+      "files": {
+        "email_validator-2.3.0-py3-none-any.whl": {
+          "sha256": "80f13f623413e6b197ae73bb10bf4eb0908faf509ad8362c5edeb0be7fd450b4",
+          "size": 35604
+        },
+        "cachelib-0.13.0-py3-none-any.whl": {
+          "sha256": "8c8019e53b6302967d4e8329a504acf75e7bc46130291d30188a6e4e58162516",
+          "size": 20914
+        },
+        "flask_caching-2.4.0-py3-none-any.whl": {
+          "sha256": "d15b8135f055c4f28f6f7dbcf8d36a3de4af1224def975ae6e0b43cbfa684486",
+          "size": 28727
+        },
+        "typing_extensions-4.15.0-py3-none-any.whl": {
+          "sha256": "f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548",
+          "size": 44614
+        },
+        "greenlet-3.5.0-cp314-cp314-win_amd64.whl": {
+          "sha256": "3bc59be3945ae9750b9e7d45067d01ae3fe90ea5f9ade99239dabdd6e28a5033",
+          "size": 239835
+        },
+        "charset_normalizer-3.4.7-cp314-cp314-win_amd64.whl": {
+          "sha256": "92a0a01ead5e668468e952e4238cccd7c537364eb7d851ab144ab6627dbbe12f",
+          "size": 159634
+        },
+        "colorama-0.4.6-py2.py3-none-any.whl": {
+          "sha256": "4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6",
+          "size": 25335
+        },
+        "Flask_Migrate-4.1.0-py3-none-any.whl": {
+          "sha256": "24d8051af161782e0743af1b04a152d007bad9772b2bca67b7ec1e8ceeb3910d",
+          "size": 21237
+        },
+        "markupsafe-3.0.3-cp314-cp314-win_amd64.whl": {
+          "sha256": "bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581",
+          "size": 15341
+        },
+        "flask_marshmallow-1.5.0-py3-none-any.whl": {
+          "sha256": "99951c77e5654111ed733811c6dc9310bfb4c3688c78a9e76f80b5ae0b2279a6",
+          "size": 12161
+        },
+        "tzdata-2026.3-py2.py3-none-any.whl": {
+          "sha256": "dc096730c87af6cab1b171c9d532be840741ff5d459015e7f6947bd7d7e54931",
+          "size": 348168
+        },
+        "python_dotenv-1.2.2-py3-none-any.whl": {
+          "sha256": "1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a",
+          "size": 22101
+        },
+        "dnspython-2.8.0-py3-none-any.whl": {
+          "sha256": "01d9bbc4a2d76bf0db7c1f729812ded6d912bd318d3b1cf81d30c0f845dbf3af",
+          "size": 331094
+        },
+        "pymysql-1.1.3-py3-none-any.whl": {
+          "sha256": "8164ba62c552f6105f3b11753352d0f16b90d1703ba67d81923d5a8a5d1c5289",
+          "size": 45356
+        },
+        "packaging-26.3-py3-none-any.whl": {
+          "sha256": "d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c",
+          "size": 129956
+        },
+        "flask_jwt_extended-4.7.3-py2.py3-none-any.whl": {
+          "sha256": "905ac807b52b5409bc9244dbcca434968c13ca6f9d91bffe7d4cb71e0e6231cb",
+          "size": 22698
+        },
+        "urllib3-2.7.0-py3-none-any.whl": {
+          "sha256": "9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897",
+          "size": 131087
+        },
+        "marshmallow-4.3.0-py3-none-any.whl": {
+          "sha256": "46c4fe6984707e3cbd485dfebbf0a59874f58d695aad05c1668d15e8c6e13b46",
+          "size": 49148
+        },
+        "waitress-3.0.2-py3-none-any.whl": {
+          "sha256": "c56d67fd6e87c2ee598b76abdd4e96cfad1f24cacdea5078d382b1f9d7b5ed2e",
+          "size": 56232
+        },
+        "idna-3.13-py3-none-any.whl": {
+          "sha256": "892ea0cde124a99ce773decba204c5552b69c3c67ffd5f232eb7696135bc8bb3",
+          "size": 68629
+        },
+        "flask-3.1.3-py3-none-any.whl": {
+          "sha256": "f4bcbefc124291925f1a26446da31a5178f9483862233b23c0c96a20701f670c",
+          "size": 103424
+        },
+        "werkzeug-3.1.8-py3-none-any.whl": {
+          "sha256": "63a77fb8892bf28ebc3178683445222aa500e48ebad5ec77b0ad80f8726b1f50",
+          "size": 226459
+        },
+        "flask_sqlalchemy-3.1.1-py3-none-any.whl": {
+          "sha256": "4ba4be7f419dc72f4efd8802d69974803c37259dd42f3913b0dcf75c9447e0a0",
+          "size": 25125
+        },
+        "marshmallow_sqlalchemy-1.5.0-py3-none-any.whl": {
+          "sha256": "3865232672f3dd38c4d5e4e85fdedce76904200742c3594948a2d11d0af93258",
+          "size": 16582
+        },
+        "alembic-1.18.4-py3-none-any.whl": {
+          "sha256": "a5ed4adcf6d8a4cb575f3d759f071b03cd6e5c7618eb796cb52497be25bfe19a",
+          "size": 263893
+        },
+        "tabulate-0.10.0-py3-none-any.whl": {
+          "sha256": "f0b0622e567335c8fabaaa659f1b33bcb6ddfe2e496071b743aa113f8774f2d3",
+          "size": 39814
+        },
+        "cffi-2.1.0-cp314-cp314-win_amd64.whl": {
+          "sha256": "1b96bfe2c4bd825681b7d311ad6d9b7280a091f43e8f63da5729638083cd3bfb",
+          "size": 187937
+        },
+        "jinja2-3.1.6-py3-none-any.whl": {
+          "sha256": "85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67",
+          "size": 134899
+        },
+        "cryptography-50.0.0-cp311-abi3-win_amd64.whl": {
+          "sha256": "bd1c592e4d5974f0d08d4888e432157adba757c66da0246918e43677fafa2d30",
+          "size": 3840395
+        },
+        "certifi-2026.4.22-py3-none-any.whl": {
+          "sha256": "3cb2210c8f88ba2318d29b0388d1023c8492ff72ecdde4ebdaddbb13a31b1c4a",
+          "size": 135707
+        },
+        "sqlalchemy-2.0.49-cp314-cp314-win_amd64.whl": {
+          "sha256": "77641d299179c37b89cf2343ca9972c88bb6eef0d5fc504a2f86afd15cd5adf5",
+          "size": 2144204
+        },
+        "blinker-1.9.0-py3-none-any.whl": {
+          "sha256": "ba0efaa9080b619ff2f3459d1d500c57bddea4a6b424b60a91141db6fd2f08bc",
+          "size": 8458
+        },
+        "pycparser-3.0-py3-none-any.whl": {
+          "sha256": "b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992",
+          "size": 48172
+        },
+        "flask_cors-6.0.2-py3-none-any.whl": {
+          "sha256": "e57544d415dfd7da89a9564e1e3a9e515042df76e12130641ca6f3f2f03b699a",
+          "size": 13257
+        },
+        "requests-2.33.1-py3-none-any.whl": {
+          "sha256": "4e6d1ef462f3626a1f0a0a9c42dd93c63bad33f9f1c1937509b8c5c8718ab56a",
+          "size": 64947
+        },
+        "pyjwt-2.12.1-py3-none-any.whl": {
+          "sha256": "28ca37c070cad8ba8cd9790cd940535d40274d22f80ab87f3ac6a713e6e8454c",
+          "size": 29726
+        },
+        "click-8.3.3-py3-none-any.whl": {
+          "sha256": "a2bf429bb3033c89fa4936ffb35d5cb471e3719e1f3c8a7c3fff0b8314305613",
+          "size": 110502
+        },
+        "mysql_connector_python-9.7.0-cp314-cp314-win_amd64.whl": {
+          "sha256": "5a5abbc152bc28cb2e64a04605ecd9941eff6b0dc5f9528cb84adb873e9a1e49",
+          "size": 18197576
+        },
+        "mako-1.3.12-py3-none-any.whl": {
+          "sha256": "8f61569480282dbf557145ce441e4ba888be453c30989f879f0d652e39f53ea9",
+          "size": 78521
+        },
+        "itsdangerous-2.2.0-py3-none-any.whl": {
+          "sha256": "c6242fc49e35958c8b15141343aa660db5fc54d4f13a1db01a3f5891b98700ef",
+          "size": 16234
+        }
+      },
+      "required": true
+    },
+    "urlrewrite": {
+      "files": {
+        "rewrite_amd64_en-US.msi": {
+          "sha256": "37342ff2f585f263f34f48e9de59eb1051d61015a8e967dbde4075716230a32a",
+          "size": 6078464
+        }
+      },
+      "required": false
+    },
+    "mysqlclient": {
+      "files": {
+        "libcrypto-3-x64.dll": {
+          "sha256": "e84ec61fc1b07a3c899ae39c1dc3f38591cdd310c043a388e7ab40a6828aa297",
+          "size": 5187216
+        },
+        "mysqldump.exe": {
+          "sha256": "329410b7a8ae3d68d38e6f5b781610770854d3f11b975060e231dae62c20dc46",
+          "size": 7142528
+        },
+        "mysql.exe": {
+          "sha256": "bd6880253c1853fc17b1e19129d6e5d9f9c86a2dccf2c7c9e6b878a10baa9770",
+          "size": 7177336
+        },
+        "libssl-3-x64.dll": {
+          "sha256": "e24fcd6c8ec31a14c97f520b5b960ed360c55ddf0935040eff297e511697633e",
+          "size": 788616
+        }
+      },
+      "required": false
+    }
+  }
+}

deploy/windows/installer/bundle-lock.ps1

@@ -0,0 +1,261 @@
+<#
+.SYNOPSIS
+    Hash manifest for the installer's third-party payload: create it, and check a
+    bundle against it.
+
+.DESCRIPTION
+    Dot-source this. It defines two functions and runs nothing on its own:
+
+      New-BundleLock   hash a staged bundle and return the lock object
+      Test-BundleLock  compare a staged bundle against a lock, return problems
+
+    WHAT IT COVERS, and why pip's own hash checking is not enough.
+
+    requirements.txt carries a sha256 for every wheel, so pip refuses an artifact
+    upstream did not publish. Three gaps remain, and all three are what actually
+    goes wrong with a hand-assembled offline bundle:
+
+      1. pip lists EVERY artifact of a pinned version - cffi 2.1.0 alone has 100
+         hashes. It proves the wheel is genuine, not that it is the wheel this
+         bundle was built and tested with.
+      2. pip ignores extra files in the wheelhouse. A stale wheel left behind by
+         a previous build sits there unnoticed until a resolve picks it up.
+      3. pip says nothing about the rest of the payload - the Python installer,
+         the HttpPlatformHandler MSI, URL Rewrite, MySQL. Those are executables
+         that run as SYSTEM on the target server and were, until this file, the
+         only unverified thing the installer would run.
+
+    So the lock records an exact file set with a sha256 and a byte size each, and
+    verification is SET EQUALITY: a missing file, an unexpected extra file, or a
+    changed file all fail. Nothing is skipped and nothing is "close enough".
+
+    The app tree is deliberately NOT covered. It is built from the repository on
+    every run and changes with every commit; hashing it would make the lock churn
+    constantly and train everyone to regenerate it without reading it. Git is the
+    record for the app tree. This file is the record for everything that comes
+    from outside the repository.
+
+.NOTES
+    Stock Windows PowerShell 5.1, and also runs under pwsh on Linux so the Bash
+    builder can call the same checker.
+#>
+
+# Payload directories under the bundle root. 'required' means the installer
+# cannot work without it; the optional ones are per-deployment choices, and an
+# absent optional directory is fine. A PRESENT directory is always checked in
+# full, optional or not.
+$script:BundlePayloads = @(
+    @{ Name = 'wheels';              Required = $true;  What = 'Python wheels for the offline install' }
+    @{ Name = 'python';              Required = $true;  What = 'the Python installer' }
+    @{ Name = 'httpplatformhandler'; Required = $true;  What = 'the IIS module that launches waitress' }
+    @{ Name = 'urlrewrite';          Required = $false; What = 'IIS URL Rewrite, for the client-IP rule' }
+    @{ Name = 'mysqlclient';         Required = $false; What = 'mysql/mysqldump, for backups against a remote database' }
+    @{ Name = 'vcredist';            Required = $false; What = 'the Visual C++ runtime MySQL requires' }
+    @{ Name = 'mysql';               Required = $false; What = 'MySQL, for the bundled-database option' }
+)
+
+function Get-JsonProperty {
+    # shopdb-install.ps1 runs under Set-StrictMode 2.0, where reading a property
+    # that does not exist on a PSCustomObject THROWS instead of returning $null.
+    # A truncated or hand-edited bundle-lock.json would therefore blow up with
+    # "Property 'payloads' cannot be found" rather than saying what is wrong with
+    # the lock. Every read of parsed JSON goes through here.
+    param($Object, [string] $Name, $Default = $null)
+    if ($null -eq $Object) { return $Default }
+    $prop = $Object.PSObject.Properties[$Name]
+    if ($null -eq $prop) { return $Default }
+    return $prop.Value
+}
+
+function Get-FileDigest {
+    param([string] $Path)
+    $sha = [System.Security.Cryptography.SHA256]::Create()
+    $stream = [System.IO.File]::OpenRead($Path)
+    try   { return (-join ($sha.ComputeHash($stream) | ForEach-Object { $_.ToString('x2') })) }
+    finally { $stream.Dispose(); $sha.Dispose() }
+}
+
+function Get-PayloadFiles {
+    <#
+      Every file in the directory, keyed by its path RELATIVE to that directory
+      with forward slashes, so a lock generated on Windows reads the same from
+      the Bash builder.
+
+      The root comes from Get-Item, NOT Resolve-Path, and the prefix is checked
+      before it is trimmed. Both matter, and a real install proved it:
+
+      Inno extracts the bundle under C:\Users\ADMINI~1\AppData\Local\Temp\... -
+      an 8.3 SHORT path. Resolve-Path kept that short form while Get-ChildItem
+      returned the long one (Administrator), so the root was five characters
+      shorter than the prefix it was slicing off. Every relative path came out
+      mangled - 'wheels/heels/flask.whl' - and the verifier reported all 96 files
+      as simultaneously missing and unexpected. The payload was fine; the
+      comparison was not.
+
+      Get-Item and Get-ChildItem go through the same provider, so their path
+      forms agree. The StartsWith guard means that if they ever disagree again
+      this fails loudly instead of inventing paths.
+    #>
+    param([string] $Dir)
+    $out = @{}
+    if (-not (Test-Path $Dir)) { return $out }
+    $rootItem = Get-Item -LiteralPath $Dir
+    $root = $rootItem.FullName.TrimEnd('\', '/')
+    foreach ($f in (Get-ChildItem -LiteralPath $rootItem.FullName -Recurse -File)) {
+        if (-not $f.FullName.StartsWith($root, [System.StringComparison]::OrdinalIgnoreCase)) {
+            throw ("cannot place '{0}' beneath '{1}' - path forms disagree (8.3 short name?)" -f $f.FullName, $root)
+        }
+        $rel = $f.FullName.Substring($root.Length).TrimStart('\', '/').Replace('\', '/')
+        $out[$rel] = @{ sha256 = (Get-FileDigest $f.FullName); size = $f.Length }
+    }
+    return $out
+}
+
+function New-BundleLock {
+    <#
+      Hash a staged bundle. The caller writes the result to bundle-lock.json;
+      this returns the object so a caller can diff it against the committed lock
+      before overwriting anything.
+    #>
+    param(
+        [Parameter(Mandatory = $true)] [string] $BundleRoot,
+        [string] $PythonTag = 'cp314',
+        [string] $Platform  = 'win_amd64'
+    )
+    $payloads = @{}
+    foreach ($p in $script:BundlePayloads) {
+        $dir = Join-Path $BundleRoot $p.Name
+        if (-not (Test-Path $dir)) {
+            if ($p.Required) { throw ("payload directory is missing: {0} ({1})" -f $p.Name, $p.What) }
+            continue
+        }
+        $files = Get-PayloadFiles $dir
+        if ($files.Count -eq 0 -and $p.Required) {
+            throw ("payload directory is empty: {0} ({1})" -f $p.Name, $p.What)
+        }
+        $payloads[$p.Name] = @{ required = $p.Required; files = $files }
+    }
+    return [ordered]@{
+        schema     = 1
+        generated  = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+        pythontag  = $PythonTag
+        platform   = $Platform
+        note       = 'Exact third-party payload of the installer bundle. Regenerate with refresh-bundle-lock.ps1 and COMMIT the change as a reviewed dependency bump.'
+        payloads   = $payloads
+    }
+}
+
+function Test-BundleLock {
+    <#
+      Compare a staged bundle against a lock. Returns an array of problem
+      strings - EMPTY means the bundle is exactly what the lock describes.
+
+      Returning problems rather than throwing is deliberate: an operator fixing a
+      wheelhouse wants the whole list at once, not one failure per rebuild.
+    #>
+    param(
+        [Parameter(Mandatory = $true)] [string] $BundleRoot,
+        [Parameter(Mandatory = $true)] $Lock
+    )
+    $problems = @()
+    $payloads = Get-JsonProperty $Lock 'payloads'
+    # ,@(...) for the same reason as the final return: a bare one-element array
+    # unrolls to a string, and the caller's .Count then measures the wrong thing.
+    if ($null -eq $payloads) { return ,@('bundle-lock.json has no "payloads" section') }
+
+    foreach ($p in $script:BundlePayloads) {
+        $name    = $p.Name
+        $dir     = Join-Path $BundleRoot $name
+        $present = Test-Path $dir
+        $entry   = Get-JsonProperty $payloads $name
+        $locked  = ($null -ne $entry)
+
+        if (-not $locked) {
+            # Not in the lock at all. An unlocked directory that exists is a
+            # payload nobody reviewed, which is exactly what this is here to stop.
+            if ($present) { $problems += "$name/ is present but is not in bundle-lock.json - regenerate the lock" }
+            elseif ($p.Required) { $problems += "$name/ is required but is in neither the bundle nor the lock" }
+            continue
+        }
+        if (-not $present) {
+            if ($p.Required -or (Get-JsonProperty $entry 'required' $false)) {
+                $problems += "$name/ is in the lock but missing from the bundle ($($p.What))"
+            }
+            continue
+        }
+
+        $expected = @{}
+        $lockedFiles = Get-JsonProperty $entry 'files'
+        if ($null -ne $lockedFiles) {
+            foreach ($prop in $lockedFiles.PSObject.Properties) { $expected[$prop.Name] = $prop.Value }
+        }
+        $actual = Get-PayloadFiles $dir
+
+        # Sorted so the report reads the same way twice, and so it matches the
+        # order verify_bundle_lock.py produces.
+        foreach ($rel in ($expected.Keys | Sort-Object)) {
+            if (-not $actual.ContainsKey($rel)) { $problems += "$name/$rel is in the lock but missing from the bundle"; continue }
+            if ($actual[$rel].sha256 -ne $expected[$rel].sha256) {
+                $problems += "$name/$rel does NOT match the lock (expected sha256 $($expected[$rel].sha256.Substring(0,12))..., got $($actual[$rel].sha256.Substring(0,12))...)"
+            } elseif ([int64] $actual[$rel].size -ne [int64] $expected[$rel].size) {
+                # Cannot happen for a matching sha256, so it means the lock itself
+                # was hand-edited. Say so rather than passing it.
+                $problems += "$name/$rel size disagrees with the lock - the lock has been edited by hand"
+            }
+        }
+        foreach ($rel in ($actual.Keys | Sort-Object)) {
+            if (-not $expected.ContainsKey($rel)) { $problems += "$name/$rel is in the bundle but NOT in the lock (unexpected extra file)" }
+        }
+    }
+    $problems += Test-WheelhouseCoversRequirements -BundleRoot $BundleRoot
+    # The comma keeps this an ARRAY through the return. Without it PowerShell
+    # unrolls an empty result to $null and a single result to a bare string, and
+    # every caller that asks for .Count then behaves differently depending on how
+    # many problems there happen to be.
+    return ,$problems
+}
+
+function Test-WheelhouseCoversRequirements {
+    <#
+      The lock records what IS in the wheelhouse, not what the application NEEDS.
+      Without this an incomplete wheelhouse gets locked, blessed, and shipped,
+      and the install fails on an air-gapped server.
+
+      Not hypothetical: assembling the wheelhouse anywhere other than Windows
+      silently omits colorama, a win32-only dependency of click, because pip
+      evaluates environment markers against the machine doing the downloading
+      rather than the machine being targeted. Markers are therefore IGNORED here
+      - a requirement guarded by sys_platform == 'win32' is precisely the one
+      that has to be present.
+    #>
+    param([Parameter(Mandatory = $true)] [string] $BundleRoot)
+    $wheels = Join-Path $BundleRoot 'wheels'
+    $reqs   = Join-Path $BundleRoot 'app\requirements.txt'
+    if (-not (Test-Path $wheels) -or -not (Test-Path $reqs)) { return @() }
+
+    $have = @(Get-ChildItem $wheels -File -ErrorAction SilentlyContinue | ForEach-Object { $_.Name.ToLower() })
+    $problems = @()
+    $pins = @{}
+    foreach ($line in (Get-Content $reqs)) {
+        $trimmed = $line.Trim()
+        if (-not $trimmed -or $trimmed.StartsWith('#')) { continue }
+        if ($trimmed -match '^([A-Za-z0-9._-]+)==([^\s;\\]+)') {
+            # PEP 427 wheel filename form: runs of non-alphanumerics become one _.
+            $pins[([regex]::Replace($Matches[1], '[^A-Za-z0-9.]+', '_')).ToLower()] = $Matches[2]
+        }
+    }
+    foreach ($name in ($pins.Keys | Sort-Object)) {
+        $prefix = "$name-$($pins[$name])-"
+        if (-not ($have | Where-Object { $_.StartsWith($prefix) })) {
+            $problems += ("wheels/ has no wheel for {0}=={1}, which requirements.txt pins " +
+                          "(a marked-out dependency still installs on Windows)") -f $name, $pins[$name]
+        }
+    }
+    return $problems
+}
+
+function Read-BundleLock {
+    param([Parameter(Mandatory = $true)] [string] $Path)
+    if (-not (Test-Path $Path)) { return $null }
+    return (Get-Content $Path -Raw | ConvertFrom-Json)
+}

deploy/windows/installer/make-branding.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Generate Inno Setup wizard artwork from the app's own brand assets.
+
+Everything here is derived from frontend/public/*.svg so the installer and the
+running application are visibly the same product. Nothing is redrawn by hand.
+
+Inno stretches artwork to fit and does not resample well, so render at the exact
+sizes it asks for and supply the 125%/250% variants for high-DPI displays.
+
+  WizardImageFile       164x314, 192x386, 384x772
+  WizardSmallImageFile   55x55,  64x64,  138x138
+  SetupIconFile          .ico with 16/24/32/48/64/128/256
+
+Usage: python3 make-branding.py [output-dir]
+"""
+import io
+import sys
+from pathlib import Path
+
+import cairosvg
+from PIL import Image, ImageDraw, ImageFont
+
+ASSETS = Path.home() / "projects/shopdb-flask/frontend/public"
+OUT = Path(sys.argv[1] if len(sys.argv) > 1 else Path(__file__).parent)
+
+# Sampled from the application's own palette so the installer does not look like
+# a different product wearing the same badge.
+NAVY = (10, 34, 74)       # deep base
+BLUE = (16, 74, 150)      # GE blue
+CYAN = (0, 158, 224)      # accent
+WHITE = (255, 255, 255)
+MUTED = (176, 197, 226)
+
+
+def render_svg(name, width=None, height=None):
+    png = cairosvg.svg2png(url=str(ASSETS / name), output_width=width, output_height=height)
+    return Image.open(io.BytesIO(png)).convert("RGBA")
+
+
+def recolour(img, colour):
+    """Replace RGB while keeping the alpha mask. Source marks are dark-on-light;
+    on a dark panel they must be inverted or they disappear."""
+    solid = Image.new("RGBA", img.size, colour + (255,))
+    solid.putalpha(img.getchannel("A"))
+    return solid
+
+
+def font(size, bold=False):
+    for path in (
+        f"/usr/share/fonts/truetype/dejavu/DejaVuSans{'-Bold' if bold else ''}.ttf",
+        f"/usr/share/fonts/truetype/liberation/LiberationSans{'-Bold' if bold else '-Regular'}.ttf",
+    ):
+        if Path(path).exists():
+            return ImageFont.truetype(path, size)
+    return ImageFont.load_default()
+
+
+def vertical_gradient(size, top, bottom):
+    w, h = size
+    img = Image.new("RGB", size)
+    draw = ImageDraw.Draw(img)
+    for y in range(h):
+        t = y / max(1, h - 1)
+        # Ease the ramp so the middle does not look flat.
+        t = t * t * (3 - 2 * t)
+        draw.line(
+            [(0, y), (w, y)],
+            fill=tuple(int(top[i] + (bottom[i] - top[i]) * t) for i in range(3)),
+        )
+    return img
+
+
+def banner(w, h):
+    img = vertical_gradient((w, h), BLUE, NAVY)
+    draw = ImageDraw.Draw(img)
+    k = w / 164.0                      # scale factor from the 100% design
+
+    # Faint diagonal wash: stops the flat area under the text reading as empty.
+    glow = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+    gd = ImageDraw.Draw(glow)
+    gd.polygon([(0, int(h * 0.52)), (w, int(h * 0.30)), (w, h), (0, h)],
+               fill=(255, 255, 255, 10))
+    img = Image.alpha_composite(img.convert("RGBA"), glow).convert("RGB")
+    draw = ImageDraw.Draw(img)
+
+    margin = int(22 * k)
+
+    # GE Aerospace wordmark at the top, above the product name - the corporate
+    # mark leads, the product sits under it. (Previously the bare monogram was
+    # here and the wordmark was stranded at the bottom.)
+    mark_w = w - (margin * 2)
+    mark = render_svg("ge-aerospace-logo.svg", mark_w, int(mark_w * 32 / 138))
+    mark = recolour(mark, WHITE)
+    img.paste(mark, (margin, int(34 * k)), mark)
+
+    # Product name, directly beneath it.
+    y = int(34 * k) + mark.height + int(30 * k)
+    draw.text((margin, y), "ShopDB", font=font(int(26 * k), bold=True), fill=WHITE)
+    y += int(31 * k)
+
+    # Hairline rule, then the descriptor. Cheap way to look considered.
+    draw.rectangle([margin, y, margin + int(30 * k), y + max(1, int(2 * k))], fill=CYAN)
+    y += int(14 * k)
+    for line in ("Asset management", "for the shop floor"):
+        draw.text((margin, y), line, font=font(int(10.5 * k)), fill=MUTED)
+        y += int(15 * k)
+
+    # Accent bar flush to the bottom edge.
+    bar = max(2, int(4 * k))
+    draw.rectangle([0, h - bar, w, h], fill=CYAN)
+    return img
+
+
+def small(size):
+    """Header mark on every page after the welcome page. White plate so it sits
+    correctly on the wizard's own header, in light or dark mode."""
+    img = Image.new("RGB", (size, size), WHITE)
+    m = int(size * 0.80)
+    mono = recolour(render_svg("ge-monogram.svg", m, m), BLUE)
+    off = (size - m) // 2
+    img.paste(mono, (off, off), mono)
+    return img
+
+
+def icon(path):
+    """Installer icon. Rounded navy tile with the monogram, so it reads at 16px
+    instead of turning into mush."""
+    base = 256
+    img = Image.new("RGBA", (base, base), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    d.rounded_rectangle([0, 0, base - 1, base - 1], radius=int(base * 0.22), fill=BLUE + (255,))
+    d.rounded_rectangle([0, 0, base - 1, int(base * 0.5)], radius=int(base * 0.22),
+                        fill=(30, 96, 175, 255))
+    d.rounded_rectangle([0, int(base * 0.3), base - 1, base - 1], radius=int(base * 0.22),
+                        fill=BLUE + (255,))
+    m = int(base * 0.62)
+    mono = recolour(render_svg("ge-monogram.svg", m, m), WHITE)
+    img.paste(mono, ((base - m) // 2, (base - m) // 2), mono)
+    img.save(path, sizes=[(16, 16), (24, 24), (32, 32), (48, 48), (64, 64),
+                          (128, 128), (256, 256)])
+
+
+def main():
+    OUT.mkdir(parents=True, exist_ok=True)
+    made = []
+    for w, h, name in [(164, 314, "wizard-image.bmp"),
+                       (192, 386, "wizard-image@125.bmp"),
+                       (384, 772, "wizard-image@250.bmp")]:
+        banner(w, h).save(OUT / name, "BMP"); made.append((name, f"{w}x{h}"))
+    for s, name in [(55, "wizard-small.bmp"), (64, "wizard-small@125.bmp"),
+                    (138, "wizard-small@250.bmp")]:
+        small(s).save(OUT / name, "BMP"); made.append((name, f"{s}x{s}"))
+    icon(OUT / "shopdb.ico"); made.append(("shopdb.ico", "multi-size"))
+    for name, dims in made:
+        print(f"  {name:<26} {dims:<10} {(OUT / name).stat().st_size // 1024} KB")
+
+
+if __name__ == "__main__":
+    main()

deploy/windows/installer/refresh-bundle-lock.ps1

@@ -0,0 +1,110 @@
+<#
+.SYNOPSIS
+    Regenerate bundle-lock.json from the staged bundle, after showing what would
+    change.
+
+.DESCRIPTION
+    Run this on the machine that assembled the wheelhouse, once the bundle holds
+    the payload you intend to ship:
+
+      bundle\wheels\               the wheels, built with the matching Python
+      bundle\python\               the Python installer
+      bundle\httpplatformhandler\  the IIS module MSI
+      bundle\urlrewrite\           URL Rewrite MSI     (optional)
+      bundle\mysql\                MySQL MSI           (optional)
+
+    Then COMMIT the resulting bundle-lock.json. That commit is the review: it is
+    the only place a change to what runs as SYSTEM on a customer's server becomes
+    visible to a human. A lock regenerated and committed without reading the diff
+    provides nothing, so this refuses to overwrite an existing lock until you
+    have seen the change and passed -Yes.
+
+.EXAMPLE
+    .\refresh-bundle-lock.ps1                 # show the diff, write nothing
+    .\refresh-bundle-lock.ps1 -Yes            # write it
+
+.NOTES
+    Building the wheelhouse itself no longer requires Windows. From any machine:
+      pip download -r requirements.txt -d wheels --only-binary=:all: `
+          --platform win_amd64 --python-version 314 --implementation cp --abi cp314
+    Do it wherever you like; this script records what came out.
+#>
+
+[CmdletBinding()]
+param(
+    [string] $BundleRoot = (Join-Path $PSScriptRoot 'bundle'),
+    [string] $LockPath   = (Join-Path $PSScriptRoot 'bundle-lock.json'),
+    [string] $PythonTag  = 'cp314',
+    [string] $Platform   = 'win_amd64',
+    [switch] $Yes
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'bundle-lock.ps1')
+
+function Say { param($m, $c = 'Gray') Write-Host $m -ForegroundColor $c }
+
+if (-not (Test-Path $BundleRoot)) {
+    Say "bundle not found: $BundleRoot" 'Red'
+    Say 'Stage it first with build-installer.ps1 (or build-installer.sh), then add' 'Yellow'
+    Say 'the wheels and installers by hand.' 'Yellow'
+    exit 1
+}
+
+Say ''
+Say "  Hashing $BundleRoot" 'Cyan'
+$new = New-BundleLock -BundleRoot $BundleRoot -PythonTag $PythonTag -Platform $Platform
+
+foreach ($name in $new.payloads.Keys) {
+    Say ("    {0,-22} {1,4} files" -f $name, $new.payloads[$name].files.Count)
+}
+
+$old = Read-BundleLock $LockPath
+if (-not $old) {
+    Say ''
+    Say '  No existing lock - this will be the first one.' 'Yellow'
+} else {
+    # Diff by file, per payload, so the operator sees exactly which artifacts
+    # changed rather than "the lock is different".
+    Say ''
+    Say '  Changes against the committed lock:' 'Cyan'
+    $changes = 0
+    foreach ($name in $new.payloads.Keys) {
+        $oldFiles = @{}
+        if ($old.payloads.PSObject.Properties.Name -contains $name) {
+            foreach ($p in $old.payloads.$name.files.PSObject.Properties) { $oldFiles[$p.Name] = $p.Value.sha256 }
+        }
+        $newFiles = $new.payloads[$name].files
+        foreach ($rel in ($newFiles.Keys | Sort-Object)) {
+            if (-not $oldFiles.ContainsKey($rel))                 { Say "    + $name/$rel" 'Green';  $changes++ }
+            elseif ($oldFiles[$rel] -ne $newFiles[$rel].sha256)   { Say "    ~ $name/$rel  (content changed)" 'Yellow'; $changes++ }
+        }
+        foreach ($rel in ($oldFiles.Keys | Sort-Object)) {
+            if (-not $newFiles.ContainsKey($rel))                 { Say "    - $name/$rel" 'Red'; $changes++ }
+        }
+    }
+    foreach ($p in $old.payloads.PSObject.Properties.Name) {
+        if (-not $new.payloads.Contains($p)) { Say "    - $p/ (whole payload gone)" 'Red'; $changes++ }
+    }
+    if ($changes -eq 0) {
+        Say '    none - the bundle already matches the lock' 'Green'
+        exit 0
+    }
+    Say ''
+    Say ("  {0} change(s)." -f $changes) 'White'
+}
+
+if (-not $Yes) {
+    Say ''
+    Say '  Nothing written. Read the list above, then re-run with -Yes.' 'Yellow'
+    Say '  Commit the resulting bundle-lock.json - that commit IS the review.' 'Yellow'
+    exit 2
+}
+
+# ConvertTo-Json defaults to a depth of 2, which silently flattens the per-file
+# entries into "System.Collections.Hashtable" strings and produces a lock that
+# verifies against nothing.
+$new | ConvertTo-Json -Depth 8 | Set-Content -Path $LockPath -Encoding UTF8
+Say ''
+Say "  Written: $LockPath" 'Green'
+Say '  Commit it.' 'Green'

deploy/windows/installer/shopdb-preflight.ps1

@@ -0,0 +1,562 @@
+<#
+.SYNOPSIS
+    ShopDB-Flask installer - Stage 1: read-only preflight.
+
+.DESCRIPTION
+    Discovers everything the installer needs to know about this box and reports
+    it. Makes NO changes: no installs, no config edits, no service restarts.
+    Safe to run on a production server.
+
+    Written for stock Windows PowerShell 5.1 (Windows Server ships it). No
+    pwsh-only syntax, no external modules, no network access.
+
+.PARAMETER SitePort
+    The port the ShopDB site will listen on. Default 8090 (the runbook's example;
+    the classic ASP site keeps 8080).
+
+.PARAMETER AppRoot
+    Intended install directory. Default C:\shopdb-flask.
+
+.PARAMETER Json
+    Emit machine-readable JSON instead of the human report. Later installer
+    stages consume this.
+
+.EXAMPLE
+    powershell -ExecutionPolicy Bypass -File .\shopdb-preflight.ps1
+    powershell -ExecutionPolicy Bypass -File .\shopdb-preflight.ps1 -Json > preflight.json
+
+.NOTES
+    Exit 0 = no blocking problems. Exit 1 = at least one FAIL.
+#>
+
+[CmdletBinding()]
+param(
+    [int]    $SitePort = 8090,
+    [string] $AppRoot  = 'C:\shopdb-flask',
+    # Needed so the port check can tell OUR site apart from a stranger's.
+    [string] $SiteName = 'shopdb-flask',
+    [switch] $Json,
+    # Machine-readable output for a GUI caller: one record per line,
+    #   STATUS|AREA|CHECK|DETAIL|FIX
+    # The console rendering below aligns columns with padding spaces, which only
+    # works in a fixed-width font at console width. A GUI must do its own layout,
+    # so give it DATA and let it decide - do not make it parse a formatted table.
+    # (-Json exists too, but Inno's Pascal Script has no JSON parser.)
+    [switch] $Delimited
+)
+
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+# --- result collection -------------------------------------------------------
+# Every check appends one record. Status is PASS / WARN / FAIL / INFO.
+$script:Results = New-Object System.Collections.ArrayList
+$script:IisPresent = $false
+
+function Add-Result {
+    param(
+        [string] $Area,
+        [string] $Check,
+        [ValidateSet('PASS','WARN','FAIL','INFO','SKIP')] [string] $Status,
+        [string] $Detail,
+        [string] $Fix = ''
+    )
+    $null = $script:Results.Add([PSCustomObject]@{
+        Area   = $Area
+        Check  = $Check
+        Status = $Status
+        Detail = $Detail
+        Fix    = $Fix
+    })
+}
+
+# Wrap a check so one failure cannot abort the whole run. On an unfamiliar box
+# an unexpected exception is itself a finding, not a crash.
+function Invoke-Check {
+    param([string] $Area, [string] $Check, [scriptblock] $Body)
+    try { & $Body }
+    catch {
+        Add-Result $Area $Check 'WARN' "check could not run: $($_.Exception.Message)" `
+            'Report this output; the installer needs to handle this box shape.'
+    }
+}
+
+# =============================================================================
+# 1. Operator context
+# =============================================================================
+
+Invoke-Check 'System' 'Elevation' {
+    $id  = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $adm = (New-Object Security.Principal.WindowsPrincipal($id)).IsInRole(
+               [Security.Principal.WindowsBuiltInRole]::Administrator)
+    if ($adm) { Add-Result 'System' 'Elevation' 'PASS' 'running as Administrator' }
+    else {
+        Add-Result 'System' 'Elevation' 'FAIL' 'not elevated' `
+            'Re-run PowerShell as Administrator. IIS and service changes require it.'
+    }
+}
+
+Invoke-Check 'System' 'Windows version' {
+    $os   = Get-CimInstance Win32_OperatingSystem
+    $name = $os.Caption
+    $ver  = $os.Version
+    # ProductType: 1 = workstation, 2 = domain controller, 3 = server
+    $isServer = ($os.ProductType -ne 1)
+    $detail = "$name (build $ver), $(if ($isServer) {'Server'} else {'Client'})"
+
+    $supported = $false
+    if ($isServer -and [version]$ver -ge [version]'10.0.17763') { $supported = $true }  # 2019+
+    if (-not $isServer -and [version]$ver -ge [version]'10.0.19045') { $supported = $true } # Win10 22H2+
+
+    if ($supported) { Add-Result 'System' 'Windows version' 'PASS' $detail }
+    else {
+        Add-Result 'System' 'Windows version' 'FAIL' $detail `
+            'Supported: Windows Server 2019/2022+, or Windows 10 22H2 / 11 Pro+.'
+    }
+
+    # Client SKUs must be Pro/Enterprise/Education for IIS.
+    if (-not $isServer -and $name -match 'Home') {
+        Add-Result 'System' 'Windows edition' 'FAIL' 'Windows Home edition' `
+            'IIS is not available on Home editions. Pro or higher is required.'
+    }
+}
+
+Invoke-Check 'System' 'Architecture' {
+    if ([Environment]::Is64BitOperatingSystem) {
+        Add-Result 'System' 'Architecture' 'PASS' '64-bit'
+    } else {
+        Add-Result 'System' 'Architecture' 'FAIL' '32-bit' `
+            'The bundled Python and wheels are 64-bit (win_amd64) only.'
+    }
+}
+
+Invoke-Check 'System' 'PowerShell version' {
+    $v = $PSVersionTable.PSVersion
+    Add-Result 'System' 'PowerShell version' 'INFO' "$v"
+    if ($v.Major -lt 5) {
+        Add-Result 'System' 'PowerShell version' 'FAIL' "$v" `
+            'PowerShell 5.1 or later is required.'
+    }
+}
+
+# =============================================================================
+# 2. Disk and ports
+# =============================================================================
+
+Invoke-Check 'Disk' 'Free space' {
+    $drive = (Split-Path -Qualifier $AppRoot)
+    $d = Get-CimInstance Win32_LogicalDisk -Filter "DeviceID='$drive'"
+    if ($null -eq $d) {
+        Add-Result 'Disk' 'Free space' 'FAIL' "drive $drive not found" `
+            "Choose an -AppRoot on an existing volume."
+        return
+    }
+    $freeGB = [math]::Round($d.FreeSpace / 1GB, 1)
+    $detail = "$freeGB GB free on $drive"
+    if ($freeGB -ge 5) { Add-Result 'Disk' 'Free space' 'PASS' $detail }
+    else { Add-Result 'Disk' 'Free space' 'FAIL' $detail 'At least 5 GB is required.' }
+}
+
+Invoke-Check 'Disk' 'AppRoot' {
+    if (Test-Path $AppRoot) {
+        $existing = @(Get-ChildItem $AppRoot -Force -ErrorAction SilentlyContinue)
+        if ($existing.Count -gt 0) {
+            $hasEnv = Test-Path (Join-Path $AppRoot '.env')
+            if ($hasEnv) {
+                # An existing install is the NORMAL state for an upgrade. Reporting
+                # it as a warning makes a routine update look like a problem.
+                $ver = ''
+                $vf = Join-Path $AppRoot '.installed-version'
+                if (Test-Path $vf) { $ver = ' version ' + (Get-Content $vf -TotalCount 1).Trim() }
+                Add-Result 'Disk' 'AppRoot' 'INFO' `
+                    "existing ShopDB-Flask install found$ver - it will be upgraded in place, and your settings and database are kept"
+            } else {
+                Add-Result 'Disk' 'AppRoot' 'WARN' "$AppRoot exists and is not empty" `
+                    'Confirm this directory is safe to install into.'
+            }
+        } else { Add-Result 'Disk' 'AppRoot' 'PASS' "$AppRoot exists and is empty" }
+    } else { Add-Result 'Disk' 'AppRoot' 'PASS' "$AppRoot does not exist yet" }
+}
+
+function Test-PortFree {
+    param([int] $Port)
+    # Get-NetTCPConnection is the reliable listener check on Server 2012R2+.
+    try {
+        $listening = @(Get-NetTCPConnection -State Listen -LocalPort $Port -ErrorAction SilentlyContinue)
+        return ($listening.Count -eq 0)
+    } catch {
+        # Fall back to a bind attempt if the cmdlet is unavailable.
+        try {
+            $l = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Any, $Port)
+            $l.Start(); $l.Stop(); return $true
+        } catch { return $false }
+    }
+}
+
+Invoke-Check 'Network' 'Site port' {
+    if (Test-PortFree $SitePort) {
+        Add-Result 'Network' 'Site port' 'PASS' "TCP $SitePort is free"
+    } else {
+        $owner = ''
+        try {
+            $c = Get-NetTCPConnection -State Listen -LocalPort $SitePort -ErrorAction SilentlyContinue | Select-Object -First 1
+            if ($c) { $owner = " (pid $($c.OwningProcess): $((Get-Process -Id $c.OwningProcess -ErrorAction SilentlyContinue).ProcessName))" }
+        } catch { }
+        # Is the listener OUR OWN site? On a reinstall or upgrade the port is held
+        # by the very application being upgraded, and blocking on that makes the
+        # installer refuse to update anything it previously installed.
+        $ours = $false
+        try {
+            Import-Module WebAdministration -ErrorAction SilentlyContinue
+            $site = Get-Website -Name $SiteName -ErrorAction SilentlyContinue
+            if ($site) {
+                foreach ($b in $site.bindings.Collection) {
+                    # ${} is required: "$SitePort:" parses as a DRIVE-qualified variable.
+                    if ($b.bindingInformation -match ":${SitePort}:") { $ours = $true }
+                }
+            }
+        } catch { }
+
+        if ($ours) {
+            Add-Result 'Network' 'Site port' 'INFO' `
+                "TCP $SitePort is used by the existing $SiteName site - this will be upgraded in place"
+        } else {
+            # WARN, not FAIL. This check runs before the operator has reached the
+            # Address page, so it is testing the DEFAULT port, not necessarily
+            # the one they intend to use. Blocking here would refuse an install
+            # over a conflict the very next page lets them resolve.
+            Add-Result 'Network' 'Site port' 'WARN' "TCP $SitePort is in use$owner" `
+                "Pick a different port on the Address page later in this wizard, or stop whatever is holding it."
+        }
+    }
+}
+
+# =============================================================================
+# 3. IIS
+# =============================================================================
+
+Invoke-Check 'IIS' 'Installed' {
+    $svc = Get-Service -Name W3SVC -ErrorAction SilentlyContinue
+    $script:IisPresent = ($null -ne $svc)
+    if ($null -eq $svc) {
+        Add-Result 'IIS' 'Installed' 'FAIL' 'W3SVC service not found' `
+            'Install IIS. Server: Install-WindowsFeature Web-Server -IncludeManagementTools. Client: enable Internet Information Services in Windows Features.'
+        return
+    }
+    Add-Result 'IIS' 'Installed' 'PASS' "W3SVC present, status $($svc.Status)"
+    if ($svc.Status -ne 'Running') {
+        Add-Result 'IIS' 'Running' 'WARN' "W3SVC is $($svc.Status)" 'Start-Service W3SVC'
+    }
+}
+
+Invoke-Check 'IIS' 'WebAdministration module' {
+    $m = Get-Module -ListAvailable -Name WebAdministration
+    if ($m) { Add-Result 'IIS' 'WebAdministration module' 'PASS' 'available' }
+    else {
+        Add-Result 'IIS' 'WebAdministration module' 'FAIL' 'not available' `
+            'Install the IIS management tools (Web-Mgmt-Console / IIS Management Scripts and Tools).'
+    }
+}
+
+Invoke-Check 'IIS' 'HttpPlatformHandler' {
+    # The handler registers itself as a global module. Check the module list.
+    $appcmd = Join-Path $env:windir 'system32\inetsrv\appcmd.exe'
+    if (-not (Test-Path $appcmd)) {
+        Add-Result 'IIS' 'HttpPlatformHandler' 'SKIP' 'appcmd.exe not present (IIS not installed)' `
+            'Re-run this preflight after installing IIS.'
+        return
+    }
+    $modules = & $appcmd list module 2>$null
+    if ($modules -match 'httpPlatformHandler') {
+        Add-Result 'IIS' 'HttpPlatformHandler' 'PASS' 'installed'
+    } else {
+        # NOT a blocker: the MSI is in the bundle and stage 4 installs it. This
+        # was a FAIL, which - once the preflight page started blocking on any
+        # failure - stopped the wizard dead over something the installer was
+        # about to do by itself, with no way forward but to go and install it by
+        # hand. Nothing the installer SUPPLIES may be a blocker.
+        Add-Result 'IIS' 'HttpPlatformHandler' 'INFO' 'not installed yet' `
+            'The installer installs it from the bundle. No action needed.'
+    }
+}
+
+Invoke-Check 'IIS' 'Locked config sections' {
+    # The authoritative source is applicationHost.config. `appcmd list config
+    # /section:X` prints the section CONTENTS, not its lock state, so grepping
+    # that output silently reports every section as unlocked.
+    $cfg = Join-Path $env:windir 'system32\inetsrv\config\applicationHost.config'
+    if (-not (Test-Path $cfg)) {
+        Add-Result 'IIS' 'Locked config sections' 'SKIP' 'applicationHost.config not found'
+        return
+    }
+    foreach ($name in @('handlers','httpPlatform')) {
+        $line = Select-String -Path $cfg -Pattern ('<section name="' + $name + '"') |
+                Select-Object -First 1
+        if ($null -eq $line) {
+            # httpPlatform is registered by the HttpPlatformHandler MSI. Before
+            # that, `appcmd unlock config /section:system.webServer/httpPlatform`
+            # fails with "Unknown config section".
+            Add-Result 'IIS' "Section $name" 'SKIP' 'section not registered yet' `
+                'Install HttpPlatformHandler FIRST; only then can this section be unlocked.'
+        } elseif ($line.Line -match 'overrideModeDefault="Deny"') {
+            Add-Result 'IIS' "Section $name" 'WARN' 'locked (overrideModeDefault="Deny")' `
+                "Installer must run: appcmd unlock config /section:system.webServer/$name  (else IIS 500.19)"
+        } else {
+            Add-Result 'IIS' "Section $name" 'PASS' 'not locked'
+        }
+    }
+}
+
+Invoke-Check 'IIS' 'URL Rewrite module' {
+    $appcmd = Join-Path $env:windir 'system32\inetsrv\appcmd.exe'
+    if (-not (Test-Path $appcmd)) {
+        Add-Result 'IIS' 'URL Rewrite module' 'SKIP' 'IIS not installed; cannot check'
+        return
+    }
+    $modules = & $appcmd list module 2>$null
+    if ($modules -match 'RewriteModule') {
+        Add-Result 'IIS' 'URL Rewrite module' 'PASS' 'installed (the X-Forwarded-For rule can be enabled)'
+    } else {
+        # Not a FAIL: it is only needed for -ClientIpSource direct, and the
+        # installer carries the MSI and installs it itself. Worth reporting
+        # because without the rule IIS sends no X-Forwarded-For at all, so every
+        # client reads as 127.0.0.1 and the GE-Enforce IP allowlist, the
+        # visitor-location lookup and per-host login rate limiting go quiet.
+        Add-Result 'IIS' 'URL Rewrite module' 'INFO' 'not installed' `
+            'The installer installs it from the bundle when -ClientIpSource is direct. Behind a reverse proxy that already sets X-Forwarded-For, use -ClientIpSource proxy and leave it out.'
+    }
+}
+
+Invoke-Check 'IIS' 'Existing sites' {
+    if (-not $script:IisPresent) {
+        Add-Result 'IIS' 'Existing sites' 'SKIP' 'IIS not installed'
+        return
+    }
+    try {
+        Import-Module WebAdministration -ErrorAction Stop
+        $sites = @(Get-Website)
+        if ($sites.Count -eq 0) { Add-Result 'IIS' 'Existing sites' 'INFO' 'none' ; return }
+        $desc = ($sites | ForEach-Object {
+            $b = ($_.bindings.Collection | ForEach-Object { $_.bindingInformation }) -join ','
+            "$($_.Name) [$($_.State)] $b"
+        }) -join '; '
+        Add-Result 'IIS' 'Existing sites' 'INFO' $desc
+        # Adoption sites typically run the classic ASP shopdb here already.
+        if ($desc -match '8080') {
+            Add-Result 'IIS' 'Classic ASP site' 'INFO' 'a site is bound on 8080 (likely the classic ASP shopdb)' `
+                'Install ShopDB as a separate site on its own port; do not disturb this one.'
+        }
+    } catch {
+        Add-Result 'IIS' 'Existing sites' 'WARN' "could not enumerate: $($_.Exception.Message)" ''
+    }
+}
+
+# =============================================================================
+# 4. MySQL  (detect BEFORE offering bundled vs existing)
+# =============================================================================
+
+Invoke-Check 'MySQL' 'Service' {
+    $svcs = @(Get-Service -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '^MySQL' -or $_.DisplayName -match 'MySQL' })
+    if ($svcs.Count -eq 0) {
+        Add-Result 'MySQL' 'Service' 'INFO' 'no MySQL service found' `
+            'Bundled MySQL 8.4 LTS is the appropriate choice on this box.'
+        return
+    }
+    foreach ($s in $svcs) {
+        Add-Result 'MySQL' 'Service' 'WARN' "$($s.Name) ($($s.DisplayName)) is $($s.Status)" `
+            'MySQL already present. Default to the EXISTING-server option; installing bundled MySQL will collide on port 3306.'
+    }
+}
+
+Invoke-Check 'MySQL' 'Port 3306' {
+    if (Test-PortFree 3306) {
+        Add-Result 'MySQL' 'Port 3306' 'INFO' 'nothing listening on 3306'
+    } else {
+        Add-Result 'MySQL' 'Port 3306' 'WARN' 'something is listening on 3306' `
+            'Bundled MySQL cannot use the default port. Use the existing server, or pick another port.'
+    }
+}
+
+Invoke-Check 'MySQL' 'Backup client' {
+    # mysqldump is what takes the mandatory pre-upgrade backup. Without it every
+    # upgrade skips the backup - and skips it AFTER the application pool has been
+    # stopped and the tree replaced, so the site is down and there is nothing to
+    # restore from. A site whose database is on another server typically has no
+    # MySQL client installed here at all, which is exactly the case that needs it.
+    $names = @('mysqldump.exe')
+    $found = ''
+    foreach ($root in @((Join-Path $PSScriptRoot 'mysqlclient'),
+                        (Join-Path $AppRoot 'mysqlclient'),
+                        'C:\MySQL84', 'C:\Program Files\MySQL', 'C:\mysql56\bin',
+                        'C:\Program Files (x86)\MySQL')) {
+        if (-not (Test-Path $root)) { continue }
+        $hit = Get-ChildItem $root -Filter $names[0] -Recurse -ErrorAction SilentlyContinue |
+               Select-Object -First 1
+        if ($hit) { $found = $hit.FullName; break }
+    }
+    if ($found) {
+        Add-Result 'MySQL' 'Backup client' 'PASS' "mysqldump found ($found)"
+    } else {
+        Add-Result 'MySQL' 'Backup client' 'WARN' 'mysqldump not found on this server' `
+            'Needed for the automatic pre-upgrade backup and for "shopdb-admin.ps1 backup". A first install works without it; upgrades will not be protected. It is not on this server yet - the installer stages its own copy, so this normally resolves itself during installation.'
+    }
+}
+
+Invoke-Check 'MySQL' 'Version and config' {
+    # Find mysqld.exe via the service binary path; read the version and locate my.ini.
+    $svc = Get-CimInstance Win32_Service -ErrorAction SilentlyContinue |
+           Where-Object { $_.PathName -match 'mysqld' } | Select-Object -First 1
+    if ($null -eq $svc) { return }
+
+    $path = $svc.PathName
+    $exe = ''
+    if ($path -match '"([^"]+mysqld[^"]*)"') { $exe = $matches[1] }
+    elseif ($path -match '(\S+mysqld\S*)') { $exe = $matches[1] }
+
+    $ver = ''
+    if ($exe -and (Test-Path $exe)) {
+        try { $ver = (& $exe --version 2>$null | Out-String).Trim() } catch { }
+    }
+    if ($ver) { Add-Result 'MySQL' 'Version' 'INFO' $ver }
+
+    # my.ini path is passed as --defaults-file in the service command line.
+    $ini = ''
+    if ($path -match '--defaults-file="?([^"]+\.ini)"?') { $ini = $matches[1] }
+    if ($ini -and (Test-Path $ini)) {
+        Add-Result 'MySQL' 'Config file' 'INFO' $ini
+
+        # MySQL 5.6 needs three flags or `flask db upgrade` dies with error 1071.
+        $is56 = ($ver -match '\b5\.6\.')
+        if ($is56) {
+            $content = Get-Content $ini -Raw
+            $need = @('innodb_file_per_table','innodb_file_format','innodb_large_prefix')
+            $missing = @()
+            foreach ($k in $need) { if ($content -notmatch $k) { $missing += $k } }
+            if ($missing.Count -eq 0) {
+                # Present in the FILE is not the same as ACTIVE. MySQL must be
+                # restarted for them to take effect, and the app's own
+                # `flask db-utils preflight` queries the live server - trust that.
+                Add-Result 'MySQL' '5.6 index flags' 'WARN' 'all three present in my.ini' `
+                    'Present in the file only. They take effect after a MySQL RESTART, which interrupts the classic ASP app. Confirm with SHOW VARIABLES or flask db-utils preflight.'
+            } else {
+                # WARN, not FAIL. This inspects the LOCAL MySQL, which may not be the
+            # database the operator is about to install against - a bundled 8.4,
+            # or a remote server. Blocking the wizard here refused an install
+            # over a server that had nothing to do with it. Stage 3 runs
+            # 'flask db-utils preflight' against the database actually chosen,
+            # which is the check that can genuinely block.
+            Add-Result 'MySQL' '5.6 index flags' 'WARN' ("missing: " + ($missing -join ', ')) `
+                    "Add to [mysqld] in $ini and restart MySQL, or 'flask db upgrade' fails with error 1071. NOTE: restarting interrupts the classic ASP app."
+            }
+        }
+    }
+}
+
+# =============================================================================
+# 5. Python  (detect, but the installer uses its OWN bundled interpreter)
+# =============================================================================
+
+Invoke-Check 'Python' 'On PATH' {
+    $cmd = Get-Command python -ErrorAction SilentlyContinue
+    if ($null -eq $cmd) {
+        Add-Result 'Python' 'On PATH' 'INFO' 'no python on PATH' `
+            'Expected. The installer supplies its own interpreter.'
+        return
+    }
+    $v = ''
+    try { $v = (& $cmd.Source --version 2>&1 | Out-String).Trim() } catch { }
+    $detail = "$v at $($cmd.Source)"
+
+    # A per-user install under %LOCALAPPDATA% is unreadable by the IIS app-pool
+    # identity. That produces a 500 with an empty HttpPlatform log.
+    if ($cmd.Source -like "$env:LOCALAPPDATA*") {
+        Add-Result 'Python' 'On PATH' 'WARN' "$detail (PER-USER install)" `
+            'The IIS app-pool identity cannot read %LOCALAPPDATA%. The installer must install Python for ALL USERS and use absolute paths.'
+    } elseif ($cmd.Source -like '*WindowsApps*') {
+        Add-Result 'Python' 'On PATH' 'WARN' "$detail (Microsoft Store)" `
+            'Store Python misbehaves under service identities. The installer will not use it.'
+    } else {
+        Add-Result 'Python' 'On PATH' 'INFO' $detail `
+            'Not used by the installer, but a manual `flask` command later would resolve to this interpreter.'
+    }
+}
+
+Invoke-Check 'Python' 'Registered installs' {
+    $found = @()
+    foreach ($hive in @('HKLM:\SOFTWARE\Python\PythonCore','HKCU:\SOFTWARE\Python\PythonCore')) {
+        if (Test-Path $hive) {
+            foreach ($k in Get-ChildItem $hive -ErrorAction SilentlyContinue) {
+                $ip = Join-Path $k.PSPath 'InstallPath'
+                if (Test-Path $ip) {
+                    $loc = (Get-ItemProperty $ip -ErrorAction SilentlyContinue).'(default)'
+                    $scope = if ($hive -like 'HKLM*') { 'all-users' } else { 'per-user' }
+                    $found += "$($k.PSChildName) ($scope) $loc"
+                }
+            }
+        }
+    }
+    if ($found.Count -eq 0) { Add-Result 'Python' 'Registered installs' 'INFO' 'none' }
+    else { Add-Result 'Python' 'Registered installs' 'INFO' ($found -join '; ') }
+}
+
+# =============================================================================
+# Report
+# =============================================================================
+
+$fails = @($script:Results | Where-Object { $_.Status -eq 'FAIL' })
+$warns = @($script:Results | Where-Object { $_.Status -eq 'WARN' })
+$skips = @($script:Results | Where-Object { $_.Status -eq 'SKIP' })
+
+if ($Delimited) {
+    # Data only. No padding, no colour, no alignment - the caller lays it out.
+    # Pipes are stripped from field values so the record can be split naively.
+    foreach ($r in $script:Results) {
+        $fix = ''
+        if ($r.Fix) { $fix = $r.Fix }
+        $fields = @($r.Status, $r.Area, $r.Check, $r.Detail, $fix) | ForEach-Object {
+            ([string]$_) -replace '\|', '/' -replace '\s*\r?\n\s*', ' '
+        }
+        Write-Output ($fields -join '|')
+    }
+} elseif ($Json) {
+    [PSCustomObject]@{
+        Timestamp = (Get-Date).ToString('s')
+        Computer  = $env:COMPUTERNAME
+        SitePort  = $SitePort
+        AppRoot   = $AppRoot
+        Failures  = $fails.Count
+        Warnings  = $warns.Count
+        Skipped   = $skips.Count
+        Results   = $script:Results
+    } | ConvertTo-Json -Depth 5
+} else {
+    Write-Host ''
+    Write-Host 'ShopDB-Flask preflight' -ForegroundColor Cyan
+    Write-Host ("  host {0}   site port {1}   approot {2}" -f $env:COMPUTERNAME, $SitePort, $AppRoot)
+    Write-Host ''
+    $area = ''
+    foreach ($r in $script:Results) {
+        if ($r.Area -ne $area) { $area = $r.Area; Write-Host "[$area]" -ForegroundColor White }
+        $colour = 'Gray'
+        if ($r.Status -eq 'PASS') { $colour = 'Green' }
+        if ($r.Status -eq 'WARN') { $colour = 'Yellow' }
+        if ($r.Status -eq 'FAIL') { $colour = 'Red' }
+        if ($r.Status -eq 'SKIP') { $colour = 'DarkGray' }
+        Write-Host ("  {0,-5} {1,-28} {2}" -f $r.Status, $r.Check, $r.Detail) -ForegroundColor $colour
+        if ($r.Fix -and $r.Status -ne 'PASS' -and $r.Status -ne 'INFO' -and $r.Status -ne 'SKIP') {
+            Write-Host ("        -> {0}" -f $r.Fix) -ForegroundColor DarkGray
+        }
+    }
+    Write-Host ''
+    if ($fails.Count -eq 0) {
+        Write-Host "No blocking problems. $($warns.Count) warning(s), $($skips.Count) skipped." -ForegroundColor Green
+    } else {
+        Write-Host "$($fails.Count) blocking problem(s), $($warns.Count) warning(s), $($skips.Count) skipped." -ForegroundColor Red
+    }
+    if ($skips.Count -gt 0) {
+        Write-Host "  Skipped checks were NOT verified. Re-run once their prerequisite is installed." -ForegroundColor DarkGray
+    }
+    Write-Host ''
+}
+
+if ($fails.Count -gt 0) { exit 1 } else { exit 0 }

deploy/windows/installer/tests/test-install-state.ps1

@@ -0,0 +1,130 @@
+# Tests the installer's durable install record.
+#
+# The record answers one question: "is this a re-run of MY install?". Getting it
+# wrong is destructive in one direction - answering "first provisioning" for a
+# server holding real data lets prune-schema --force loose on it - and a dead
+# end in the other, which is what it was built to fix.
+#
+# Run directly:  pwsh -File test-install-state.ps1
+# pytest runs it through tests/test_installer_state.py wherever pwsh exists.
+
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+$Here      = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Installer = Join-Path (Split-Path -Parent $Here) 'shopdb-install.ps1'
+if (-not (Test-Path $Installer)) { throw "installer not found at $Installer" }
+
+$Sandbox = Join-Path ([System.IO.Path]::GetTempPath()) ('shopdb-state-' + [System.Guid]::NewGuid().ToString('N'))
+
+# Load ONLY the state block, so the rest of the installer does not run. Bounded
+# by the same markers the installer uses, and it fails loudly if either moves
+# rather than silently testing nothing.
+$lines = Get-Content $Installer
+$start = ($lines | Select-String -Pattern '^\$script:StateFile ' | Select-Object -First 1)
+$end   = ($lines | Select-String -Pattern '^function Invoke-Native' | Select-Object -First 1)
+if (-not $start -or -not $end) { throw 'could not locate the install-record block in shopdb-install.ps1' }
+$block = $lines[($start.LineNumber - 1)..($end.LineNumber - 2)] -join "`n"
+if ($block -notmatch 'function Test-FirstProvisioning') { throw 'extracted block does not contain the state functions' }
+
+# Stand-ins for the surrounding script.
+$script:Created = New-Object System.Collections.ArrayList
+function Write-Log { param($m, $l = 'INFO') }
+function Protect-File { param([string] $Path, [switch] $Directory) }
+function Test-SamePath {
+    param([string] $A, [string] $B)
+    if (-not $A) { return -not $B }
+    return ($A.TrimEnd('\', '/').ToLowerInvariant() -eq $B.TrimEnd('\', '/').ToLowerInvariant())
+}
+if (-not $env:ProgramData) { $env:ProgramData = [System.IO.Path]::GetTempPath() }
+
+Invoke-Expression $block
+
+$script:Failures = 0
+function Check {
+    param([string] $Name, $Expected, $Actual)
+    if ($Expected -eq $Actual) {
+        Write-Host ("  PASS  " + $Name)
+    } else {
+        Write-Host ("  FAIL  {0}: expected [{1}], got [{2}]" -f $Name, $Expected, $Actual)
+        $script:Failures++
+    }
+}
+
+function Reset-Case {
+    param([switch] $Stamped)
+    if (Test-Path $Sandbox) { Remove-Item $Sandbox -Recurse -Force }
+    New-Item -ItemType Directory -Path $Sandbox -Force | Out-Null
+    $script:AppRoot      = $Sandbox
+    $script:StateFile    = Join-Path $Sandbox 'install-state.json'
+    $script:InstallState = $null
+    if ($Stamped) { Set-Content (Join-Path $Sandbox '.installed-version') '0.7.0' }
+}
+
+Write-Host 'brand new server'
+Reset-Case
+Initialize-InstallState
+Check 'first provisioning' $true (Test-FirstProvisioning)
+Check 'record written' $true (Test-Path $script:StateFile)
+
+Write-Host 'retry of a failed first install'
+$script:InstallState = $null
+Initialize-InstallState
+Check 'still first provisioning' $true (Test-FirstProvisioning)
+
+Write-Host 'genuine upgrade after a completed install'
+Complete-InstallState
+$script:InstallState = $null
+Initialize-InstallState
+Check 'no longer first provisioning' $false (Test-FirstProvisioning)
+
+Write-Host 'install predating the record - must take the safe side'
+Reset-Case -Stamped
+Initialize-InstallState
+Check 'treated as established' $false (Test-FirstProvisioning)
+
+Write-Host 'record naming a different directory'
+Reset-Case
+Initialize-InstallState
+$other = Get-Content $script:StateFile -Raw | ConvertFrom-Json
+$other.approot = 'C:\somewhere-else'
+($other | ConvertTo-Json -Depth 6) | Set-Content $script:StateFile
+$script:InstallState = $null
+Check 'foreign record rejected' $null (Get-InstallState)
+
+Write-Host 'corrupt record'
+Reset-Case
+Set-Content $script:StateFile '{ this is not json'
+$script:InstallState = $null
+Check 'corrupt record rejected' $null (Get-InstallState)
+Reset-Case
+Set-Content $script:StateFile '{ this is not json'
+Initialize-InstallState
+Check 'recovers and rewrites' $true ($null -ne $script:InstallState)
+
+Write-Host 'created items survive a crash'
+Reset-Case
+Initialize-InstallState
+Track 'site' 'shopdb-flask'
+Track 'apppool' 'shopdbflask'
+Track 'site' 'shopdb-flask'
+$script:InstallState = $null
+Initialize-InstallState
+Check 'site remembered' 'shopdb-flask' ((Get-CreatedItems 'site') -join ',')
+Check 'apppool remembered' 'shopdbflask' ((Get-CreatedItems 'apppool') -join ',')
+# A zero-length array returned from a function unrolls to $null, and $null.Count
+# is fatal under StrictMode. This is the check that catches losing the comma.
+Check 'unknown kind is an empty array' 0 ((Get-CreatedItems 'firewall')).Count
+
+Write-Host 'no record at all'
+$script:InstallState = $null
+Check 'empty list, not null' 0 ((Get-CreatedItems 'site')).Count
+Check 'not first provisioning' $false (Test-FirstProvisioning)
+
+if (Test-Path $Sandbox) { Remove-Item $Sandbox -Recurse -Force }
+if ($script:Failures -gt 0) {
+    Write-Host ("{0} check(s) failed" -f $script:Failures)
+    exit 1
+}
+Write-Host 'all checks passed'
+exit 0

deploy/windows/installer/verify_bundle_lock.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Check a staged installer bundle against bundle-lock.json.
+
+Prints one line per problem and exits non-zero if there are any. Exits 0 only
+when the bundle's third-party payload is EXACTLY what the lock describes: no
+missing file, no unexpected extra file, no changed content.
+
+Why this exists alongside bundle-lock.ps1, which does the same job:
+
+  - bundle-lock.ps1 is canonical. It runs at INSTALL time on the target server,
+    where PowerShell is the only thing guaranteed to be present - Python is not
+    installed until stage 2, and verifying the payload after running part of it
+    would defeat the purpose.
+  - This file lets the Linux builder (build-installer.sh) do the same check
+    without adding pwsh as a build dependency.
+
+The two are kept honest by tests/test_bundle_lock.py, which runs BOTH against
+the same fixtures and fails if they disagree.
+
+Usage: verify_bundle_lock.py <bundle-root> <bundle-lock.json>
+"""
+import hashlib
+import json
+import os
+import re
+import sys
+
+# Must match $script:BundlePayloads in bundle-lock.ps1.
+PAYLOADS = [
+    ('wheels',              True,  'Python wheels for the offline install'),
+    ('python',              True,  'the Python installer'),
+    ('httpplatformhandler', True,  'the IIS module that launches waitress'),
+    ('urlrewrite',          False, 'IIS URL Rewrite, for the client-IP rule'),
+    ('mysqlclient',         False, 'mysql/mysqldump, for backups against a remote database'),
+    ('vcredist',            False, 'the Visual C++ runtime MySQL requires'),
+    ('mysql',               False, 'MySQL, for the bundled-database option'),
+]
+
+
+def digest(path):
+    sha = hashlib.sha256()
+    with open(path, 'rb') as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b''):
+            sha.update(chunk)
+    return sha.hexdigest()
+
+
+def payload_files(directory):
+    """Every file under the directory, keyed by forward-slashed relative path."""
+    found = {}
+    if not os.path.isdir(directory):
+        return found
+    for root, _dirs, files in os.walk(directory):
+        for name in files:
+            full = os.path.join(root, name)
+            rel = os.path.relpath(full, directory).replace(os.sep, '/')
+            found[rel] = {'sha256': digest(full), 'size': os.path.getsize(full)}
+    return found
+
+
+def normalize(name):
+    """PEP 427 wheel filename form: runs of non-alphanumerics become one _."""
+    return re.sub(r'[^A-Za-z0-9.]+', '_', name).lower()
+
+
+def requirement_pins(requirements_path):
+    """Every 'name==version' pinned in a lockfile, including marked-out ones.
+
+    Markers are deliberately IGNORED. A requirement guarded by
+    sys_platform == 'win32' is exactly the case that must be present, because the
+    target is Windows and the wheelhouse is usually assembled somewhere else.
+    """
+    pins = {}
+    with open(requirements_path) as fh:
+        for line in fh:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            match = re.match(r'^([A-Za-z0-9._-]+)==([^\s;\\]+)', line)
+            if match:
+                pins[normalize(match.group(1))] = match.group(2)
+    return pins
+
+
+def check_wheelhouse_covers_requirements(bundle_root):
+    """The lock records what IS in the wheelhouse, not what the app NEEDS.
+
+    Without this, an incomplete wheelhouse gets locked and blessed, and the
+    install fails on an air-gapped server. That is not hypothetical: assembling
+    the wheelhouse on Linux silently omits colorama, a win32-only dependency of
+    click, because pip evaluates environment markers against the machine doing
+    the downloading rather than the machine being targeted.
+    """
+    wheels = os.path.join(bundle_root, 'wheels')
+    requirements = os.path.join(bundle_root, 'app', 'requirements.txt')
+    if not os.path.isdir(wheels) or not os.path.exists(requirements):
+        return []
+    have = os.listdir(wheels)
+    problems = []
+    for name, version in sorted(requirement_pins(requirements).items()):
+        prefix = '%s-%s-' % (name, version)
+        if not any(f.lower().startswith(prefix) for f in have):
+            problems.append(
+                'wheels/ has no wheel for %s==%s, which requirements.txt pins '
+                '(a marked-out dependency still installs on Windows)' % (name, version))
+    return problems
+
+
+def verify(bundle_root, lock):
+    problems = []
+    locked = lock.get('payloads')
+    if not locked:
+        return ['bundle-lock.json has no "payloads" section']
+
+    for name, required, what in PAYLOADS:
+        directory = os.path.join(bundle_root, name)
+        present = os.path.isdir(directory)
+        if name not in locked:
+            if present:
+                problems.append(
+                    '%s/ is present but is not in bundle-lock.json - regenerate the lock' % name)
+            elif required:
+                problems.append(
+                    '%s/ is required but is in neither the bundle nor the lock' % name)
+            continue
+        if not present:
+            if required or locked[name].get('required'):
+                problems.append('%s/ is in the lock but missing from the bundle (%s)' % (name, what))
+            continue
+
+        expected = locked[name].get('files', {})
+        actual = payload_files(directory)
+        for rel, want in sorted(expected.items()):
+            got = actual.get(rel)
+            if got is None:
+                problems.append('%s/%s is in the lock but missing from the bundle' % (name, rel))
+            elif got['sha256'] != want['sha256']:
+                problems.append(
+                    '%s/%s does NOT match the lock (expected sha256 %s..., got %s...)'
+                    % (name, rel, want['sha256'][:12], got['sha256'][:12]))
+            elif int(got['size']) != int(want['size']):
+                # Impossible for a matching sha256, so the lock was hand-edited.
+                problems.append(
+                    '%s/%s size disagrees with the lock - the lock has been edited by hand'
+                    % (name, rel))
+        for rel in sorted(actual):
+            if rel not in expected:
+                problems.append(
+                    '%s/%s is in the bundle but NOT in the lock (unexpected extra file)'
+                    % (name, rel))
+    problems.extend(check_wheelhouse_covers_requirements(bundle_root))
+    return problems
+
+
+def main():
+    if len(sys.argv) != 3:
+        sys.exit('usage: verify_bundle_lock.py <bundle-root> <bundle-lock.json>')
+    bundle_root, lock_path = sys.argv[1], sys.argv[2]
+    if not os.path.exists(lock_path):
+        print('no bundle-lock.json at %s' % lock_path)
+        return 1
+    with open(lock_path) as fh:
+        lock = json.load(fh)
+    problems = verify(bundle_root, lock)
+    for problem in problems:
+        print(problem)
+    return 1 if problems else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

deploy/windows/shopdb-diagnose.py

@@ -0,0 +1,422 @@
+"""Collect everything needed to diagnose a ShopDB-Flask stage 5 failure.
+
+Stage 5 is the smoke test: the installer asks IIS for the site and expects 200.
+When it does not get one, the cause is always in one of four places, and this
+script reads all four in one pass so the answer arrives in a single round trip:
+
+  1. What IIS actually answers, and with which status code and error page.
+  2. Whether the config sections httpPlatformHandler needs are unlocked.
+  3. Whether the app-pool identity can read the app and run its venv.
+  4. Whether the app itself imports and starts.
+
+Run it ON THE SERVER, as Administrator:
+
+    C:\\Python314\\python.exe shopdb-diagnose.py
+
+It writes shopdb-diagnose-<timestamp>.txt next to itself and prints the path.
+Send that file back.
+
+SECRETS: the report never contains them. Values from .env (database password,
+SECRET_KEY, JWT_SECRET_KEY) are read first, then scrubbed out of every section
+of the report before it is written, including command output and tracebacks
+that might quote them.
+
+Standard library only, so it runs on the bundled runtime or any system Python.
+"""
+
+import os
+import re
+import socket
+import subprocess
+import sys
+import time
+from datetime import datetime
+
+APP_ROOT = os.environ.get('SHOPDB_APPROOT', r'C:\shopdb-flask')
+ALIAS = 'shopdb'
+TIMEOUT = 25
+
+# Filled from .env, then scrubbed from the whole report.
+SECRETS = []
+
+WINDIR = os.environ.get('WINDIR', r'C:\Windows')
+# Sysnative gives a 32-bit process the real 64-bit System32. Harmless on 64-bit.
+APPCMD_CANDIDATES = [
+    os.path.join(WINDIR, 'Sysnative', 'inetsrv', 'appcmd.exe'),
+    os.path.join(WINDIR, 'System32', 'inetsrv', 'appcmd.exe'),
+]
+
+
+def find_appcmd():
+    for path in APPCMD_CANDIDATES:
+        if os.path.isfile(path):
+            return path
+    return None
+
+
+class Report(object):
+    def __init__(self):
+        self.chunks = []
+
+    def head(self, title):
+        self.chunks.append('\n' + '=' * 72 + '\n' + title + '\n' + '=' * 72)
+
+    def line(self, text=''):
+        self.chunks.append(str(text))
+
+    def block(self, title, body):
+        self.chunks.append('\n--- %s ---' % title)
+        if body is None or str(body).strip() == '':
+            self.chunks.append('(no output)')
+        else:
+            self.chunks.append(str(body).rstrip())
+
+    def text(self):
+        return '\n'.join(self.chunks) + '\n'
+
+
+def run(cmd, timeout=60):
+    """Run a command, return combined output. Never raises."""
+    try:
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE,
+                                stderr=subprocess.STDOUT, shell=False)
+        out, _ = proc.communicate(timeout=timeout)
+        text = out.decode('utf-8', 'replace') if out else ''
+        return '[exit %s]\n%s' % (proc.returncode, text)
+    except subprocess.TimeoutExpired:
+        try:
+            proc.kill()
+        except Exception:
+            pass
+        return '[TIMED OUT after %ss]' % timeout
+    except Exception as exc:
+        return '[could not run: %s]' % exc
+
+
+def powershell(script, timeout=90):
+    exe = os.path.join(WINDIR, 'Sysnative', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+    if not os.path.isfile(exe):
+        exe = 'powershell.exe'
+    return run([exe, '-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
+               timeout=timeout)
+
+
+def load_secrets():
+    """Read .env so its secret VALUES can be scrubbed from the report."""
+    env_path = os.path.join(APP_ROOT, '.env')
+    found = {}
+    if not os.path.isfile(env_path):
+        return found, None
+    try:
+        with open(env_path, 'r', encoding='utf-8', errors='replace') as handle:
+            raw = handle.read()
+    except Exception as exc:
+        return found, '[could not read .env: %s]' % exc
+
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line or line.startswith('#') or '=' not in line:
+            continue
+        key, value = line.split('=', 1)
+        key, value = key.strip(), value.strip().strip('"').strip("'")
+        found[key] = value
+        if not value:
+            continue
+        upper = key.upper()
+        if 'SECRET' in upper or 'PASSWORD' in upper or 'TOKEN' in upper or 'KEY' in upper:
+            SECRETS.append(value)
+        if upper == 'DATABASE_URL':
+            # mysql+pymysql://user:PASSWORD@host/db -- the password only.
+            match = re.match(r'^[^:]+://([^:@/]+):([^@]+)@', value)
+            if match:
+                SECRETS.append(match.group(2))
+    return found, raw
+
+
+def scrub(text):
+    """Remove every known secret value from the report."""
+    for secret in SECRETS:
+        if secret and len(secret) >= 4:
+            text = text.replace(secret, '<REDACTED>')
+    # Catch a password inside any URL that did not come from .env.
+    text = re.sub(r'(://[^:@/\s]+:)[^@\s]+(@)', r'\1<REDACTED>\2', text)
+    return text
+
+
+def http_probe(url):
+    """Fetch a URL, returning status, headers and body even for an error page."""
+    import urllib.error
+    import urllib.request
+
+    started = time.time()
+    try:
+        request = urllib.request.Request(url, headers={'User-Agent': 'shopdb-diagnose'})
+        with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+            body = response.read(4000).decode('utf-8', 'replace')
+            return {'status': response.status, 'reason': response.reason,
+                    'headers': dict(response.headers), 'body': body,
+                    'seconds': time.time() - started}
+    except urllib.error.HTTPError as exc:
+        body = ''
+        try:
+            body = exc.read(4000).decode('utf-8', 'replace')
+        except Exception:
+            pass
+        return {'status': exc.code, 'reason': exc.reason,
+                'headers': dict(exc.headers or {}), 'body': body,
+                'seconds': time.time() - started}
+    except Exception as exc:
+        return {'status': None, 'reason': '%s: %s' % (type(exc).__name__, exc),
+                'headers': {}, 'body': '', 'seconds': time.time() - started}
+
+
+def summarise_iis_error(body):
+    """Pull the meaningful bits out of an IIS error page."""
+    if not body:
+        return None
+    import html
+
+    # style and script blocks first: their contents survive plain tag stripping
+    # and drag CSS into the summary.
+    flat = re.sub(r'(?is)<(script|style)[^>]*>.*?</\1>', ' ', body)
+    flat = re.sub(r'(?s)<!--.*?-->', ' ', flat)
+    flat = re.sub(r'(?s)<[^>]*>', ' ', flat)
+    # Any unterminated tag left by the 4000-byte body truncation.
+    flat = re.sub(r'(?s)<[^>]*$', ' ', flat)
+    flat = html.unescape(flat)
+    flat = re.sub(r'\s+', ' ', flat).strip()
+
+    hints = []
+    for pattern in (r'\b\d{3}\.\d+\b', r'0x[0-9a-fA-F]{8}',
+                    r'Error Code[^.]{0,80}', r'Config (?:Error|File)[^.]{0,120}',
+                    r'Requested URL[^.]{0,120}', r'Physical Path[^.]{0,120}'):
+        for match in re.findall(pattern, flat):
+            cleaned = re.sub(r'\s+', ' ', match).strip(' :-')
+            if cleaned and cleaned not in hints:
+                hints.append(cleaned)
+    return {'flat': flat[:1200], 'hints': hints}
+
+
+def main():
+    report = Report()
+    stamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+
+    env_values, env_raw = load_secrets()
+
+    report.line('ShopDB-Flask stage 5 diagnostic')
+    report.line('generated %s' % datetime.now().strftime('%Y-%m-%d %H:%M:%S'))
+    report.line('host %s' % socket.gethostname())
+    report.line('app root %s' % APP_ROOT)
+    report.line('python %s' % sys.version.replace('\n', ' '))
+    report.line('process is %d-bit' % (64 if sys.maxsize > 2 ** 32 else 32))
+
+    # ---------------------------------------------------------------- 1. HTTP
+    report.head('1. WHAT IIS ANSWERS')
+    report.line('This is the single most important section. The status code names')
+    report.line('the fault: 500.19 = config locked, 502.3/503 = the app did not')
+    report.line('start, 404 = application or handler mapping missing.')
+
+    hostname = socket.gethostname()
+    targets = [
+        'http://localhost/%s/' % ALIAS,
+        'http://127.0.0.1/%s/' % ALIAS,
+        'http://[::1]/%s/' % ALIAS,
+        'http://%s/%s/' % (hostname, ALIAS),
+        'http://localhost/',
+    ]
+    for url in targets:
+        result = http_probe(url)
+        report.line('\n%s' % url)
+        report.line('  status : %s %s' % (result['status'], result['reason']))
+        report.line('  time   : %.1fs' % result['seconds'])
+        server = result['headers'].get('Server')
+        if server:
+            report.line('  server : %s' % server)
+        summary = summarise_iis_error(result['body'])
+        if summary and summary['hints']:
+            report.line('  hints  : %s' % ' | '.join(summary['hints'][:8]))
+        if summary and summary['flat']:
+            report.line('  body   : %s' % summary['flat'][:600])
+
+    # localhost resolving to ::1 first has bitten this install before.
+    report.block('name resolution for localhost', run(
+        ['nslookup', 'localhost'], timeout=20))
+
+    # ------------------------------------------------------------- 2. IIS state
+    report.head('2. IIS STATE')
+    appcmd = find_appcmd()
+    if not appcmd:
+        report.line('appcmd.exe NOT FOUND - is the IIS role installed?')
+    else:
+        report.line('appcmd: %s' % appcmd)
+        report.block('sites', run([appcmd, 'list', 'sites']))
+        report.block('applications', run([appcmd, 'list', 'apps']))
+        report.block('app pools', run([appcmd, 'list', 'apppools']))
+        report.block('worker processes (empty means nothing is running)',
+                     run([appcmd, 'list', 'wp']))
+        report.block('modules: httpPlatformHandler present?',
+                     run([appcmd, 'list', 'modules']))
+        # overrideMode tells us whether the unlock actually took effect.
+        #
+        # allowedServerVariables is in this list because it caused a 500.52 that
+        # the first two sections could not explain: it is Deny by default, so an
+        # <allowedServerVariables> block in the app's web.config is rejected
+        # before httpPlatformHandler runs. Checking only the sections we unlock
+        # would have missed the one we do not.
+        for section in ('system.webServer/handlers',
+                        'system.webServer/httpPlatform',
+                        'system.webServer/rewrite/allowedServerVariables',
+                        'system.webServer/rewrite/rules'):
+            report.block('lock state of %s' % section,
+                         run([appcmd, 'list', 'config', '/section:%s' % section,
+                              '/text:*']))
+
+    report.block('W3SVC / WAS services', powershell(
+        "Get-Service W3SVC,WAS | Format-Table Name,Status,StartType -AutoSize | Out-String"))
+    report.block('listeners on port 80', powershell(
+        "Get-NetTCPConnection -LocalPort 80 -State Listen -EA SilentlyContinue | "
+        "Format-Table LocalAddress,LocalPort,OwningProcess -AutoSize | Out-String"))
+    report.block('app pool detail', powershell(
+        "Import-Module WebAdministration -EA SilentlyContinue; "
+        "Get-Item IIS:\\AppPools\\shopdbflask -EA SilentlyContinue | "
+        "Select-Object name,state,managedRuntimeVersion,enable32BitAppOnWin64,"
+        "@{n='identity';e={$_.processModel.identityType}} | Format-List | Out-String"))
+
+    # --------------------------------------------------------- 3. app + config
+    report.head('3. APPLICATION AND CONFIG')
+
+    web_config = os.path.join(APP_ROOT, 'web.config')
+    if os.path.isfile(web_config):
+        try:
+            with open(web_config, 'r', encoding='utf-8', errors='replace') as handle:
+                report.block('web.config', handle.read())
+        except Exception as exc:
+            report.block('web.config', '[could not read: %s]' % exc)
+    else:
+        report.block('web.config', 'MISSING at %s' % web_config)
+
+    if env_raw is None:
+        report.block('.env', 'MISSING at %s' % os.path.join(APP_ROOT, '.env'))
+    else:
+        # Keys and non-secret values only. Secret values are scrubbed anyway.
+        lines = []
+        for key in sorted(env_values):
+            upper = key.upper()
+            secretish = ('SECRET' in upper or 'PASSWORD' in upper
+                         or 'TOKEN' in upper or 'KEY' in upper
+                         or upper == 'DATABASE_URL')
+            if secretish:
+                lines.append('%s = <set, %d chars>' % (key, len(env_values[key])))
+            else:
+                lines.append('%s = %s' % (key, env_values[key]))
+        report.block('.env (secret values withheld)', '\n'.join(lines))
+
+    venv_python = os.path.join(APP_ROOT, 'venv', 'Scripts', 'python.exe')
+    report.line('\nvenv python exists: %s' % os.path.isfile(venv_python))
+    if os.path.isfile(venv_python):
+        # The exact failure stage 3 used to hit. Proves the app imports.
+        report.block('venv: import shopdb', run(
+            [venv_python, '-c',
+             'import shopdb; print("import OK"); '
+             'app = shopdb.create_app(); print("create_app OK")'], timeout=120))
+        report.block('venv: waitress present', run(
+            [venv_python, '-c', 'import waitress; print(waitress.__version__)'],
+            timeout=60))
+
+    # What httpPlatformHandler is told to launch, and whether it exists.
+    if os.path.isfile(web_config):
+        try:
+            with open(web_config, 'r', encoding='utf-8', errors='replace') as handle:
+                raw = handle.read()
+            match = re.search(r'processPath\s*=\s*"([^"]+)"', raw)
+            args = re.search(r'arguments\s*=\s*"([^"]*)"', raw)
+            if match:
+                path = os.path.expandvars(match.group(1))
+                report.line('\nhttpPlatform processPath : %s' % match.group(1))
+                report.line('  resolved               : %s' % path)
+                report.line('  exists                 : %s' % os.path.isfile(path))
+            if args:
+                report.line('httpPlatform arguments   : %s' % args.group(1))
+        except Exception as exc:
+            report.line('[could not parse web.config: %s]' % exc)
+
+    # ------------------------------------------------------------- 4. app logs
+    report.head('4. APPLICATION LOGS')
+    log_dir = os.path.join(APP_ROOT, 'logs')
+    if not os.path.isdir(log_dir):
+        report.line('MISSING: %s' % log_dir)
+    else:
+        entries = []
+        for name in sorted(os.listdir(log_dir)):
+            full = os.path.join(log_dir, name)
+            try:
+                entries.append((os.path.getmtime(full), full, name,
+                                os.path.getsize(full)))
+            except OSError:
+                pass
+        if not entries:
+            report.line('%s is EMPTY.' % log_dir)
+            report.line('No stdout log at all means httpPlatformHandler never')
+            report.line('launched python - look at the pool identity and ACLs.')
+        for _, full, name, size in sorted(entries, reverse=True)[:5]:
+            if size == 0:
+                report.block('%s (0 bytes)' % name,
+                             'EMPTY - python was launched but wrote nothing.')
+                continue
+            try:
+                with open(full, 'r', encoding='utf-8', errors='replace') as handle:
+                    tail = handle.readlines()[-60:]
+                report.block('%s (%d bytes, last 60 lines)' % (name, size),
+                             ''.join(tail))
+            except Exception as exc:
+                report.block(name, '[could not read: %s]' % exc)
+
+    # ---------------------------------------------------------------- 5. ACLs
+    report.head('5. PERMISSIONS')
+    report.line('The pool runs as "IIS AppPool\\shopdbflask". It needs RX on the')
+    report.line('tree, Modify on logs and instance, and Read on .env.')
+    for target in (APP_ROOT, log_dir, os.path.join(APP_ROOT, '.env'),
+                   os.path.join(APP_ROOT, 'venv', 'Scripts')):
+        if os.path.exists(target):
+            report.block('icacls %s' % target, run(['icacls', target], timeout=40))
+
+    # ------------------------------------------------------------ 6. event log
+    report.head('6. EVENT LOG')
+    report.block('recent application errors', powershell(
+        "Get-WinEvent -FilterHashtable @{LogName='Application';"
+        "StartTime=(Get-Date).AddHours(-6)} -EA SilentlyContinue | "
+        "Where-Object { $_.ProviderName -match 'HttpPlatform|IIS|W3SVC|WAS|\\.NET' "
+        "-or $_.LevelDisplayName -eq 'Error' } | Select-Object -First 25 "
+        "TimeCreated,ProviderName,LevelDisplayName,Message | Format-List | Out-String",
+        timeout=180))
+    report.block('system log: WAS / W3SVC', powershell(
+        "Get-WinEvent -FilterHashtable @{LogName='System';"
+        "StartTime=(Get-Date).AddHours(-6)} -EA SilentlyContinue | "
+        "Where-Object { $_.ProviderName -match 'WAS|W3SVC|HTTP' } | "
+        "Select-Object -First 20 TimeCreated,ProviderName,LevelDisplayName,Message | "
+        "Format-List | Out-String", timeout=180))
+
+    # ------------------------------------------------------------------ write
+    body = scrub(report.text())
+    out_path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                            'shopdb-diagnose-%s.txt' % stamp)
+    try:
+        with open(out_path, 'w', encoding='utf-8') as handle:
+            handle.write(body)
+    except Exception:
+        out_path = os.path.join(os.environ.get('TEMP', r'C:\Windows\Temp'),
+                                'shopdb-diagnose-%s.txt' % stamp)
+        with open(out_path, 'w', encoding='utf-8') as handle:
+            handle.write(body)
+
+    print('')
+    print('Report written to:')
+    print('  %s' % out_path)
+    print('')
+    print('%d secret value(s) were scrubbed from it.' % len(SECRETS))
+    print('Send that file back.')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

deploy/windows/web.config

@@ -11,7 +11,7 @@
     - HttpPlatformHandler IIS module installed
       (https://www.iis.net/downloads/microsoft/httpplatformhandler)
     - URL Rewrite module installed (only for the optional X-Forwarded-For rule)
-    - Python 3.12 + a venv at APP_ROOT\venv with requirements.txt + waitress
+    - Python 3.14 + a venv at APP_ROOT\venv with requirements.txt + waitress
     - Secrets live in APP_ROOT\.env (wsgi.py load_dotenv() reads it). Keep them
       OUT of this file. Lock .env ACLs to the app pool identity + admins.
 
@@ -28,7 +28,7 @@
 
     <httpPlatform
         processPath="C:\shopdb-flask\venv\Scripts\waitress-serve.exe"
-        arguments="--port=%HTTP_PLATFORM_PORT% --host=127.0.0.1 --threads=8 wsgi:app"
+        arguments="--port=%HTTP_PLATFORM_PORT% --host=127.0.0.1 --threads=8 --trusted-proxy=127.0.0.1 --trusted-proxy-headers=x-forwarded-for --trusted-proxy-count=1 wsgi:app"
         stdoutLogEnabled="true"
         stdoutLogFile="C:\shopdb-flask\logs\httpplatform"
         startupTimeLimit="120"
@@ -38,24 +38,57 @@
              config (SQL echo, debug, wrong DB URL). Real secrets go in .env. -->
         <environmentVariable name="FLASK_ENV" value="production" />
         <environmentVariable name="PYTHONPATH" value="C:\shopdb-flask" />
+        <!-- Subpath method only: when this web.config sits in an IIS
+             Application (e.g. /ops) under an existing site instead of its own
+             site, tell the app its mount path. Must match the alias the
+             Application was created with AND the VITE_BASE_PATH the frontend
+             was built with ('/ops/'). Omit for the own-site method.
+        <environmentVariable name="MOUNT_PATH" value="/ops" />
+        -->
       </environmentVariables>
     </httpPlatform>
 
     <!--
-      OPTIONAL: forward the real client IP so audit logs and the kiosk
-      visitor-location feature (IP -> business unit) see the caller, not the
-      loopback that HttpPlatformHandler connects from.
+      Forward the real client IP, so the audit log, the kiosk visitor-location
+      feature (IP -> business unit), the GE-Enforce IP allowlist and per-host
+      login rate limiting all see the caller rather than the loopback address
+      HttpPlatformHandler connects from.
 
-      This block is COMMENTED OUT by default because it needs the URL Rewrite
-      module; with it uncommented but URL Rewrite not installed, IIS returns
-      HTTP 500.19 ("configuration section not well-formed / cannot be read").
-      Install URL Rewrite (https://www.iis.net/downloads/microsoft/url-rewrite)
-      and then uncomment the <rewrite> block below to enable it.
+      IIS does not set X-Forwarded-For on its own. Without the rule below there
+      is no such header at all, and every client looks like 127.0.0.1 - so the
+      allowlist and the visitor-location lookup silently stop working.
 
+      ONLY CORRECT WHEN IIS IS DIRECTLY EXPOSED. It overwrites the header with
+      REMOTE_ADDR, which is what stops a client spoofing its own X-Forwarded-For.
+      Behind a reverse proxy (ARR, a load balancer) REMOTE_ADDR is the PROXY, so
+      this rule would destroy the real client IP - there, leave it disabled and
+      let the proxy set the header.
+
+      It ships DISABLED because it needs the URL Rewrite module; enabled without
+      it, IIS returns HTTP 500.19 ("configuration section not well-formed").
+
+      There is deliberately NO <allowedServerVariables> block below. Setting a
+      server variable requires that variable to be allowed, but the section
+      system.webServer/rewrite/allowedServerVariables ships with
+      overrideModeDefault="Deny", so declaring it in an application's own
+      web.config is refused outright: IIS answered 500.52 with error 0x80070021,
+      "this configuration section cannot be used at this path", BEFORE it ever
+      reached httpPlatformHandler - so python was never launched and the stdout
+      log stayed empty, which looks like an application fault and is not one.
+
+      The installer instead allows the single variable at server level, which
+      grants exactly HTTP_X_FORWARDED_FOR rather than unlocking the section and
+      letting every site on the machine declare arbitrary server variables.
+
+      The installer handles both: -ClientIpSource direct installs URL Rewrite
+      from the bundle, allows the variable, and enables this; -ClientIpSource
+      proxy leaves it alone. By hand: install URL Rewrite, run
+        appcmd set config /section:system.webServer/rewrite/allowedServerVariables ^
+          /+"[name='HTTP_X_FORWARDED_FOR']" /commit:apphost
+      then delete the two marker lines below.
+    -->
+    <!-- SHOPDB-CLIENTIP-BEGIN
     <rewrite>
-      <allowedServerVariables>
-        <add name="HTTP_X_FORWARDED_FOR" />
-      </allowedServerVariables>
       <rules>
         <rule name="Set X-Forwarded-For" stopProcessing="false">
           <match url=".*" />
@@ -66,7 +99,53 @@
         </rule>
       </rules>
     </rewrite>
-    -->
+    SHOPDB-CLIENTIP-END -->
+
+    <security>
+      <requestFiltering>
+        <!-- IIS request filtering caps a request body at 30,000,000 bytes by
+             default and answers 413 before waitress sees it. The agent package
+             upload accepts 128 MB (MAX_CONTENT_LENGTH is 256 MB), and the tray
+             binary alone is ~69 MB, so the IIS cap has to be raised to match or
+             every agent upload fails on Windows while working under Docker. -->
+        <requestLimits maxAllowedContentLength="268435456" />
+      </requestFiltering>
+    </security>
 
   </system.webServer>
+
+  <!--
+    Installer downloads: serve /installers/* as IIS static files instead of
+    forwarding them to Flask. The handler above is path="*", so without this a
+    request for /installers/Foo.exe goes to waitress, which has no such route
+    (SPA fallback), and large binaries would stream through a Python thread.
+
+    This <location> clears the httpPlatformHandler for that one subpath and puts
+    the static file handler back, so IIS serves the bytes directly (kernel-mode,
+    range/resume, no Python thread held).
+
+    Requires a physical folder at APP_ROOT\installers (the site's physical path
+    is APP_ROOT). Drop the installer binaries there, e.g. robocopy them from the
+    classic wwwroot\installers. The stored installpath 'installers/Foo.exe' then
+    resolves to <mount>/installers/Foo.exe (e.g. /shopdb/installers/Foo.exe).
+
+    .exe/.msi are given an explicit MIME map; if the parent site has a Request
+    Filtering rule that denies executable extensions, also allow them there.
+  -->
+  <location path="installers">
+    <system.webServer>
+      <handlers>
+        <clear />
+        <add name="StaticFile" path="*" verb="*"
+             modules="StaticFileModule" resourceType="File"
+             requireAccess="Read" />
+      </handlers>
+      <staticContent>
+        <remove fileExtension=".exe" />
+        <mimeMap fileExtension=".exe" mimeType="application/octet-stream" />
+        <remove fileExtension=".msi" />
+        <mimeMap fileExtension=".msi" mimeType="application/octet-stream" />
+      </staticContent>
+    </system.webServer>
+  </location>
 </configuration>

docker-compose.airgap.yml

@@ -0,0 +1,109 @@
+# shopdb-flask AIR-GAPPED single-site stack.
+#
+# For a site with NO internet. Nothing is built or pulled here: the images are
+# built on a connected box (scripts/build-offline-bundle.ps1), shipped as a
+# tarball, and `docker load`ed at the site. This file only RUNS pre-loaded
+# images. See docs/DEPLOY-AIRGAP.md for the full runbook.
+#
+# Differences from docker-compose.yml (the connected/build template):
+#   - api uses `image:` (a loaded image), never `build: .` (build needs the net).
+#   - NO ./plugins bind mount. The image already carries every plugin baked in;
+#     binding a host ./plugins (which does not exist at an image-only site) would
+#     mask the baked plugins with an empty dir and load ZERO plugins.
+#   - a one-shot `migrate` service runs db upgrade + plugin upgrade-all + seed
+#     BEFORE api starts, so `up -d` alone brings up a working site (no manual
+#     `docker compose exec ... flask db upgrade` to forget).
+#
+# Usage at the site:
+#   docker load < shopdb-stack-<version>.tar.gz
+#   cp .env.example .env    # then edit: secrets, CORS_ORIGINS, IMAGE_TAG
+#   docker compose -f docker-compose.airgap.yml up -d
+#   docker compose -f docker-compose.airgap.yml exec api flask seed admin <user> <email> <password>
+
+# Shared application environment, reused by the migrate one-shot and the api
+# service so the two never drift. A YAML anchor, not a container.
+x-app-env: &app-env
+  FLASK_APP: wsgi.py
+  FLASK_ENV: production
+  DATABASE_URL: mysql+pymysql://shopdb:${MYSQL_PASSWORD}@db:3306/shopdb_flask?charset=utf8mb4
+  SECRET_KEY: ${SECRET_KEY:?SECRET_KEY must be set}
+  JWT_SECRET_KEY: ${JWT_SECRET_KEY:?JWT_SECRET_KEY must be set}
+  CORS_ORIGINS: ${CORS_ORIGINS:?CORS_ORIGINS must be set}
+  LOG_LEVEL: ${LOG_LEVEL:-INFO}
+  ZABBIX_URL: ${ZABBIX_URL:-}
+  ZABBIX_TOKEN: ${ZABBIX_TOKEN:-}
+  # Channel label for a distributable installer. Empty on the stable (main)
+  # bundle, 'DEV' on the edge (dev-be) bundle, which lights up the sidebar
+  # badge. Sourced from .env, which build-channel-installer.ps1 pre-fills.
+  SHOPDB_ENV_LABEL: ${SHOPDB_ENV_LABEL:-}
+
+services:
+  db:
+    image: mysql:8.4
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?MYSQL_ROOT_PASSWORD must be set}
+      MYSQL_DATABASE: shopdb_flask
+      MYSQL_USER: shopdb
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?MYSQL_PASSWORD must be set}
+    volumes:
+      - db_data:/var/lib/mysql
+    ports:
+      - "127.0.0.1:${MYSQL_PORT:-3306}:3306"
+    healthcheck:
+      # 127.0.0.1, not localhost: localhost means the unix socket, and the
+      # entrypoint's init pass answers on the socket while running the server
+      # with --skip-networking. A socket ping therefore reports healthy DURING
+      # init, and the api/migrate services start against a server that is about
+      # to restart. Over TCP the probe stays red until the real server listens.
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # One-shot schema + seed. Runs to completion and exits; api waits for it.
+  # Every step is idempotent, so it is safe to run on every `up`.
+  migrate:
+    image: shopdb-flask:${IMAGE_TAG:-0.7.0}
+    restart: "no"
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      <<: *app-env
+    command:
+      - sh
+      - -c
+      - >
+        flask db upgrade &&
+        flask plugin upgrade-all &&
+        flask seed permissions &&
+        flask seed settings &&
+        flask seed reference-data
+    # plugin upgrade-all rewrites plugins.json, so migrate needs the same
+    # instance volume api uses. Without it the enabled-plugin list is written
+    # into a container that exits immediately afterwards.
+    volumes:
+      - instance_data:/app/instance
+
+  api:
+    image: shopdb-flask:${IMAGE_TAG:-0.7.0}
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
+    environment:
+      <<: *app-env
+    ports:
+      - "${API_PORT:-5001}:5001"
+    # See docker-compose.yml for what lives here. Same reasoning: /app/instance
+    # is written state and does not survive a container recreate on its own.
+    volumes:
+      - instance_data:/app/instance
+
+volumes:
+  db_data:
+  instance_data:

docker-compose.backup.yml

@@ -0,0 +1,175 @@
+# shopdb-flask BACKUP overlay - opt-in, per-site.
+#
+# WHY a separate overlay: backups are not part of the base stack every site must
+# run. A facility turns them on by adding this file to its compose invocation:
+#
+#   docker compose -f docker-compose.yml -f docker-compose.backup.yml \
+#     --profile backup up -d
+#
+# That brings up THREE cooperating pieces:
+#   - backup-store   : a resident, isolated restic REST server (the third
+#                      container). Holds every snapshot in its own volume and is
+#                      reachable ONLY over the compose network - never published
+#                      to the host - so the app can touch backups solely through
+#                      the backup/restore utility, not with a shell or db creds.
+#   - backup-watcher : a resident poller that actuates the "Back up now" sentinel
+#                      the api drops, running the one-shot against backup-store.
+#                      This is what makes the in-app button produce a real backup
+#                      given the api container cannot run docker.
+#   - backup         : the same one-shot as a manual `run --rm backup` for sites
+#                      that prefer a host scheduler (cron / Task Scheduler).
+#
+# WHAT each run captures, as one recoverable set:
+#   - db.sql.gz    : mysqldump --single-transaction of the whole DB (users,
+#                    auth, ledger, every plugin table). InnoDB-consistent,
+#                    non-blocking.
+#   - instance/    : restic snapshot of /app/instance (deduped, encrypted),
+#                    the files MySQL rows point at.
+#   - manifest.json: core+plugin Alembic revisions and image tag at capture
+#                    time - the stamp that makes a restore a CHECKED operation.
+#
+# Retention (restic-native): --keep-daily 5 --keep-weekly 4 --keep-monthly 6,
+# satisfying "any day in the last 5" plus a cheap long-horizon tail.
+#
+# DESTINATION defaults to the third container via RESTIC_REPOSITORY:
+#   third container : rest:http://backup-store:8000/   (default, ships with app)
+#   AWS S3          : s3:s3.amazonaws.com/shopdb-<site>-backups
+#   Azure Blob      : azure:shopdbbackups:<site>
+#   SMB share       : mount the share on the host, point at a local path
+# Credentials come from the site's env/secret store, never committed - same
+# pattern as the collector key.
+
+# The THIRD container: an isolated backup store the app can only reach through
+# the backup/restore utility, never with a shell or the db credentials. It runs
+# restic's REST server over the compose network; the only thing that speaks to
+# it is the backup watcher/one-shot via RESTIC_REPOSITORY=rest:http://... . Its
+# data lives in its own named volume (backupstore_data), so it is container
+# agnostic - later a pull/migration utility can point at this same REST endpoint
+# from anywhere without touching the app or the database.
+services:
+  backup-store:
+    image: restic/rest-server:0.13.0
+    profiles: ["backup"]
+    restart: unless-stopped
+    environment:
+      # Private (no public /create) so repos are provisioned by the backup
+      # client's `restic init`, and append-only OFF here because the same
+      # utility both writes and prunes; isolation comes from this being the
+      # only service on the network with access, not from client trust.
+      DISABLE_AUTHENTICATION: "true"
+      OPTIONS: "--no-auth"
+    volumes:
+      - backupstore_data:/data
+    # Deliberately NOT published to the host: reachable only over the compose
+    # network by service name, so nothing outside the stack can touch backups.
+    expose:
+      - "8000"
+    healthcheck:
+      test: ["CMD", "sh", "-c", "wget -q -O - http://127.0.0.1:8000/ >/dev/null 2>&1 || true"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  # Resident watcher: actuates the "Back up now" sentinel the api drops. This is
+  # the piece that makes the UI button run a real backup, since the api itself
+  # cannot run docker. It shares the base image with the one-shot and calls the
+  # same backup.sh.
+  backup-watcher:
+    image: shopdb-backup:local
+    build:
+      context: .
+      dockerfile: scripts/backup/Dockerfile.backup
+    profiles: ["backup"]
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      backup-store:
+        condition: service_started
+    environment:
+      # DB access - same credentials the api uses, reaching db over the compose
+      # network by service name.
+      MYSQL_HOST: db
+      MYSQL_DATABASE: shopdb_flask
+      MYSQL_USER: shopdb
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?MYSQL_PASSWORD must be set}
+      # Destination is the third container by default: restic's REST backend on
+      # the isolated backup-store. A site can still override RESTIC_REPOSITORY
+      # in .env to send offsite instead, but out of the box backups land in the
+      # dedicated container.
+      RESTIC_REPOSITORY: ${RESTIC_REPOSITORY:-rest:http://backup-store:8000/}
+      RESTIC_PASSWORD: ${RESTIC_PASSWORD:?RESTIC_PASSWORD must be set}
+      # Optional cloud creds, passed through when set (empty otherwise).
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-}
+      AZURE_ACCOUNT_NAME: ${AZURE_ACCOUNT_NAME:-}
+      AZURE_ACCOUNT_KEY: ${AZURE_ACCOUNT_KEY:-}
+      # Site tag stamped into every snapshot + manifest.
+      SHOPDB_SITE: ${SHOPDB_SITE:-shopdb}
+      SHOPDB_IMAGE_TAG: ${SHOPDB_IMAGE:-source}
+      SHOPDB_BACKUPS_ROOT: /backups
+      BACKUP_POLL_SECONDS: ${BACKUP_POLL_SECONDS:-10}
+    volumes:
+      # The watcher services both backup (read) and restore (write) requests, so
+      # the instance tree is mounted read-write here. Restore has to lay the
+      # files half of a set back down next to the DB rows that reference it; the
+      # backup half still only ever reads. The manual one-shot below stays :ro.
+      - instance_data:/app/instance
+      # Alembic chain, read-only, so the manifest can stamp the schema revision
+      # the running code is at.
+      - ./migrations:/app/migrations:ro
+      - ./plugins:/app/plugins:ro
+      # Shared backups volume: holds the fast local db.sql.gz + manifest and the
+      # .backup-requested sentinel the api drops. The api mounts this same volume
+      # (see docker-compose.yml) so the UI can enumerate sets and request runs.
+      - backup_data:/backups
+      - ./scripts/backup:/opt/backup:ro
+    entrypoint: ["/opt/backup/watch.sh"]
+
+  # Manual one-shot, unchanged usage: `docker compose ... run --rm backup`.
+  # Kept for host-scheduler / cron sites that prefer a scheduled pass over the
+  # in-app button. Shares everything with the watcher but runs once and exits.
+  backup:
+    image: shopdb-backup:local
+    build:
+      context: .
+      dockerfile: scripts/backup/Dockerfile.backup
+    profiles: ["backup"]
+    restart: "no"
+    depends_on:
+      db:
+        condition: service_healthy
+      backup-store:
+        condition: service_started
+    environment:
+      MYSQL_HOST: db
+      MYSQL_DATABASE: shopdb_flask
+      MYSQL_USER: shopdb
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?MYSQL_PASSWORD must be set}
+      RESTIC_REPOSITORY: ${RESTIC_REPOSITORY:-rest:http://backup-store:8000/}
+      RESTIC_PASSWORD: ${RESTIC_PASSWORD:?RESTIC_PASSWORD must be set}
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-}
+      AZURE_ACCOUNT_NAME: ${AZURE_ACCOUNT_NAME:-}
+      AZURE_ACCOUNT_KEY: ${AZURE_ACCOUNT_KEY:-}
+      SHOPDB_SITE: ${SHOPDB_SITE:-shopdb}
+      SHOPDB_IMAGE_TAG: ${SHOPDB_IMAGE:-source}
+      SHOPDB_BACKUPS_ROOT: /backups
+    volumes:
+      - instance_data:/app/instance:ro
+      - ./migrations:/app/migrations:ro
+      - ./plugins:/app/plugins:ro
+      - backup_data:/backups
+      - ./scripts/backup:/opt/backup:ro
+    entrypoint: ["/opt/backup/backup.sh"]
+
+  # Give the api read/write on the shared backups volume so the UI can list sets
+  # and drop the "Back up now" sentinel the watcher actuates. This extends the
+  # api service defined in docker-compose.yml (merged by compose).
+  api:
+    volumes:
+      - backup_data:/backups
+
+volumes:
+  backup_data:
+  backupstore_data:

docker-compose.channel.yml

@@ -0,0 +1,27 @@
+# Channel overlay for side-by-side stable / bleeding-edge stacks.
+#
+# The base docker-compose.yml is channel-agnostic. This overlay adds only the
+# pieces that differ between a stable (main) and an edge (dev-be) stack so the
+# two can run at once on one dev workstation without colliding:
+#
+#   - SHOPDB_ENV_LABEL is passed into the api container. When non-empty the
+#     public settings endpoint surfaces it as env_label and the sidebar renders
+#     a red DEV badge. Stable leaves it unset, so nothing renders.
+#   - Ports fall back to the SAME defaults as the base file, so running this
+#     overlay alone changes nothing; the bootstrap script overrides API_PORT /
+#     MYSQL_PORT for the edge stack so both channels bind distinct host ports.
+#
+# The stacks are isolated by compose project name (-p shopdb-stable /
+# -p shopdb-edge), which namespaces containers, networks, and the named
+# volumes, so each channel keeps its own database and instance state.
+#
+# Usage (driven by scripts/dev-bootstrap.ps1, shown here for reference):
+#   docker compose -p shopdb-edge \
+#     -f docker-compose.yml -f docker-compose.channel.yml up -d
+
+services:
+  api:
+    environment:
+      # Empty on stable. The edge stack sets SHOPDB_ENV_LABEL=DEV in its .env
+      # (written by the bootstrap script) to light up the badge.
+      SHOPDB_ENV_LABEL: ${SHOPDB_ENV_LABEL:-}

docker-compose.pull.yml

@@ -0,0 +1,95 @@
+# shopdb-flask PULL stack for dev workstations (stable / edge channels).
+#
+# WHY this exists: pilots behind an inspecting proxy cannot reliably BUILD the
+# image from source (npm's many small fetches get reset mid-install). Instead
+# CI (.github/workflows/publish-images.yml) builds the image on clean runners
+# and publishes it to GHCR; this file just PULLS and RUNS it. One resumable
+# image pull survives the proxy where hundreds of npm requests do not.
+#
+# Nothing is built here (no `build:`), mirroring docker-compose.airgap.yml:
+#   - api/migrate use `image:` (pulled from GHCR), never `build: .`.
+#   - NO ./plugins bind mount; the image carries every plugin baked in.
+#   - a one-shot `migrate` runs db upgrade + plugin upgrade-all + seed before
+#     api starts, so `up -d` alone brings up a working site.
+#
+# Driven by scripts/dev-bootstrap.ps1, which sets SHOPDB_IMAGE (the channel
+# image ref), SHOPDB_ENV_LABEL, API_PORT and MYSQL_PORT per channel and picks a
+# compose project name (-p shopdb-stable / -p shopdb-edge) so the two channels
+# run side by side without colliding.
+
+x-app-env: &app-env
+  FLASK_APP: wsgi.py
+  FLASK_ENV: production
+  DATABASE_URL: mysql+pymysql://shopdb:${MYSQL_PASSWORD}@db:3306/shopdb_flask?charset=utf8mb4
+  SECRET_KEY: ${SECRET_KEY:?SECRET_KEY must be set}
+  JWT_SECRET_KEY: ${JWT_SECRET_KEY:?JWT_SECRET_KEY must be set}
+  CORS_ORIGINS: ${CORS_ORIGINS:?CORS_ORIGINS must be set}
+  LOG_LEVEL: ${LOG_LEVEL:-INFO}
+  # Empty on stable; 'DEV' on edge, which lights the sidebar badge.
+  SHOPDB_ENV_LABEL: ${SHOPDB_ENV_LABEL:-}
+
+services:
+  db:
+    image: mysql:8.4
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?MYSQL_ROOT_PASSWORD must be set}
+      MYSQL_DATABASE: shopdb_flask
+      MYSQL_USER: shopdb
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?MYSQL_PASSWORD must be set}
+    volumes:
+      - db_data:/var/lib/mysql
+    ports:
+      - "127.0.0.1:${MYSQL_PORT:-3306}:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # One-shot schema + seed. Runs to completion and exits; api waits for it.
+  # Every step is idempotent, so it is safe to run on every `up`.
+  migrate:
+    image: ${SHOPDB_IMAGE:?SHOPDB_IMAGE must be set to the channel image ref}
+    pull_policy: always
+    restart: "no"
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      <<: *app-env
+    command:
+      - sh
+      - -c
+      - >
+        flask db upgrade &&
+        flask plugin upgrade-all &&
+        flask seed permissions &&
+        flask seed settings &&
+        flask seed reference-data
+    volumes:
+      - instance_data:/app/instance
+
+  api:
+    image: ${SHOPDB_IMAGE:?SHOPDB_IMAGE must be set to the channel image ref}
+    pull_policy: always
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
+    environment:
+      <<: *app-env
+    ports:
+      # Loopback only, same as the DB below. This stack generates its own
+      # dev secrets and may hold a real imported dataset; it has no business
+      # listening on every interface of a laptop on a shop-floor network.
+      - "127.0.0.1:${API_PORT:-5001}:5001"
+    volumes:
+      - instance_data:/app/instance
+
+volumes:
+  db_data:
+  instance_data: