witan-core 0.2.0__tar.gz

witan_core-0.2.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+.venv/
+__pycache__/
+*.pyc
+
+# Environment / secrets
+.env
+.env.local
+.env.*.local
+*.secret
+
+# Editor
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+# omnigraph binary downloaded by hatch_build.py — not committed
+_bin/
+# omnigraph cluster state (populated by `omnigraph cluster import`)
+__cluster/
+
+# MCP server logs / caches
+.mcp-cache/
+mcp-server.log
+.ruff_cache/
+
+# agent-config-kit remote skill/hook fetch cache
+.agent-config-kit-cache/

witan_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `witan-core` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
+a MINOR bump may include breaking changes).
+
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- Remote-access layer (`witan_core.remote`, the `remote` extra) — the
+  transport-agnostic ADR-0005 path-a client stack, so a second deployed server
+  can reuse it: `DeviceAuth` (`witan_core.remote.oidc`) drives the OIDC
+  device-authorization grant (RFC 8628) + a 0600 token cache, parameterized by
+  cache path and login hint; `RemoteMCPProxy` (`witan_core.remote.proxy`) mirrors
+  a FastMCP server's tool surface over `streamable-http` (positional→name arg
+  mapping, `{"result": …}` envelope unwrap), with subclass hooks for the
+  admin-tool refusal set, client-side repo resolution, and error wording.
+  witan-council now binds its policy (cache location, `witan login` hint,
+  `_ADMIN_ONLY`, `repo.detect`) via thin shims instead of owning the mechanism.
+- CLI scaffolding (`witan_core.cli`, the `cli` extra): `AgentName`/`AGENT_NAMES`
+  (the supported coding-agent constants), `make_app` (the `--version`-wired
+  cyclopts app factory), `resolve_author` (`--author` → `git config user.name` →
+  `$USER` → `"unknown"`), and `report_install` (the agent-config install-result
+  printer — styled with a rich `console`, plain `print` without one). Both
+  servers' `setup` commands now share these instead of carrying divergent copies.
+- `agent-config-kit` is now a dependency of the `cli` extra (supplies
+  `resolve_version` and the `InstallResult` type) — a valid leaf→leaf edge, since
+  both servers already depend on it.
+
+## [0.1.0] - 2026-07-15
+
+Initial release of the shared `witan-core` package (import `witan_core`),
+mirroring `agent-config-kit`. Both witan MCP servers now depend on it via a
+`[tool.uv.sources]` editable path plus a `witan-core>=0.1,<1` PyPI range. This
+establishes the package and the deliberate reversal of the "no cross-package
+import" convention. See `docs/design/witan-core-extraction-spec.md`.
+
+### Added
+
+- `popen_detached` (`witan_core._detach`) — cross-platform detached subprocess spawning.
+- `install_omnigraph` (`witan_core.omnigraph_install`) — the pinned omnigraph
+  binary installer and single source of `_OMNIGRAPH_VERSION` (`rich` imported lazily).
+- `confirm`/`text` (`witan_core.elicit`) — MCP elicitation primitives (the `mcp` extra).
+- `normalise`/`find_git_config` (`witan_core.repo_key`) — the cross-layer
+  repo-key canonicalizer, with a golden contract test.
+- `now_iso` (`witan_core.timeutil`).
+- Throttled-optimize mechanics (`witan_core.maintenance`) — interval parsing,
+  atomic last-run stamp, and due-check.
+- `OmnigraphClient` base (`witan_core.omnigraph`) — the omnigraph-CLI subprocess
+  wrapper (write lock, retry/repair, per-actor admission-cap backoff,
+  `OmnigraphConflict`); each server subclasses it for its own tail.
+
+Extracted from the duplicated surface of `witan` (witan-council) and
+`witan-code`; the now-duplicated copies were deleted from both servers.

