release v1.5.1

Also collapses a duplicated changelog section. A second "## [Unreleased]"
heading has existed at the foot of the file since 2026-08-07, above the
roadmap list -- and because it matched first, my own v1.5.0 and T-69 commits
wrote their entries into both copies. The roadmap is now "## Planned", which is
what it always was, so the two cannot collide again.

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,70 @@
+{
+  "env": {
+    "PQL_VAULT": "/mnt/media/Projects/scheduler"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(pql)",
+      "Bash(pql *)",
+      "Bash(/home/jpmschweitzer/.local/bin/pql:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git branch:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(pytest:*)",
+      "Bash(docker logs scheduler:*)",
+      "Bash(curl -s http://localhost:8090/*)"
+    ],
+    "deny": [
+      "Bash(/mnt/media/Projects/cladmin/ops/bin/toj)",
+      "Bash(/mnt/media/Projects/cladmin/ops/bin/toj:*)",
+      "Bash(chmod -R 777 *)",
+      "Bash(chmod 777 *)",
+      "Bash(dd if=*)",
+      "Bash(find * -delete*)",
+      "Bash(find * -exec*)",
+      "Bash(git * add --all*)",
+      "Bash(git * add -A*)",
+      "Bash(git * add .)",
+      "Bash(git * branch -D *)",
+      "Bash(git * checkout -- *)",
+      "Bash(git * clean -fd*)",
+      "Bash(git * clean -fdx*)",
+      "Bash(git * commit --no-verify*)",
+      "Bash(git * merge --no-ff*)",
+      "Bash(git * push --force*)",
+      "Bash(git * push -f*)",
+      "Bash(git * reset --hard*)",
+      "Bash(git * restore .*)",
+      "Bash(git add --all*)",
+      "Bash(git add -A*)",
+      "Bash(git add .)",
+      "Bash(git branch -D *)",
+      "Bash(git checkout -- *)",
+      "Bash(git clean -fd*)",
+      "Bash(git clean -fdx*)",
+      "Bash(git commit --no-verify*)",
+      "Bash(git merge --no-ff*)",
+      "Bash(git push --force*)",
+      "Bash(git push -f*)",
+      "Bash(git reset --hard*)",
+      "Bash(git restore .*)",
+      "Bash(mkfs*)",
+      "Bash(psql * -c DELETE FROM scheduled_tasks*)",
+      "Bash(psql * -c DROP*)",
+      "Bash(psql * DROP DATABASE*)",
+      "Bash(psql * TRUNCATE*)",
+      "Bash(redis-cli * FLUSHALL*)",
+      "Bash(redis-cli * FLUSHDB*)",
+      "Bash(rm -rf $HOME*)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~*)",
+      "Bash(su *)",
+      "Bash(sudo *)",
+      "Bash(toj)",
+      "Bash(toj:*)"
+    ]
+  }
+}

.gitattributes

