builderhooks: add dsynth tracker hooks

README.md

@@ -15,6 +15,9 @@ From the repository root, use:
 The wrapper bootstraps `scripts/generator/.venv` automatically on first run and
 dispatches to the installed `dportsv3` console entrypoint.
 
+For a disposable DragonFly chroot development shell, see
+`scripts/tools/dports-dev-env` and `docs/dev-chroot-environment.md`.
+
 ## Organization
 
 - **docs/**  

docs/dev-chroot-environment.md

@@ -0,0 +1,82 @@
+# Dev Chroot Environment
+
+`scripts/tools/dports-dev-env` creates a throwaway DragonFly chroot for port
+development while reusing cached inputs.
+
+Current scope:
+
+- backend: `chroot` only
+- rootfs source: latest `DragonFly-x86_64-*.world.tar.gz` from Avalon releases
+- DeltaPorts checkout: mounted live from the host
+- FreeBSD ports source: persistent mirror plus branch worktree
+
+## Requirements
+
+- run as `root`
+- host commands: `curl`, `tar`, `git`, `chroot`, `mount_null`, `mount_procfs`
+- network access to Avalon and the FreeBSD ports git remote
+
+## Create One Environment
+
+```bash
+sudo scripts/tools/dports-dev-env create --target @2026Q2 --origin editors/vim --shell
+```
+
+This will:
+
+1. discover the latest DragonFly `*world*` asset on Avalon,
+2. cache the downloaded archive,
+3. extract it once into the shared base cache,
+4. create a throwaway env root from that cache,
+5. mount the host DeltaPorts checkout into `/work/DeltaPorts`,
+6. create or refresh a cached FreeBSD ports worktree for the target branch,
+7. mount that worktree into `/work/freebsd-ports`,
+8. attempt to bootstrap a few development tools inside the chroot,
+9. run `compose` with `--oracle-profile off`,
+10. drop you into a shell if `--shell` was requested.
+
+## Enter Later
+
+```bash
+sudo scripts/tools/dports-dev-env shell 2026Q2-editors_vim
+```
+
+## Destroy
+
+```bash
+sudo scripts/tools/dports-dev-env destroy 2026Q2-editors_vim
+```
+
+## List
+
+```bash
+scripts/tools/dports-dev-env list
+```
+
+## Default Layout
+
+By default the helper stores state under `~/.cache/dports-dev/`:
+
+- `base-downloads/`: downloaded Avalon archives
+- `base-extracted/`: extracted reusable clean rootfs trees
+- `repos/freebsd-ports.git/`: persistent git mirror
+- `worktrees/freebsd-ports/<branch>/`: cached worktrees
+- `envs/<name>/root/`: throwaway chroot root
+
+## In-Chroot Helpers
+
+The shell defines:
+
+- `regen`: rerun compose for the environment target
+- `reapply`: rerun `dsl apply` for the selected origin
+- `showenv`: print `DPORTS_*` environment variables
+
+## Notes
+
+- `compose` failures do not delete the environment; the root is kept for manual
+  inspection.
+- Tool bootstrapping is best-effort beyond the required package list. The exact
+  package name providing `genpatch` may need adjustment for your host package
+  repositories.
+- The helper is intentionally structured around a `BACKEND` field in state so a
+  future jail backend can reuse the same UX.

scripts/builderhooks/README.tracker-hooks.md

@@ -0,0 +1,41 @@
+# dsynth tracker hooks
+
+These hooks connect dsynth build events to the `dportsv3 tracker` server.
+
+Files:
+
+- `tracker_common.sh`: shared helper logic
+- `dportsv3-tracker.conf.example`: config template
+- `hook_run_start`, `hook_run_end`: tracker run lifecycle
+- `hook_pkg_start` / `hook_pkg_started`: enqueue + mark building
+- `hook_pkg_success`, `hook_pkg_failure`, `hook_pkg_ignored`,
+  `hook_pkg_skipped`: final result recording
+
+Install pattern:
+
+```bash
+install -d /etc/dsynth
+install -m 755 scripts/builderhooks/hook_* /etc/dsynth/
+install -m 755 scripts/builderhooks/tracker_common.sh /etc/dsynth/
+install -m 644 scripts/builderhooks/dportsv3-tracker.conf.example \
+  /etc/dsynth/dportsv3-tracker.conf
+```
+
+Then edit `/etc/dsynth/dportsv3-tracker.conf` for:
+
+- `DPORTSV3_BIN`
+- `DPORTSV3_TRACKER_URL`
+- `DPORTSV3_TRACKER_TARGET`
+- `DPORTSV3_TRACKER_BUILD_TYPE`
+
+Notes:
+
+- hooks log failures but exit successfully so dsynth builds continue if the
+  tracker is unavailable
+- `hook_pkg_start` and `hook_pkg_started` are both provided to cover local
+  dsynth variants
+- per-port start hooks enqueue the port before calling `mark-building`, which
+  matches tracker DB expectations
+- if `start-build` fails (for example because an active run already exists for
+  the same target/build type), tracking is disabled for the rest of that dsynth
+  run instead of reusing a stale run id from a previous build

scripts/builderhooks/dportsv3-tracker.conf.example

@@ -0,0 +1,22 @@
+# dsynth tracker hook configuration
+
+# Absolute path to the repo-root wrapper or another installed dportsv3 binary.
+DPORTSV3_BIN=/absolute/path/to/DeltaPorts/dportsv3
+
+# Tracker server base URL.
+DPORTSV3_TRACKER_URL=http://127.0.0.1:8080
+
+# Build target associated with this dsynth profile.
+DPORTSV3_TRACKER_TARGET=@2026Q1
+
+# Tracker build type for this dsynth run.
+DPORTSV3_TRACKER_BUILD_TYPE=test
+
+# Directory used to store per-profile active run state.
+DPORTSV3_TRACKER_STATE_DIR=/var/db/dsynth-tracker
+
+# Hook-local log file. Hook failures are logged here and do not fail dsynth.
+DPORTSV3_TRACKER_HOOK_LOG=/var/log/dsynth-tracker-hooks.log
+
+# Optional external log URL prefix. If set, result hooks append `/ORIGIN`.
+# DPORTSV3_TRACKER_LOG_URL_BASE=https://logs.example/dsynth

scripts/builderhooks/hook_pkg_failure

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_record_result

scripts/builderhooks/hook_pkg_ignored

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_record_result

scripts/builderhooks/hook_pkg_skipped

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_record_result

scripts/builderhooks/hook_pkg_start

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_mark_building

scripts/builderhooks/hook_pkg_started

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_mark_building

scripts/builderhooks/hook_pkg_success

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_record_result

scripts/builderhooks/hook_run_end

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_run_end

scripts/builderhooks/hook_run_start

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+. "$(dirname "$0")/tracker_common.sh"
+tracker_run_start