witan_core-0.2.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: witan-core
+Version: 0.2.0
+Summary: Shared core for the witan MCP servers (witan-council + witan-code)
+Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/packages/witan-core
+Project-URL: Repository, https://github.com/mitodl/agent-kit
+Project-URL: Issues, https://github.com/mitodl/agent-kit/issues
+License-Expression: BSD-3-Clause
+Keywords: agent,coding-agent,mcp,omnigraph,shared
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Provides-Extra: cli
+Requires-Dist: agent-config-kit<1,>=0.4; extra == 'cli'
+Requires-Dist: cyclopts<5,>=4; extra == 'cli'
+Requires-Dist: rich>=13; extra == 'cli'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<4,>=3.4.2; extra == 'mcp'
+Provides-Extra: remote
+Requires-Dist: fastmcp<4,>=3.4.2; extra == 'remote'
+Requires-Dist: httpx>=0.27; extra == 'remote'
+Description-Content-Type: text/markdown
+
+# witan-core
+
+Shared core for the two witan MCP servers — `witan` (dist `witan-council`,
+`mcp/servers/witan`) and `witan-code` (`mcp/servers/witan-code`). It is the third
+shared `packages/` sibling alongside
+[`agent-config-kit`](../agent-config-kit/README.md), wired into both servers via
+a `[tool.uv.sources]` editable path (dev/CI) plus a published PyPI version range.
+
+## Why
+
+The two servers were built copy-paste-and-diverge and carried an explicit
+"deliberately duplicated — no cross-package import" convention. As the shared
+surface grew, fixes had to be applied twice and silently drifted — including code
+that is *contractually required* to stay identical (the repo-key canonicalizer
+behind the cross-layer symbol join key; the pinned omnigraph binary version, kept
+in lockstep by a fragile Renovate custom manager).
+
+`witan-core` deliberately reverses that convention. The full rationale, scope,
+and per-extraction contracts live in
+[`docs/design/witan-core-extraction-spec.md`](../../docs/design/witan-core-extraction-spec.md).
+
+## Invariant
+
+`witan_core` imports **neither** `witan` nor `witan_code`. It is a leaf below
+both, preserving the one-directional `witan` → `witan_code` optional-mount DAG
+(`witan` mounts `witan-code` as `witan code`; `witan-code` never imports `witan`).
+
+## Dependencies
+
+The base package is stdlib-only. Heavier concerns are gated behind extras so
+neither server pulls weight it doesn't use:
+
+- `witan-core[cli]` → `cyclopts`, `rich` (CLI scaffolding, styled installer output)
+- `witan-core[mcp]` → `fastmcp` (MCP elicitation primitives)
+
+## What's here
+
+Extracted so far (each deletes the duplicated copies from both servers):
+
+- `_detach.popen_detached` — cross-platform detached subprocess spawning
+- `omnigraph_install` — the pinned-omnigraph-binary installer (single source of
+  the version; `rich` imported lazily)
+- `elicit` — the `confirm`/`text` MCP elicitation primitives (needs the `mcp`
+  extra; not re-exported from the package root)
+- `repo_key` — `normalise` + `find_git_config`, the cross-layer repo-key
+  canonicalizer, with a golden contract test
+- `timeutil.now_iso`
+- `maintenance` — the throttled-optimize stamp/interval/due mechanics
+- `omnigraph.OmnigraphClient` — the omnigraph-CLI subprocess wrapper base
+  (write lock, retry/repair, admission-cap backoff); each server subclasses it
+  (witan adds `apply_schema`; witan-code adds branch ops + bulk `load`)
+
+Still local to each server (intentionally): the CLI scaffolding — its
+extraction coordinates with the in-flight multi-user deployment work (see the
+spec).

witan_core-0.2.0/README.md