@@ -0,0 +1 @@
+.pql/changelog/*.sql merge=union

.githooks/pre-push

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Trigger only. The checks live in the Makefile, where they can be read, run by
+# hand (`make pre-push`), and changed under review.
+#
+# This file is identical in every repo in this workspace, deliberately: the call
+# surface is the same everywhere even though what each gate runs is not, so
+# nobody has to read a repo to find out how to check it (D-27).
+#
+# Enable per clone with:  git config core.hooksPath .githooks
+# Never bypass with --no-verify. Suppress a specific finding deliberately
+# instead, with a reason — see `make pre-push`.
+set -euo pipefail
+exec make -C "$(git rev-parse --show-toplevel)" pre-push

.gitignore

@@ -87,3 +87,16 @@ cython_debug/
 # Project-specific
 logs/
 task-data/
+
+# Claude Code user-specific settings
+.claude/settings.local.json
+.pql/*
+!.pql/changelog/
+
+# pql shims planted by `pql init` into the dir core.hooksPath points at.
+# Per-clone: each embeds the absolute path of the pql binary that planted it.
+# Only .githooks/pre-push is shared.
+.githooks/pre-commit
+.githooks/post-merge
+.githooks/post-checkout
+.githooks/post-rewrite

.pql/changelog/0000-format.sql

@@ -0,0 +1,11 @@
+-- Changelog format marker, written by pql. Comments only: this file
+-- is never executed — Import descends into the per-table directories
+-- and does not read the changelog root.
+--
+-- A changelog carrying no marker is format 1, the shape that existed
+-- before formats were versioned. An older format is migrated forward
+-- by `pql plan upgrade` (and automatically from the post-merge hook);
+-- a newer one is refused rather than replayed under rules this binary
+-- does not know. See D-28 and docs/versions.md.
+-- pql:changelog_format: 2.0.0
+-- pql:written_by: 2.2.0

.pql/changelog/ticket_deps/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_history/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_idmap/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_labels/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/tickets/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

AGENTS.md

@@ -1,72 +0,0 @@
-
-# AGENTS.md
-
-> **Start every session by reading this file.**
-> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
-
-## 1. Agent Operational Protocols
-
-### 🧠 Work Patterns (Plan-Act-Reflect)
-* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
-* **Act:** Execute the changes in small, atomic steps.
-* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
-
-### 🛡️ Git Discipline
-* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
-* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
-    * `feat: add user login endpoint`
-    * `fix: resolve database connection timeout`
-    * `refactor: split monolith dependency file`
-* **Atomic Commits:** Keep commits small. One logical change = one commit.
-
-### 📝 Changelog Maintenance
-* **Update `CHANGELOG.md`** with every user-facing change.
-* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
-
-### 🚀 Release Flow
-When changes are ready for deployment:
-
-1. **Ask user if deploy cycle is desired **
-
-2. **Update version** in `pyproject.toml`:
-   - Bug fixes: bump patch version (1.8.3 → 1.8.4)
-   - New features: bump minor version (1.8.4 → 1.9.0)
-
-3. **Update CHANGELOG.md**:
-   - Move items from `[Unreleased]` to new version section
-   - Add release date: `## [1.8.4] - 2025-12-16`
-
-4. **Commit and tag**:
-   ```bash
-   git add -A
-   git commit -m "fix: description of changes"
-   git tag v1.8.4
-   git push origin main --tags
-   ```
-
-5. **CI/CD triggers automatically**:
-   - Gitea CI builds Docker image on new tag
-   - Watchtower pulls and deploys to production
-   - Verify deployment: `curl http://192.168.86.149:8000/health`
-
----
-
-## 2. FastAPI Architecture & Best Practices
-*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*
-
-### 📂 Project Structure (Directory-based, NOT File-type based)
-Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.
-
-**Correct Structure:**
-```text
-src/
-├── auth/
-│   ├── router.py      # Endpoints
-│   ├── schemas.py     # Pydantic models
-│   ├── service.py     # Business logic (CRUD, etc.)
-│   ├── dependencies.py# Module-specific dependencies
-│   └── config.py      # Module-specific settings
-├── posts/
-│   ├── router.py
-│   └── ...
-└── main.py            # App entry point

CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-08-11
+
+### Fixed
+- Backups no longer freeze the API. The config backup ran its ~21 minutes of tarring on the
+  event loop, so the whole service was unreachable 03:05-03:25 nightly; it now runs in a
+  worker thread. Health reports moved off the loop too.
+- The health report's permission diagnostic prints the database's own message instead of
+  asserting a cause. It claimed the user lacked INSERT on `check_history` when that grant was
+  present and the missing one was USAGE on the sequence behind its serial id.
+
+### Notes
+- Requires `GRANT USAGE ON SEQUENCE check_history_id_seq TO scheduler_user`, applied
+  2026-08-11. The table grant alone does not permit the insert.
+
+## [1.5.0] - 2026-08-11
+
+### Added
+- Backup executors report their own outcome to the homelab health record — one row in
+  `check_history` per run, success or failure. Replaces a monitor that inferred backup health
+  from file age and could not tell a failed backup from one that had not run yet.
+
+### Notes
+- Requires `GRANT INSERT ON check_history TO scheduler_user` in the `sysmon` database, applied
+  2026-08-11. Without it the report is refused, logged, and skipped; the backup itself is unaffected.
+
 ## [1.4.0] - 2026-08-08
 
 ### Added
@@ -269,9 +294,7 @@ config_backup_executor.py        50% 📈
 TOTAL                            80% 🎯
 ```
 
-## [Unreleased]
-
-### Planned
+## Planned
 - Redis integration for distributed locking
 - Webhook notifications for task completion
 - Task dependencies (run task B after task A succeeds)

CLAUDE.md

@@ -0,0 +1,160 @@
+# CLAUDE.md — scheduler
+
+"The Scheduler" — system-wide maintenance orchestration for tower-of-joy: config backups, doc
+mirroring to Gitea, cleanup and retention, and arbitrary REST calls on a cron. Python 3.12 /
+FastAPI, APScheduler, PostgreSQL and Redis. Container `scheduler` on `docker-dataplane`,
+port **8090**, Redis DB **3**, Postgres DB **scheduler**.
+
+It is the homelab's cron. Recurring work belongs here rather than in a systemd timer (workspace D-5).
+
+## Live contract
+
+`http://localhost:8090/openapi.json` — 10 paths, `version: 1.4.0` (verified 2026-08-09). Human
+docs at `/docs`. Generated from running code, so read it instead of inferring routes.
+
+**Every route except `/health` requires `Authorization: Bearer $SCHEDULER_API_KEY`.** An
+unauthenticated call returns `{"detail": "Missing API key"}` at 200-shape JSON, not a 401 body
+you might pattern-match on.
+
+Note the old AGENTS.md told you to verify deploys against `192.168.86.149:8000/health`. That is
+**tatlock's** port, not this service's. It is 8090.
+
+## The thing that will mislead you: executors are chosen by data, not code
+
+`src/executors/*.py` are **never statically imported**. `src/tasks/executor.py:202` does:
+
+```python
+module_path = f"src.executors.{executor_name}"
+module = __import__(module_path, fromlist=['execute'])
+```
+
+where `executor_name` comes from a **row in the `scheduled_tasks` table**. Consequences, and
+they defeat both of the usual checks:
+
+- **grep finds nothing.** No file imports `config_backup_executor`; the name only ever exists as
+  a database string.
+- **`sys.modules` finds nothing either.** A cold `import src.main` loads only `src`, `src.config`,
+  `src.main`, `src.models`, `src.tasks`, `src.tasks.executor`. Every executor is absent until a
+  task actually fires. Absence there is a timing artifact, not evidence of death.
+
+**The authoritative source is the database.** As of 2026-08-09:
+
+| Executor | Rows | Enabled |
+|---|---|---|
+| `rest_api_executor` | 16 | yes |
+| `doc_sync_executor` | 2 | yes |
+| `config_backup_executor`, `docker_prune_executor`, `gitea_release_cleanup_executor`, `portainer_backup_executor`, `postgres_retention_executor` | 1 each | yes |
+| `example_executor` | 1 | **no** |
+| `gcs_backup_executor` | **0** | — |
+
+`gcs_backup_executor` has no rows at all. That does **not** make it dead code: it becomes live
+the instant someone inserts a row naming it, with no code change and no deploy. Treat unreferenced
+executors as *dormant*, not removable. An executor's contract is a module-level
+`execute(config, settings)` — a missing one is caught at run time and reported as
+`Executor <name> missing execute() function`, not at import or startup.
+
+Re-check with the query rather than trusting the table above:
+
+```bash
+docker exec scheduler python3 -c "
+import psycopg2
+from src.config import get_settings
+s = get_settings()
+c = psycopg2.connect(host=s.postgres_host, port=s.postgres_port, dbname=s.postgres_db,
+                     user=s.postgres_user, password=s.postgres_password)
+cur = c.cursor()
+cur.execute('SELECT executor, count(*), bool_or(enabled) FROM scheduled_tasks GROUP BY executor ORDER BY 1')
+[print(r) for r in cur.fetchall()]"
+```
+
+Build the connection from `get_settings()` fields as above. Do not print the assembled URL — it
+carries the Postgres password.
+
+## Database
+
+Three tables, and the names do not match the API paths: **`scheduled_tasks`** (not `tasks` —
+`SELECT … FROM tasks` fails with `UndefinedTable`), `task_executions`, `doc_sources`. Schema is
+SQLAlchemy (`src/models.py`); there is no Alembic here, unlike core-api.
+
+## Layout, and one trap in it
+
+`src/main.py` (app + routes), `src/config.py` (pydantic-settings), `src/models.py`,
+`src/tasks/executor.py` (the scheduling engine), `src/executors/` (the dynamically-loaded units).
+
+**`src/config/` also exists and is an empty directory.** `import src.config` resolves to
+`src/config.py` — verified in the container, `__file__` is `/app/src/config.py`, because a
+regular module wins over a namespace package. Do not "fix" this by moving config into the
+directory, and do not assume the directory is a package with contents.
+
+## Registering tasks
+
+Tasks are DB-driven, registered over the API — not YAML, not a file in this repo. See
+`TASK_REGISTRATION.md` for the payload shape and the cron-field conventions (`hour: -1` means
+every hour). There is also a workspace-level `scheduler` skill for driving it conversationally.
+
+## Working here
+
+Group new work by domain rather than by file type; a single large `routers/` folder is the thing
+to avoid. Reference: [FastAPI best practices](https://github.com/zhanymkanov/fastapi-best-practices).
+
+```bash
+.venv/bin/python -m pytest tests/          # or: pytest tests/
+```
+
+Test dependencies are the `test` extra in `pyproject.toml` (pytest, pytest-asyncio, pytest-cov,
+freezegun). `pytest.ini` is at the repo root. No linter is configured — no ruff/flake8 config and
+neither in the dependencies — so do not assume `ruff check` exists here.
+
+## CI
+
+`.gitea/workflows/build.yml` is the only workflow and triggers **only on `v*` tag push**: build,
+push image, ping Watchtower. There is **no CI test or lint gate**. Run the tests yourself before
+tagging.
+
+## Work tracking
+
+Work lives in **pql**, not a markdown TODO. **This repo's vault is standalone** — its tickets
+and its internal decisions live here in `.pql/` and `governance/`, and travel with a clone,
+because `.pql/changelog/` is committed and replayed by the git hooks (workspace D-15). The databases are
+gitignored and rebuildable with `pql plan rebuild`.
+
+`pql` is **not** on the non-interactive `PATH` — invoke it as `/home/jpmschweitzer/.local/bin/pql`.
+From inside this repo no `--vault` is needed: pql anchors at the nearest `.git/` ancestor, which
+is this repo.
+
+```bash
+/home/jpmschweitzer/.local/bin/pql ticket list          # this repo's open work
+/home/jpmschweitzer/.local/bin/pql plan whatsnext       # next unblocked item, with context
+/home/jpmschweitzer/.local/bin/pql decisions list       # this repo's own decisions
+```
+
+Stack-level decisions that constrain this service — the host, the network, deploy mechanics,
+and the fact that recurring work belongs here at all (workspace D-5) — live in the **workspace** vault
+and need the flag:
+
+```bash
+/home/jpmschweitzer/.local/bin/pql --vault /mnt/media/Projects decisions list --domain scheduler
+```
+
+Note `ticket new --decision D-N` resolves ids within **one** vault, so a ticket here cannot link
+to a workspace decision. Cite the id in the ticket body instead.
+
+## Git
+
+- **History is linear — no merge commits.** Work on `main`, or a short-lived branch that is
+  fast-forwarded and deleted. The previous AGENTS.md mandated a feature branch per change; that
+  rule was retired workspace-wide on 2026-08-08.
+- **Conventional Commits**: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
+- **Stage explicitly. Never `git add -A`** — it is denied by policy, and it sweeps in whatever
+  else is dirty, including secrets.
+- Update `CHANGELOG.md` for every user-facing change, under `[Unreleased]`.
+
+## Releasing
+
+Ask whether a deploy is wanted first — it is not automatic.
+
+1. Bump `version` in `pyproject.toml` (patch for fixes, minor for features).
+2. Move `[Unreleased]` entries into a dated section in `CHANGELOG.md`.
+3. Stage the changed files by name, commit, tag `vX.Y.Z`, `git push origin main --tags`.
+4. Gitea CI builds and pushes on the tag; Watchtower deploys it.
+5. Verify: `curl http://192.168.86.149:8090/health`.

Makefile

@@ -0,0 +1,55 @@
+# scheduler — the repo's command surface (D-27).
+#
+# There is no venv in this working tree today, even though CLAUDE.md documents
+# `.venv/bin/python -m pytest`. `make test` says so rather than failing with a
+# bare "No such file or directory", and `make setup` creates one.
+#
+# `python3` on this host is 3.8; PYTHON names 3.12 explicitly (D-26).
+
+VENV   := $(CURDIR)/.venv
+PYTHON ?= python3.12
+
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show this help
+	@grep -hE '^[a-z][a-z0-9_-]*:.*?## ' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: setup
+setup: ## Create the venv and install the test extra
+	$(PYTHON) -m venv .venv
+	$(VENV)/bin/pip install -e ".[test]"
+
+.PHONY: test
+test: ## Run the test suite
+	@test -x $(VENV)/bin/python || { echo "FAIL — no venv in this tree; run: make setup"; exit 69; }
+	$(VENV)/bin/python -m pytest tests/
+
+# No `lint` target, deliberately. CLAUDE.md states it outright: no linter is
+# configured, no ruff or flake8 config, neither in the dependencies. Per D-27
+# the name is reserved for repos that lint rather than mandated everywhere — a
+# target here could only fail or report clean for something never run.
+
+# git hands a hook a non-login shell, which never sees ~/.local/bin — where
+# gitleaks lands. Without this the scan reports "not installed" on every push,
+# which is a check that fails open (D-24).
+export PATH := $(HOME)/.local/bin:/usr/local/bin:$(PATH)
+
+.PHONY: secrets
+secrets: ## Scan the commits about to be pushed for credentials
+	@ci/secrets.sh
+
+# The call surface is identical in every repo; what it runs is not.
+#
+# `secrets` runs first, deliberately: it is the only failure here that cannot be
+# undone by fixing it afterwards. A failed lint costs another commit; a pushed
+# credential is cached and indexed whether or not it is later deleted.
+#
+# Some of these fail today, and are left wired anyway. The state was measured
+# once and written down in T-56 rather than being worked around here — a gate
+# quietly narrowed to what already passes is a gate that reports success for
+# doing nothing, which is the failure this workspace keeps rediscovering.
+.PHONY: pre-push
+pre-push: secrets ## Everything the pre-push hook runs
+	@echo "  --   not gated here yet: lint (no linter configured) and test (T-56)"

ci/secrets.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Secret scan over the commits about to be pushed.
+#
+# Lives here rather than inside .githooks/pre-push so it can be read, run by
+# hand (`make secrets`), and changed under review. A hook is a trigger; it is
+# not a home for logic. Identical in every repo in this workspace (D-27).
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+# A non-login shell — which is what git gives a hook — skips /etc/profile.d
+# and never sees ~/.local/bin, where the gitleaks release tarball lands.
+# Without this the scan reports "not installed" on every push.
+[ -d "$HOME/.local/bin" ] && PATH="$HOME/.local/bin:$PATH"
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "FAIL secrets — gitleaks not installed, so this check would be a no-op pretending to pass." >&2
+  echo "     https://github.com/gitleaks/gitleaks/releases → ~/.local/bin/gitleaks" >&2
+  exit 1
+fi
+
+# Scan the outgoing range, not full history. History here carries findings
+# that are settled — test fixtures and vendored third-party code — and a gate
+# that fails on something unfixable gets bypassed within a week. What matters
+# is what is about to leave this machine.
+if upstream=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null); then
+  range="$upstream..HEAD"
+elif git rev-parse --verify --quiet origin/main >/dev/null; then
+  range="origin/main..HEAD"
+else
+  range=""
+fi
+
+if [ -z "$range" ]; then
+  gitleaks dir . --redact --no-banner --exit-code 1 || {
+    echo "FAIL secrets — gitleaks found a credential in the working tree." >&2; exit 1; }
+  exit 0
+fi
+
+[ -n "$(git log --oneline "$range" 2>/dev/null)" ] || exit 0
+
+gitleaks git . --log-opts="$range" --redact --no-banner --exit-code 1 >/dev/null 2>&1 || {
+  echo "FAIL secrets — gitleaks found a credential in the commits being pushed." >&2
+  echo "     inspect (values redacted):  gitleaks git . --log-opts=\"$range\" --redact" >&2
+  echo "     then remove and rotate it, or suppress deliberately:" >&2
+  echo "       inline  '# gitleaks:allow  <reason>'" >&2
+  echo "       or add the fingerprint to .gitleaksignore WITH a reason" >&2
+  exit 1
+}
+echo "  ok   secrets"

governance/README.md

@@ -0,0 +1,54 @@
+# Decisions, Questions, Rejected
+
+This directory holds structured planning records that pql parses
+into pql.db. Each record is a `### [DQR]-N: Title` heading inside
+a markdown file. Files live in three per-type subdirectories:
+
+- `decisions/<domain>.md` — confirmed design decisions
+- `questions/<domain>.md` — open questions that may resolve into
+  decisions or rejected proposals
+- `rejected/<domain>.md` — rejected proposals (kept for the audit
+  trail)
+
+The parser infers domain from the filename stem and record type
+from the parent subdirectory.
+
+D-records that propose implementation work link to `initiative`-type
+tickets via `decision_ref`. Run `pql decisions show <id>
+--with-tickets` to inspect implementation status.
+
+## Recommended domains
+
+Start with this canonical set; create files as records land in
+each domain:
+
+- **architecture** — structural commitments (storage, layering,
+  languages, libraries)
+- **process** — team workflow (commits, branches, releases, reviews)
+- **design** — user-facing surface (UX, UI, public APIs)
+- **coding-conventions** — team-internal code shape (style, lint,
+  file layout)
+- **testing** — quality strategy (coverage, layers, gates)
+
+You might also want, project-permitting:
+
+- `accessibility` — if you ship user-facing software
+- `security` — if you handle user data or network surfaces
+- `licensing` — if you release open-source or commercial
+- `documentation` — if user-docs are non-trivial
+- `deployment` — if shipping is non-trivial
+- `performance` — if you have perf budgets / SLOs
+
+<!-- pql:records (auto-generated; do not edit manually) -->
+
+## Decisions
+
+- _(none)_
+
+## Open questions
+
+- _(none)_
+
+## Rejected
+
+- _(none)_

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "the-scheduler"
-version = "1.4.0"
+version = "1.5.1"
 description = "System-wide maintenance orchestration - backups, doc mirroring, cleanup, task automation"
 readme = "README.md"
 requires-python = ">=3.12"

src/executors/config_backup_executor.py

@@ -2,6 +2,20 @@
 Config Backup Executor
 Backs up Docker container configs and host-based service configs.
 Replicates functionality of maintenance container's backup-configs.sh
+
+The work runs in a worker thread. `execute` is awaited by the scheduling engine
+on the same event loop that serves `/health` and the whole REST API, and this
+job spends ~21 minutes inside tarfile and zlib. Called inline it starves the
+loop for that entire window: on 2026-08-11 the API was unreachable 03:05-03:25
+nightly and again at 07:39 when the job was triggered by hand, which is T-74.
+The hourly health check fires at :35 and had never once sampled the outage.
+
+`asyncio.to_thread` is the whole fix — zlib releases the GIL while compressing,
+so the loop gets scheduled normally. One caveat worth knowing: the engine wraps
+executors in `asyncio.wait_for`, and a thread cannot be cancelled. On timeout
+the task is recorded as failed while the tar keeps running to completion. That
+is still strictly better than blocking everything, and the configured timeout
+(3600s) is well clear of the observed 1263s.
 """
 import asyncio
 import logging
@@ -9,16 +23,75 @@ import tarfile
 import tempfile
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import List, Dict, Any
+from typing import Any, Callable, Dict, List, Optional
 
 from src.config import Settings
+from src.executors import health_report
 
 logger = logging.getLogger(__name__)
 
 
-async def execute(config: dict, settings: Settings) -> str:
+def _create_tar_filter(excludes: List[str]) -> Callable[[Any], Optional[Any]]:
+    """Build the tarfile filter for a set of exclude patterns.
+
+    Matching is **substring**, not glob, and that is deliberate: a pattern is
+    reduced to its literal core by dropping leading `*/` and trailing `/*`, and
+    a member is excluded when that core appears anywhere in its name.
+
+    It looks like a half-finished glob and the temptation is to "fix" it with
+    `fnmatch`. Doing so would break the deployed configuration badly, because
+    that configuration is written against these semantics:
+
+      ".log"              fnmatch would match only a file named exactly `.log`,
+                          so every log file starts being archived instead.
+      "ollama/models/*"   fnmatch anchors at the start of the name, and members
+                          are named `docker-data/ollama/models/...`, so nothing
+                          matches and many GB of model blobs enter the archive.
+
+    Same for `amp/Versions/*`, `qdrant/storage/*` and the rest — every one is an
+    unanchored mid-path fragment. The nightly archive would grow, not shrink.
+    `tests/test_config_backup_executor.py` pins both cases so this cannot be
+    changed silently.
     """
-    Execute config backup task.
+    cores = [p.replace('*/', '').replace('/*', '') for p in excludes]
+
+    def tar_filter(tarinfo):
+        for core in cores:
+            if core in tarinfo.name:
+                logger.debug(f"Excluding: {tarinfo.name}")
+                return None
+        return tarinfo
+
+    return tar_filter
+
+
+def _cleanup_old_backups(backup_dir: Path, retention_days: int) -> None:
+    """Remove backups older than the retention period."""
+    cutoff_date = datetime.now() - timedelta(days=retention_days)
+    removed_count = 0
+    removed_size = 0
+
+    logger.info(f"Cleaning up backups older than {retention_days} days...")
+
+    for backup_file in backup_dir.glob('docker-configs-*.tar.gz'):
+        file_mtime = datetime.fromtimestamp(backup_file.stat().st_mtime)
+
+        if file_mtime < cutoff_date:
+            file_size = backup_file.stat().st_size
+            logger.info(f"Removing old backup: {backup_file.name} (from {file_mtime:%Y-%m-%d})")
+            backup_file.unlink()
+            removed_count += 1
+            removed_size += file_size
+
+    if removed_count > 0:
+        removed_size_mb = removed_size / (1024 * 1024)
+        logger.info(f"Removed {removed_count} old backups, freed {removed_size_mb:.2f}MB")
+    else:
+        logger.info("No old backups to remove")
+
+
+def _backup(config: dict) -> str:
+    """The blocking body of the backup. Runs in a worker thread, never on the loop.
 
     Config schema:
         {
@@ -34,20 +107,11 @@ async def execute(config: dict, settings: Settings) -> str:
             "compress": true
         }
 
-    Args:
-        config: Backup configuration
-        settings: Global scheduler settings
-
-    Returns:
-        Summary of backup operation
-
-    Raises:
-        Exception: On backup failure
+    Returns a one-line summary. Raises on failure.
     """
     sources = config.get('sources', [])
     backup_dir = Path(config.get('backup_dir', '/backups/docker-configs'))
     retention_days = config.get('retention_days', 30)
-    compress = config.get('compress', True)
 
     if not sources:
         raise ValueError("No backup sources configured")
@@ -58,15 +122,12 @@ async def execute(config: dict, settings: Settings) -> str:
 
     logger.info(f"Starting Docker configs backup: {backup_filename}")
 
-    # Create backup directory
     backup_dir.mkdir(parents=True, exist_ok=True)
 
-    # Create temporary directory for staging
     with tempfile.TemporaryDirectory(prefix='backup-') as temp_dir:
         temp_path = Path(temp_dir)
         results = []
 
-        # Backup each source
         for source in sources:
             source_path = Path(source['path'])
             source_name = source['name']
@@ -78,23 +139,13 @@ async def execute(config: dict, settings: Settings) -> str:
 
             logger.info(f"Backing up {source_name} from {source_path}")
 
-            # Create tar for this source
             source_tar = temp_path / f"{source_name}.tar.gz"
 
-            def tar_filter(tarinfo):
-                """Filter function to exclude patterns."""
-                for pattern in excludes:
-                    # Simple pattern matching (could be enhanced with fnmatch)
-                    if pattern.replace('*/', '').replace('/*', '') in tarinfo.name:
-                        logger.debug(f"Excluding: {tarinfo.name}")
-                        return None
-                return tarinfo
-
             with tarfile.open(source_tar, 'w:gz') as tar:
                 tar.add(
                     source_path,
                     arcname=source_name,
-                    filter=tar_filter,
+                    filter=_create_tar_filter(excludes),
                     recursive=True
                 )
 
@@ -102,23 +153,19 @@ async def execute(config: dict, settings: Settings) -> str:
             results.append(f"{source_name}: {source_size:.2f}MB")
             logger.info(f"Backed up {source_name}: {source_size:.2f}MB")
 
-        # Combine all source backups into final archive
         logger.info("Creating combined backup archive...")
         with tarfile.open(backup_file, 'w:gz') as final_tar:
             for item in temp_path.glob('*.tar.gz'):
                 final_tar.add(item, arcname=item.name)
 
-    # Verify backup created
     if not backup_file.exists():
         raise Exception("Backup file was not created")
 
     backup_size = backup_file.stat().st_size / (1024 * 1024)  # MB
     logger.info(f"Backup created successfully: {backup_size:.2f}MB")
 
-    # Clean up old backups
-    await cleanup_old_backups(backup_dir, retention_days)
+    _cleanup_old_backups(backup_dir, retention_days)
 
-    # Count remaining backups
     backup_count = len(list(backup_dir.glob('docker-configs-*.tar.gz')))
     total_size = sum(f.stat().st_size for f in backup_dir.glob('docker-configs-*.tar.gz'))
     total_size_mb = total_size / (1024 * 1024)
@@ -133,27 +180,36 @@ async def execute(config: dict, settings: Settings) -> str:
     return output
 
 
-async def cleanup_old_backups(backup_dir: Path, retention_days: int):
-    """Remove backups older than retention period."""
-    cutoff_date = datetime.now() - timedelta(days=retention_days)
-    removed_count = 0
-    removed_size = 0
+async def _run(config: dict, settings: Settings) -> str:
+    """Await the backup without holding the event loop. See the module docstring."""
+    return await asyncio.to_thread(_backup, config)
 
-    logger.info(f"Cleaning up backups older than {retention_days} days...")
 
-    for backup_file in backup_dir.glob('docker-configs-*.tar.gz'):
-        # Get file modification time
-        file_mtime = datetime.fromtimestamp(backup_file.stat().st_mtime)
+async def execute(config: dict, settings: Settings) -> str:
+    """Run the backup and report its own outcome to check_history (D-33, T-69).
 
-        if file_mtime < cutoff_date:
-            file_size = backup_file.stat().st_size
-            logger.info(f"Removing old backup: {backup_file.name} (from {file_mtime:%Y-%m-%d})")
-            backup_file.unlink()
-            removed_count += 1
-            removed_size += file_size
-
-    if removed_count > 0:
-        removed_size_mb = removed_size / (1024 * 1024)
-        logger.info(f"Removed {removed_count} old backups, freed {removed_size_mb:.2f}MB")
-    else:
-        logger.info("No old backups to remove")
+    The report wraps the work rather than living inside it, so the failure path
+    cannot be forgotten: an exception is reported as critical and then re-raised,
+    leaving the task's own status untouched. Reporting only success would
+    reproduce exactly the blind spot this replaces — a monitor that cannot tell
+    a failed backup from one that has not run.
+    """
+    try:
+        output = await _run(config, settings)
+    except Exception as exc:
+        await health_report.report_async(
+            settings,
+            domain="backup",
+            status=health_report.CRITICAL,
+            source="scheduler/config_backup_executor",
+            metrics={"job": "scheduler/config_backup_executor", "error": str(exc)[:400]},
+        )
+        raise
+    await health_report.report_async(
+        settings,
+        domain="backup",
+        status=health_report.OK,
+        source="scheduler/config_backup_executor",
+        metrics={"job": "scheduler/config_backup_executor", "summary": output[:400]},
+    )
+    return output

src/executors/health_report.py

@@ -0,0 +1,155 @@
+"""Report a task's own outcome to the homelab's central health record.
+
+Why a process reports itself, rather than a monitor inferring it:
+
+The sysmon `backup` domain used to poll the mtime of the newest file in the
+backup directory, hourly, against a 48-hour threshold — for a job that runs once
+a day. Forty-seven of every forty-eight runs could not produce a new answer, and
+worse, a file-age poll cannot distinguish "the backup failed" from "the backup
+has not run yet". If tonight's job dies, yesterday's archive is 24 hours old and
+still reads healthy, and keeps reading healthy until hour 48. A failure stayed
+invisible for two days to the check whose only job was noticing it.
+
+This executor knows at 03:05. So it says so.
+
+Recorded as D-33 in the workspace vault: `check_history` is the central health
+record and any self-maintained service may push a row describing its own
+outcome. sysmon polls only the things that cannot report themselves.
+
+Three consequences that are load-bearing here:
+
+- `source` names the producer, because the table now has several writers and a
+  row must say which one wrote it.
+- `domain` is a shared namespace. Two producers claiming one name would
+  interleave silently.
+- **A reporting failure must never fail the task.** Backing up successfully and
+  failing to mention it is strictly better than the reverse. Everything here is
+  caught and logged, which means the absence of rows is the only symptom a
+  broken reporter produces — so check for rows, not for errors.
+"""
+
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+import psycopg2
+
+logger = logging.getLogger(__name__)
+
+# The database holding check_history. Not the scheduler's own database — this is
+# a cross-service write into the health record, and it is deliberate (D-33).
+HEALTH_DB = "sysmon"
+
+OK = "ok"
+WARNING = "warning"
+CRITICAL = "critical"
+
+
+def report(
+    settings: Any,
+    domain: str,
+    status: str,
+    source: str,
+    metrics: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Write one row to check_history. Returns whether it landed.
+
+    Never raises. A caller that lets this failure surface would turn a
+    successful backup into a failed task, which inverts the point.
+    """
+    metrics = metrics or {}
+    now = datetime.now(timezone.utc)
+    result = {
+        # The envelope the table has carried since the shell era. A reader of a
+        # year of history should not have to know which producer wrote a row in
+        # order to parse it.
+        "timestamp": now.isoformat(),
+        "source": source,
+        "domain": domain,
+        "status": status,
+        "metrics": metrics,
+    }
+
+    try:
+        conn = psycopg2.connect(
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            database=HEALTH_DB,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+            connect_timeout=10,
+        )
+    except Exception as exc:  # noqa: BLE001 - reporting must not raise
+        logger.warning("health report for %s could not connect to %s: %s", domain, HEALTH_DB, exc)
+        return False
+
+    try:
+        with conn:
+            with conn.cursor() as cur:
+                # Unqualified table name, resolved through the search_path of the
+                # sysmon database. Qualifying it as sysmon.check_history looks
+                # more careful and is wrong — that schema does not exist.
+                cur.execute(
+                    "INSERT INTO check_history (host, domain, status, ts, result) "
+                    "VALUES (%s, %s, %s, %s, %s)",
+                    (_host(), domain, status, now, json.dumps(result)),
+                )
+        logger.info("health report: %s=%s recorded", domain, status)
+        return True
+    except psycopg2.errors.InsufficientPrivilege as exc:
+        # Named separately because it is the expected first failure and the fix
+        # is a grant rather than a code change. The database's own message is
+        # printed verbatim rather than summarised: the first version of this
+        # asserted "lacks INSERT on check_history" and was wrong — the table
+        # grant was present and what was actually missing was USAGE on
+        # check_history_id_seq, the sequence behind its serial id. A diagnostic
+        # that names a cause it did not observe sends the reader to the wrong
+        # fix with confidence.
+        #
+        #   GRANT INSERT ON check_history TO <user>;
+        #   GRANT USAGE ON SEQUENCE check_history_id_seq TO <user>;
+        logger.warning(
+            "health report for %s refused by the database: %s. The task itself succeeded; "
+            "only the report was lost.",
+            domain, str(exc).strip().splitlines()[0],
+        )
+        return False
+    except Exception as exc:  # noqa: BLE001 - reporting must not raise
+        logger.warning("health report for %s failed: %s", domain, exc)
+        return False
+    finally:
+        conn.close()
+
+
+async def report_async(
+    settings: Any,
+    domain: str,
+    status: str,
+    source: str,
+    metrics: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """`report` for callers on the event loop. Prefer this one inside executors.
+
+    psycopg2 is a blocking driver, so calling `report` directly from an
+    `async def` holds the loop for the length of the connect and insert — up to
+    `connect_timeout` seconds if the database is unreachable, which is exactly
+    when a report is most likely to be attempted. The scheduler serves its own
+    `/health` from that loop, so the cost of a slow report is the whole service
+    appearing down (T-74).
+    """
+    return await asyncio.to_thread(report, settings, domain, status, source, metrics)
+
+
+def _host() -> str:
+    """The host a row is attributed to.
+
+    Every Redis key and check_history row is scoped by host so a second machine
+    reporting into the same store stays distinguishable. The scheduler runs in a
+    container, whose hostname is a container id — useless as an attribution — so
+    the physical host is named explicitly.
+    """
+    import os
+
+    return os.environ.get("SYSMON_HOST", "tower-of-joy")

src/executors/portainer_backup_executor.py

@@ -37,6 +37,7 @@ from pathlib import Path
 import httpx
 
 from src.config import Settings
+from src.executors import health_report
 
 logger = logging.getLogger(__name__)
 
@@ -72,7 +73,7 @@ def _prune(output_dir: Path, retention_days: int) -> int:
     return removed
 
 
-async def execute(config: dict, settings: Settings) -> str:
+async def _run(config: dict, settings: Settings) -> str:
     url = _substitute_env(config.get("url", "")).rstrip("/")
     api_key = _substitute_env(config.get("api_key", ""))
     output_dir = Path(config.get("output_dir", "/backups/portainer"))
@@ -138,3 +139,33 @@ async def execute(config: dict, settings: Settings) -> str:
     )
     logger.info(summary)
     return summary
+
+
+async def execute(config: dict, settings: Settings) -> str:
+    """Run the backup and report its own outcome to check_history (D-33, T-69).
+
+    The report wraps the work rather than living inside it, so the failure path
+    cannot be forgotten: an exception is reported as critical and then re-raised,
+    leaving the task's own status untouched. Reporting only success would
+    reproduce exactly the blind spot this replaces — a monitor that cannot tell
+    a failed backup from one that has not run.
+    """
+    try:
+        output = await _run(config, settings)
+    except Exception as exc:
+        await health_report.report_async(
+            settings,
+            domain="backup",
+            status=health_report.CRITICAL,
+            source="scheduler/portainer_backup_executor",
+            metrics={"job": "scheduler/portainer_backup_executor", "error": str(exc)[:400]},
+        )
+        raise
+    await health_report.report_async(
+        settings,
+        domain="backup",
+        status=health_report.OK,
+        source="scheduler/portainer_backup_executor",
+        metrics={"job": "scheduler/portainer_backup_executor", "summary": output[:400]},
+    )
+    return output

tests/test_config_backup_executor.py

@@ -1,214 +1,241 @@
+"""Tests for the config backup executor.
+
+These replace a set that arrived with the portainer-core extraction and had
+never passed in this repo: they patched the `Path` class wholesale, asserted
+`"backed up" in result` against a function that returns `"Backup completed: …"`,
+and one wrapped its only call in `except Exception: pass` with its assertion
+commented out. Seven were red from the initial commit onward, and there is no CI
+test gate here to notice (see CLAUDE.md).
+
+The replacements use real directories and real archives under `tmp_path`. A
+backup executor's whole job is what ends up inside the tar, and mocking
+`tarfile` means nothing is checked.
 """
-Tests for the config backup executor.
-"""
-import pytest
+import asyncio
+import os
+import tarfile
+import time
 from pathlib import Path
-from unittest.mock import AsyncMock, patch, MagicMock, mock_open
-from src.executors import config_backup_executor
+
+import pytest
+
 from src.config import Settings
+from src.executors import config_backup_executor
+
+
+def _make_source(root: Path) -> Path:
+    """A source tree with one file per exclude pattern the deployment uses."""
+    src = root / "docker-data"
+    (src / "ollama" / "models" / "blobs").mkdir(parents=True)
+    (src / "svc" / "cache").mkdir(parents=True)
+    (src / "svc" / "logs").mkdir(parents=True)
+
+    (src / "keep.conf").write_text("keep me")
+    (src / "svc" / "settings.json").write_text("keep me too")
+    (src / "ollama" / "models" / "blobs" / "sha256-abc").write_text("many GB in reality")
+    (src / "svc" / "cache" / "junk.bin").write_text("disposable")
+    (src / "svc" / "logs" / "app.log").write_text("noisy")
+    return src
+
+
+def _members(archive: Path) -> set:
+    """Names inside the inner per-source tar of a combined backup archive."""
+    with tarfile.open(archive, "r:gz") as outer:
+        inner_name = outer.getnames()[0]
+        fh = outer.extractfile(inner_name)
+        with tarfile.open(fileobj=fh, mode="r:gz") as inner:
+            return set(inner.getnames())
 
 
 @pytest.mark.executor
 @pytest.mark.unit
-class TestConfigBackupExecutor:
-    """Tests for config_backup_executor module."""
+class TestConfigBackup:
 
     @pytest.mark.asyncio
-    async def test_executor_requires_config_fields(self, test_settings: Settings):
-        """Test that executor validates required config."""
-        incomplete_config = {
-            "sources": []
-            # Missing backup_dir
-        }
+    async def test_no_sources_is_rejected(self, test_settings: Settings, tmp_path: Path):
+        with pytest.raises(ValueError, match="No backup sources"):
+            await config_backup_executor._run({"backup_dir": str(tmp_path)}, test_settings)
 
-        with pytest.raises((ValueError, KeyError)):
-            await config_backup_executor.execute(incomplete_config, test_settings)
+    def test_archive_contains_the_source(self, tmp_path: Path):
+        src = _make_source(tmp_path)
+        out = tmp_path / "backups"
+        summary = config_backup_executor._backup({
+            "sources": [{"path": str(src), "name": "docker-data", "excludes": []}],
+            "backup_dir": str(out),
+        })
 
-    @pytest.mark.asyncio
-    async def test_executor_with_minimal_config(self, test_settings: Settings, tmp_path: Path):
-        """Test executor with minimal valid configuration."""
-        backup_dir = tmp_path / "backups"
-        backup_dir.mkdir()
+        assert "Backup completed" in summary
+        archives = list(out.glob("docker-configs-*.tar.gz"))
+        assert len(archives) == 1
+        assert "docker-data/keep.conf" in _members(archives[0])
 
-        source_dir = tmp_path / "source"
-        source_dir.mkdir()
-        (source_dir / "test.txt").write_text("test content")
-
-        config = {
+    def test_excludes_keep_matching_members_out(self, tmp_path: Path):
+        """The patterns here are the ones the deployed task actually carries."""
+        src = _make_source(tmp_path)
+        out = tmp_path / "backups"
+        config_backup_executor._backup({
             "sources": [{
-                "path": str(source_dir),
-                "name": "test-source",
-                "excludes": []
+                "path": str(src),
+                "name": "docker-data",
+                "excludes": ["*/cache/*", ".log", "ollama/models/*"],
             }],
-            "backup_dir": str(backup_dir),
-            "compress": True,
-            "retention_days": 30
-        }
+            "backup_dir": str(out),
+        })
 
-        with patch('src.executors.config_backup_executor.Path') as mock_path_cls:
-            # Setup path mocking
-            mock_source = MagicMock()
-            mock_source.exists.return_value = True
-            mock_source.is_dir.return_value = True
-            mock_source.iterdir.return_value = [MagicMock(name="test.txt")]
+        names = _members(next(iter(out.glob("docker-configs-*.tar.gz"))))
+        assert "docker-data/keep.conf" in names
+        assert "docker-data/svc/settings.json" in names
+        assert "docker-data/svc/cache/junk.bin" not in names
+        assert "docker-data/svc/logs/app.log" not in names
+        assert "docker-data/ollama/models/blobs/sha256-abc" not in names
 
-            mock_backup = MagicMock()
-            mock_backup.mkdir = MagicMock()
+    def test_missing_source_is_skipped_not_fatal(self, tmp_path: Path):
+        src = _make_source(tmp_path)
+        out = tmp_path / "backups"
+        summary = config_backup_executor._backup({
+            "sources": [
+                {"path": str(tmp_path / "does-not-exist"), "name": "gone", "excludes": []},
+                {"path": str(src), "name": "docker-data", "excludes": []},
+            ],
+            "backup_dir": str(out),
+        })
+        assert "docker-data" in summary
+        assert "gone" not in summary
 
-            def path_side_effect(p):
-                if str(p) == str(source_dir):
-                    return mock_source
-                elif str(p) == str(backup_dir):
-                    return mock_backup
-                return MagicMock()
+    def test_cleanup_removes_only_expired_backups(self, tmp_path: Path):
+        out = tmp_path / "backups"
+        out.mkdir()
+        old = out / "docker-configs-20200101-000000.tar.gz"
+        recent = out / "docker-configs-20991231-000000.tar.gz"
+        unrelated = out / "notes.txt"
+        for f in (old, recent, unrelated):
+            f.write_text("x")
 
-            mock_path_cls.side_effect = path_side_effect
+        long_ago = time.time() - (30 * 86400)
+        os.utime(old, (long_ago, long_ago))
 
-            with patch('tarfile.open'), \
-                 patch('src.executors.config_backup_executor._cleanup_old_backups'):
+        config_backup_executor._cleanup_old_backups(out, retention_days=7)
 
-                result = await config_backup_executor.execute(config, test_settings)
-
-                assert "backed up" in result.lower() or "success" in result.lower()
-
-    @pytest.mark.asyncio
-    async def test_executor_excludes_patterns(self, test_settings: Settings, tmp_path: Path):
-        """Test that executor respects exclude patterns."""
-        backup_dir = tmp_path / "backups"
-        source_dir = tmp_path / "source"
-
-        config = {
-            "sources": [{
-                "path": str(source_dir),
-                "name": "test",
-                "excludes": ["*.log", "cache/*"]
-            }],
-            "backup_dir": str(backup_dir),
-            "compress": True
-        }
-
-        with patch('src.executors.config_backup_executor.Path'), \
-             patch('tarfile.open') as mock_tar, \
-             patch('src.executors.config_backup_executor._cleanup_old_backups'):
-
-            # Mock tarfile
-            mock_tar_obj = MagicMock()
-            mock_tar.return_value.__enter__ = MagicMock(return_value=mock_tar_obj)
-            mock_tar.return_value.__exit__ = MagicMock(return_value=None)
-
-            try:
-                await config_backup_executor.execute(config, test_settings)
-            except Exception:
-                # May fail due to mocking complexity, but that's ok
-                pass
-
-            # Should have attempted to create tarfile
-            # assert mock_tar.called  # Would check if it was actually called
-
-    @pytest.mark.asyncio
-    async def test_executor_handles_missing_source(self, test_settings: Settings, tmp_path: Path):
-        """Test executor handles missing source directory."""
-        backup_dir = tmp_path / "backups"
-        backup_dir.mkdir()
-
-        config = {
-            "sources": [{
-                "path": "/nonexistent/path",
-                "name": "missing",
-                "excludes": []
-            }],
-            "backup_dir": str(backup_dir),
-            "compress": True
-        }
-
-        with patch('src.executors.config_backup_executor.Path') as mock_path_cls:
-            mock_source = MagicMock()
-            mock_source.exists.return_value = False
-
-            mock_path_cls.return_value = mock_source
-
-            result = await config_backup_executor.execute(config, test_settings)
-
-            # Should skip non-existent sources
-            assert "skipped" in result.lower() or "not found" in result.lower() or "0" in result
-
-    @pytest.mark.asyncio
-    async def test_cleanup_old_backups(self, tmp_path: Path):
-        """Test cleanup of old backup files."""
-        backup_dir = tmp_path / "backups"
-        backup_dir.mkdir()
-
-        # Create some "old" backup files
-        old_backup = backup_dir / "backup-2020-01-01.tar.gz"
-        old_backup.write_text("old")
-
-        recent_backup = backup_dir / "backup-2025-12-01.tar.gz"
-        recent_backup.write_text("recent")
-
-        with patch('src.executors.config_backup_executor.Path') as mock_path_cls:
-            mock_backup_dir = MagicMock()
-            mock_old_file = MagicMock()
-            mock_old_file.name = "backup-2020-01-01.tar.gz"
-            mock_old_file.stat.return_value.st_mtime = 0  # Very old
-
-            mock_recent_file = MagicMock()
-            mock_recent_file.name = "backup-2025-12-01.tar.gz"
-            mock_recent_file.stat.return_value.st_mtime = 999999999999  # Recent
-
-            mock_backup_dir.glob.return_value = [mock_old_file, mock_recent_file]
-            mock_path_cls.return_value = mock_backup_dir
-
-            config_backup_executor._cleanup_old_backups(mock_backup_dir, retention_days=7)
-
-            # Old file should be removed
-            mock_old_file.unlink.assert_called_once()
+        assert not old.exists()
+        assert recent.exists()
+        assert unrelated.exists(), "cleanup must only touch files it wrote"
 
 
 @pytest.mark.executor
 @pytest.mark.unit
-class TestConfigBackupHelpers:
-    """Tests for helper functions."""
+class TestEventLoopIsNotBlocked:
+    """T-74. The scheduler serves its own API from the loop that runs executors.
 
-    def test_tar_filter_excludes_cache(self):
-        """Test that tar filter excludes cache directories."""
-        excludes = ["*/cache/*", "*.log"]
-        filter_func = config_backup_executor._create_tar_filter(excludes)
+    This job spends ~21 minutes in tarfile and zlib, so calling it inline made
+    the whole service unreachable 03:05-03:25 every night. The hourly health
+    check runs at :35 and so never once observed it — the outage was invisible
+    for as long as it existed.
+    """
 
-        # Mock tarinfo for cache file
-        cache_tarinfo = MagicMock()
-        cache_tarinfo.name = "data/cache/temp.txt"
+    @pytest.mark.asyncio
+    async def test_run_yields_to_the_loop_while_backing_up(
+        self, test_settings: Settings, monkeypatch
+    ):
+        blocked_for = 0.4
+        monkeypatch.setattr(
+            config_backup_executor, "_backup",
+            lambda config: (time.sleep(blocked_for), "Backup completed: fake")[1],
+        )
 
-        result = filter_func(cache_tarinfo)
-        assert result is None  # Should exclude
+        ticks = 0
 
-    def test_tar_filter_includes_normal_files(self):
-        """Test that tar filter includes normal files."""
-        excludes = ["*/cache/*"]
-        filter_func = config_backup_executor._create_tar_filter(excludes)
+        async def heartbeat():
+            nonlocal ticks
+            while True:
+                await asyncio.sleep(0.01)
+                ticks += 1
 
-        # Mock tarinfo for normal file
-        normal_tarinfo = MagicMock()
-        normal_tarinfo.name = "data/config.json"
+        hb = asyncio.create_task(heartbeat())
+        try:
+            result = await config_backup_executor._run({}, test_settings)
+        finally:
+            hb.cancel()
 
-        result = filter_func(normal_tarinfo)
-        assert result == normal_tarinfo  # Should include
+        assert result == "Backup completed: fake"
+        # Held inline, the loop gets no scheduling opportunity at all and this is
+        # 0. Off the loop it is ~40. The bar is low on purpose: the distinction
+        # being drawn is "the loop ran" versus "the loop was dead", and a loaded
+        # CI box should not turn that into a flake.
+        assert ticks >= 5, f"event loop starved during backup: {ticks} ticks"
 
-    def test_tar_filter_with_wildcard_patterns(self):
-        """Test tar filter with various wildcard patterns."""
-        excludes = ["*.log", "*.tmp", "temp/*"]
-        filter_func = config_backup_executor._create_tar_filter(excludes)
 
-        # Log file
-        log_tarinfo = MagicMock()
-        log_tarinfo.name = "app.log"
-        assert filter_func(log_tarinfo) is None
+@pytest.mark.executor
+@pytest.mark.unit
+class TestExcludeMatching:
+    """Substring matching, and why it must stay that way.
 
-        # Temp file
-        tmp_tarinfo = MagicMock()
-        tmp_tarinfo.name = "cache.tmp"
-        assert filter_func(tmp_tarinfo) is None
+    `_create_tar_filter` reduces each pattern to a literal core and asks whether
+    it appears anywhere in the member name. That reads like an unfinished glob,
+    and the obvious "improvement" is `fnmatch`. These tests exist to make that
+    change fail loudly, because the deployed config is written against these
+    semantics and `fnmatch` would silently stop excluding the largest things in
+    the tree.
+    """
 
-        # Normal file
-        normal_tarinfo = MagicMock()
-        normal_tarinfo.name = "config.json"
-        assert filter_func(normal_tarinfo) == normal_tarinfo
+    def test_mid_path_fragment_matches_anywhere(self):
+        """`ollama/models/*` must exclude a member named `docker-data/ollama/...`.
+
+        Under fnmatch the pattern anchors at the start of the name, does not
+        match, and many GB of model blobs enter the nightly archive.
+        """
+        f = config_backup_executor._create_tar_filter(["ollama/models/*"])
+
+        class TI:
+            name = "docker-data/ollama/models/blobs/sha256-abc"
+
+        assert f(TI()) is None
+
+    def test_bare_suffix_matches_every_file_carrying_it(self):
+        """The deployment excludes logs by the bare string `.log`, not `*.log`.
+
+        Under fnmatch this matches only a file named exactly `.log`, so every
+        real log file starts being archived.
+        """
+        f = config_backup_executor._create_tar_filter([".log"])
+
+        class TI:
+            name = "docker-data/svc/logs/app.log"
+
+        assert f(TI()) is None
+
+    def test_wrapped_pattern_is_reduced_to_its_core(self):
+        f = config_backup_executor._create_tar_filter(["*/cache/*"])
+
+        class Cache:
+            name = "docker-data/svc/cache/junk.bin"
+
+        class Normal:
+            name = "docker-data/svc/settings.json"
+
+        normal = Normal()
+        assert f(Cache()) is None
+        assert f(normal) is normal
+
+    def test_a_glob_star_is_not_interpreted(self):
+        """`*.log` is a literal here — it is not a suffix match.
+
+        This is the sharp edge of substring matching and the reason the deployed
+        config spells the pattern `.log`. Pinned so the behaviour is documented
+        rather than discovered.
+        """
+        f = config_backup_executor._create_tar_filter(["*.log"])
+
+        class TI:
+            name = "app.log"
+
+        ti = TI()
+        assert f(ti) is ti
+
+    def test_no_excludes_keeps_everything(self):
+        f = config_backup_executor._create_tar_filter([])
+
+        class TI:
+            name = "anything/at/all"
+
+        ti = TI()
+        assert f(ti) is ti