@@ -0,0 +1,55 @@
+# witan-core
+
+Shared core for the two witan MCP servers — `witan` (dist `witan-council`,
+`mcp/servers/witan`) and `witan-code` (`mcp/servers/witan-code`). It is the third
+shared `packages/` sibling alongside
+[`agent-config-kit`](../agent-config-kit/README.md), wired into both servers via
+a `[tool.uv.sources]` editable path (dev/CI) plus a published PyPI version range.
+
+## Why
+
+The two servers were built copy-paste-and-diverge and carried an explicit
+"deliberately duplicated — no cross-package import" convention. As the shared
+surface grew, fixes had to be applied twice and silently drifted — including code
+that is *contractually required* to stay identical (the repo-key canonicalizer
+behind the cross-layer symbol join key; the pinned omnigraph binary version, kept
+in lockstep by a fragile Renovate custom manager).
+
+`witan-core` deliberately reverses that convention. The full rationale, scope,
+and per-extraction contracts live in
+[`docs/design/witan-core-extraction-spec.md`](../../docs/design/witan-core-extraction-spec.md).
+
+## Invariant
+
+`witan_core` imports **neither** `witan` nor `witan_code`. It is a leaf below
+both, preserving the one-directional `witan` → `witan_code` optional-mount DAG
+(`witan` mounts `witan-code` as `witan code`; `witan-code` never imports `witan`).
+
+## Dependencies
+
+The base package is stdlib-only. Heavier concerns are gated behind extras so
+neither server pulls weight it doesn't use:
+
+- `witan-core[cli]` → `cyclopts`, `rich` (CLI scaffolding, styled installer output)
+- `witan-core[mcp]` → `fastmcp` (MCP elicitation primitives)
+
+## What's here
+
+Extracted so far (each deletes the duplicated copies from both servers):
+
+- `_detach.popen_detached` — cross-platform detached subprocess spawning
+- `omnigraph_install` — the pinned-omnigraph-binary installer (single source of
+  the version; `rich` imported lazily)
+- `elicit` — the `confirm`/`text` MCP elicitation primitives (needs the `mcp`
+  extra; not re-exported from the package root)
+- `repo_key` — `normalise` + `find_git_config`, the cross-layer repo-key
+  canonicalizer, with a golden contract test
+- `timeutil.now_iso`
+- `maintenance` — the throttled-optimize stamp/interval/due mechanics
+- `omnigraph.OmnigraphClient` — the omnigraph-CLI subprocess wrapper base
+  (write lock, retry/repair, admission-cap backoff); each server subclasses it
+  (witan adds `apply_schema`; witan-code adds branch ops + bulk `load`)
+
+Still local to each server (intentionally): the CLI scaffolding — its
+extraction coordinates with the in-flight multi-user deployment work (see the
+spec).

witan_core-0.2.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "witan-core"
+version = "0.2.0"
+description = "Shared core for the witan MCP servers (witan-council + witan-code)"
+readme = "README.md"
+license = "BSD-3-Clause"
+requires-python = ">=3.11"
+keywords = ["mcp", "agent", "omnigraph", "shared", "coding-agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+# Base modules (_detach, repo_key, timeutil, omnigraph, maintenance) are
+# stdlib-only on purpose so neither server pulls weight it doesn't use. Heavier
+# concerns are gated behind the extras below.
+dependencies = []
+
+[project.optional-dependencies]
+# cli.py (make_app/report_install/resolve_author) + the omnigraph installer's
+# styled output. agent-config-kit supplies resolve_version (--version wiring)
+# and the InstallResult type report_install prints; it is a sibling leaf package
+# both servers already depend on, so this stays a valid leaf→leaf edge.
+cli = ["cyclopts>=4,<5", "rich>=13", "agent-config-kit>=0.4,<1"]
+# elicit.py (fastmcp.server.elicitation.AcceptedElicitation).
+mcp = ["fastmcp>=3.4.2,<4"]
+# remote/ — the OIDC device-auth + token cache (httpx) and the MCP-client proxy
+# (fastmcp). ADR-0005 path-a client stack; a server's CLI uses it to reach its
+# deployed self. httpx is also a transitive fastmcp dep, relied on directly.
+remote = ["httpx>=0.27", "fastmcp>=3.4.2,<4"]
+
+[project.urls]
+Homepage = "https://github.com/mitodl/agent-kit/tree/main/packages/witan-core"
+Repository = "https://github.com/mitodl/agent-kit"
+Issues = "https://github.com/mitodl/agent-kit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["witan_core"]
+
+[tool.bumpversion]
+current_version = "0.2.0"
+allow_dirty = true
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[dependency-groups]
+# rich: the omnigraph installer imports it lazily; the installer tests exercise
+# that path. fastmcp: witan_core.elicit + remote.proxy import it (the `mcp` /
+# `remote` extras). cyclopts + agent-config-kit: the `cli` extra; the cli tests
+# exercise make_app/report_install. httpx: remote.oidc (the `remote` extra); the
+# device-auth tests drive it via httpx.MockTransport. All test-only — the base
+# package requires none of them.
+test = [
+    "pytest>=8",
+    "rich>=13",
+    "fastmcp>=3.4.2,<4",
+    "cyclopts>=4,<5",
+    "agent-config-kit>=0.4,<1",
+    "httpx>=0.27",
+]
+
+[tool.uv.sources]
+# Resolve the sibling shared package from the monorepo checkout for local dev
+# and CI; PyPI still serves it for external installs via the version range above.
+agent-config-kit = { path = "../agent-config-kit", editable = true }
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

witan_core-0.2.0/tests/test_cli.py

@@ -0,0 +1,102 @@
+"""CLI scaffolding shared by both servers' ``setup`` commands.
+
+The two servers rendered install results differently (rich markup vs plain
+print) and each carried its own copy of the agent-name constants and author
+resolution; these tests pin the shared behavior so a future divergence is caught
+here rather than in one server only.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from witan_core.cli import (
+    AGENT_NAMES,
+    AgentName,
+    make_app,
+    report_install,
+    resolve_author,
+)
+
+
+def _result(planned, skipped):
+    # report_install only reads .planned and .skipped, so a stub stands in for
+    # agent_config_kit.InstallResult (keeps the base test deps light).
+    return SimpleNamespace(planned=planned, skipped=skipped)
+
+
+def test_agent_names_cover_the_literal():
+    # Every AgentName except the "all" fan-out has a display label.
+    literals = set(AgentName.__args__) - {"all"}
+    assert literals == set(AGENT_NAMES)
+
+
+def test_resolve_author_prefers_explicit():
+    assert resolve_author("Ada Lovelace") == "Ada Lovelace"
+
+
+def test_resolve_author_falls_back_to_git(monkeypatch):
+    monkeypatch.setattr("subprocess.check_output", lambda *a, **k: "Git Name\n")
+    assert resolve_author(None) == "Git Name"
+
+
+def test_resolve_author_falls_back_to_user_env(monkeypatch):
+    def _no_git(*a, **k):
+        raise FileNotFoundError
+
+    monkeypatch.setattr("subprocess.check_output", _no_git)
+    monkeypatch.setenv("USER", "env_user")
+    assert resolve_author(None) == "env_user"
+
+
+def test_resolve_author_last_resort_unknown(monkeypatch):
+    monkeypatch.setattr("subprocess.check_output", lambda *a, **k: "  \n")
+    monkeypatch.delenv("USER", raising=False)
+    assert resolve_author(None) == "unknown"
+
+
+def test_report_install_plain(capsys):
+    report_install(
+        "claude",
+        _result(planned=["a.json"], skipped=[("b.json", "exists")]),
+        dry_run=False,
+    )
+    out = capsys.readouterr().out
+    assert "Claude Code" in out
+    assert "-> a.json" in out
+    assert "skip b.json — exists" in out
+    assert "[green]" not in out  # plain branch: no rich markup
+
+
+def test_report_install_dry_run_tag(capsys):
+    report_install("pi", _result(planned=["x"], skipped=[]), dry_run=True)
+    assert "(dry-run)" in capsys.readouterr().out
+
+
+def test_report_install_rich_uses_console_markup():
+    calls: list[str] = []
+    console = SimpleNamespace(print=lambda s: calls.append(s))
+    report_install(
+        "claude",
+        _result(planned=["a.json"], skipped=[("b.json", "exists")]),
+        dry_run=False,
+        console=console,
+    )
+    joined = "\n".join(calls)
+    assert "[bold]Claude Code[/bold]" in joined
+    assert "[green]→[/green] a.json" in joined
+    assert "[yellow]skip[/yellow] b.json — exists" in joined
+
+
+def test_make_app_sets_version(capsys):
+    app = make_app(
+        name="witan-core-test",
+        help_text="test app",
+        version_dist="witan-core",
+    )
+    with pytest.raises(SystemExit):
+        app(["--version"])
+    # resolve_version returns *some* string for the installed distribution.
+    assert capsys.readouterr().out.strip()

witan_core-0.2.0/tests/test_detach.py

@@ -0,0 +1,41 @@
+import subprocess
+import sys
+
+from witan_core import _detach
+
+
+def test_popen_detached_uses_start_new_session_on_posix(monkeypatch):
+    captured = {}
+
+    def fake_popen(args, **kwargs):
+        captured["args"] = args
+        captured["kwargs"] = kwargs
+        return "proc"
+
+    monkeypatch.setattr(sys, "platform", "linux")
+    monkeypatch.setattr(subprocess, "Popen", fake_popen)
+
+    result = _detach.popen_detached(["echo", "hi"])
+
+    assert result == "proc"
+    assert captured["kwargs"]["start_new_session"] is True
+    assert "creationflags" not in captured["kwargs"]
+
+
+def test_popen_detached_uses_creationflags_on_windows(monkeypatch):
+    captured = {}
+
+    def fake_popen(args, **kwargs):
+        captured["kwargs"] = kwargs
+        return "proc"
+
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0x200, raising=False)
+    monkeypatch.setattr(subprocess, "DETACHED_PROCESS", 0x8, raising=False)
+    monkeypatch.setattr(subprocess, "Popen", fake_popen)
+
+    result = _detach.popen_detached(["echo", "hi"])
+
+    assert result == "proc"
+    assert captured["kwargs"]["creationflags"] == 0x208
+    assert "start_new_session" not in captured["kwargs"]

witan_core-0.2.0/tests/test_elicit.py

@@ -0,0 +1,72 @@
+"""Tests for the shared elicitation primitives.
+
+Moved here from the two servers' test_elicit.py (where confirm/text were
+duplicated). Each server keeps only its own composed helper's tests
+(``repo_or_detect`` for witan, ``choose_repo`` for witan-code).
+"""
+
+import asyncio
+
+from fastmcp.server.elicitation import AcceptedElicitation, DeclinedElicitation
+
+from witan_core import elicit
+
+
+class _AcceptCtx:
+    def __init__(self, data):
+        self._data = data
+
+    async def elicit(self, message, response_type=None, **kwargs):
+        return AcceptedElicitation(data=self._data)
+
+
+class _DeclineCtx:
+    async def elicit(self, message, response_type=None, **kwargs):
+        return DeclinedElicitation()
+
+
+class _RaiseCtx:
+    async def elicit(self, *args, **kwargs):
+        raise RuntimeError("unsupported")
+
+
+def test_confirm_no_ctx_or_error_returns_default():
+    assert (
+        asyncio.run(elicit.confirm(None, "q?", default_when_unsupported=True)) is True
+    )
+    assert (
+        asyncio.run(elicit.confirm(None, "q?", default_when_unsupported=False)) is False
+    )
+    assert (
+        asyncio.run(elicit.confirm(_RaiseCtx(), "q?", default_when_unsupported=True))
+        is True
+    )
+
+
+def test_confirm_accept_and_decline():
+    assert (
+        asyncio.run(
+            elicit.confirm(_AcceptCtx(True), "q?", default_when_unsupported=False)
+        )
+        is True
+    )
+    # accepting with a False value is still a "no"
+    assert (
+        asyncio.run(
+            elicit.confirm(_AcceptCtx(False), "q?", default_when_unsupported=True)
+        )
+        is False
+    )
+    assert (
+        asyncio.run(elicit.confirm(_DeclineCtx(), "q?", default_when_unsupported=True))
+        is False
+    )
+
+
+def test_text_no_ctx_error_or_empty_returns_default():
+    assert asyncio.run(elicit.text(None, "q?", default="d")) == "d"
+    assert asyncio.run(elicit.text(_RaiseCtx(), "q?", default="d")) == "d"
+    assert asyncio.run(elicit.text(_AcceptCtx(""), "q?", default="d")) == "d"
+    # whitespace-only is treated as empty → default; a real value is stripped
+    assert asyncio.run(elicit.text(_AcceptCtx("   "), "q?", default="d")) == "d"
+    assert asyncio.run(elicit.text(_AcceptCtx("  real  "), "q?", default="d")) == "real"

witan_core-0.2.0/tests/test_import.py

@@ -0,0 +1,23 @@
+"""Package-level invariants.
+
+The leaf-package invariant (importing witan_core must pull in neither server) is
+load-bearing: it is what lets both servers depend on witan_core without a cycle.
+"""
+
+import sys
+
+
+def test_public_surface_is_exported():
+    import witan_core
+
+    assert "popen_detached" in witan_core.__all__
+    for name in witan_core.__all__:
+        assert hasattr(witan_core, name), name
+
+
+def test_no_cross_package_import():
+    """witan_core must import neither witan nor witan_code (leaf invariant)."""
+    import witan_core  # noqa: F401
+
+    assert "witan" not in sys.modules
+    assert "witan_code" not in sys.modules

witan_core-0.2.0/tests/test_maintenance.py

@@ -0,0 +1,87 @@
+from witan_core import maintenance
+
+
+def test_resolve_interval_env_override(monkeypatch):
+    monkeypatch.delenv("X_INTERVAL", raising=False)
+    assert (
+        maintenance.resolve_interval("X_INTERVAL")
+        == maintenance.DEFAULT_OPTIMIZE_INTERVAL
+    )
+    monkeypatch.setenv("X_INTERVAL", "3600")
+    assert maintenance.resolve_interval("X_INTERVAL") == 3600.0
+    monkeypatch.setenv("X_INTERVAL", "0")
+    assert maintenance.resolve_interval("X_INTERVAL") == 0.0
+    # non-numeric falls back to the default
+    monkeypatch.setenv("X_INTERVAL", "nope")
+    assert maintenance.resolve_interval("X_INTERVAL", 42.0) == 42.0
+
+
+def test_mark_run_last_run_atomic_roundtrip(tmp_path):
+    stamp = tmp_path / "stamp.json"
+    maintenance.mark_run(stamp, 12345.0)
+    assert maintenance.last_run(stamp) == 12345.0
+    # no leftover temp files
+    assert not list(tmp_path.glob("*.tmp"))
+
+
+def test_last_run_missing_or_corrupt_is_zero(tmp_path):
+    assert maintenance.last_run(tmp_path / "absent.json") == 0.0
+    corrupt = tmp_path / "corrupt.json"
+    corrupt.write_text("{ not json")
+    assert maintenance.last_run(corrupt) == 0.0
+
+
+def test_is_due_branches(tmp_path):
+    store = tmp_path / "graph.omni"
+    store.mkdir()
+    stamp = tmp_path / "stamp.json"
+    kw = dict(store=str(store), stamp_file=stamp, now=10_000.0)
+
+    # disabled
+    assert maintenance.is_due(interval=0, require_exists=False, **kw) is False
+    # remote store never fires
+    assert (
+        maintenance.is_due(
+            store="https://example.com/g",
+            stamp_file=stamp,
+            interval=3600,
+            now=10_000.0,
+            require_exists=False,
+        )
+        is False
+    )
+    # missing store when require_exists
+    assert (
+        maintenance.is_due(
+            store=str(tmp_path / "absent.omni"),
+            stamp_file=stamp,
+            interval=3600,
+            now=10_000.0,
+            require_exists=True,
+        )
+        is False
+    )
+    # due when never run
+    assert maintenance.is_due(interval=3600, require_exists=True, **kw) is True
+    # not due right after a run; due again after the window
+    maintenance.mark_run(stamp, 10_000.0)
+    assert (
+        maintenance.is_due(
+            interval=3600,
+            require_exists=True,
+            store=str(store),
+            stamp_file=stamp,
+            now=10_100.0,
+        )
+        is False
+    )
+    assert (
+        maintenance.is_due(
+            interval=3600,
+            require_exists=True,
+            store=str(store),
+            stamp_file=stamp,
+            now=14_000.0,
+        )
+        is True
+    )