@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/lib/config.mjs

@@ -0,0 +1,165 @@
+// Runtime gate configuration for the hooks. Self-contained: Node built-ins only, no npm,
+// so it works when the plugin is installed on its own.
+//
+// This is the READER the gates use at runtime. The CLI (`cli/config.mjs`) is the WRITER;
+// the two never import each other. Both agree on the file: `<project root>/.ai/config.json`,
+// with `~/.claude/claude-gates/config.json` as the global fallback.
+//
+// ── Two things a project controls per gate ──────────────────────────────────────────
+//   1. enabled — is the gate on? A gate absent from config keeps the registry default.
+//   2. params  — how the gate behaves: its whitelist, its patterns, its watched paths.
+//      A param the project declares REPLACES the gate's built-in default wholesale (it
+//      does not merge). The gate ships its defaults in its own source so the user can
+//      read them and know exactly what to override.
+//
+// ── Config shape a project may write ────────────────────────────────────────────────
+//   "gates": {
+//     "blockDestructiveShellCommands": true,                  // shorthand: enabled only
+//     "blockWritesToProtectedPaths": { "enabled": true, "protectedPaths": ["...","..."] }
+//   }
+// A bare boolean is the enabled-only shorthand the CLI writes today; an object carries
+// enabled plus any params. Both are accepted so an old plain config keeps working.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const CLAUDE_USER_DIRECTORY = '.claude';
+const GLOBAL_STATE_DIRECTORY = 'claude-gates';
+const PROJECT_STATE_DIRECTORY = '.ai';
+const CONFIG_FILE = 'config.json';
+// Markers that identify a project root while climbing. Both `.git` AND `.ai/` count — the
+// same set the CLI uses — so a repo-less project (no git yet) still gets its project config
+// read. Anchoring on `.git` alone silently dropped the project layer in such repos.
+const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
+
+function readJsonOrNull(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    // A corrupt project config must not silently disable protection: treat it as absent,
+    // which falls through to the global config and then to the registry defaults.
+    return null;
+  }
+}
+
+/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function projectConfigPath(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  if (!root) return null;
+  return join(root, PROJECT_STATE_DIRECTORY, CONFIG_FILE);
+}
+
+function globalConfigPath(home) {
+  return join(home, CLAUDE_USER_DIRECTORY, GLOBAL_STATE_DIRECTORY, CONFIG_FILE);
+}
+
+/**
+ * The `gates` object from the first config that exists: project first, then global.
+ * A project config that exists but lacks a `gates` key still wins (an empty object) —
+ * declaring a config is a deliberate act, and falling through to global would silently
+ * re-enable what the project meant to turn off.
+ */
+function gatesLayerFor(startDirectory, home) {
+  const projectPath = projectConfigPath(startDirectory);
+  const projectData = projectPath ? readJsonOrNull(projectPath) : null;
+  if (projectData) return projectData.gates ?? {};
+
+  const globalData = readJsonOrNull(globalConfigPath(home));
+  if (globalData) return globalData.gates ?? {};
+
+  return null; // nothing declared anywhere: gates fall back to registry defaults
+}
+
+/** Normalizes a gate's config entry (bool shorthand or object) to a plain object. */
+function gateEntryOf(gatesLayer, configKey) {
+  if (!gatesLayer) return null;
+  const entry = gatesLayer[configKey];
+  if (entry === undefined) return null;
+  if (typeof entry === 'boolean') return { enabled: entry };
+  if (entry && typeof entry === 'object') return entry;
+  return null; // malformed (string/number/null): ignore, fall back to default
+}
+
+/**
+ * Reads the gates layer once per dispatcher invocation and hands back a lookup the
+ * dispatcher and gates share. Reading once matters: N gates in the same tool call must
+ * not each re-read and re-parse the file.
+ *
+ * @param {string} startDirectory usually process.cwd()
+ * @returns {{ isEnabled(configKey, registryDefault): boolean,
+ *             paramsFor(configKey): object }}
+ */
+export function loadGateConfig(startDirectory, { home = homedir() } = {}) {
+  const gatesLayer = gatesLayerFor(startDirectory, home);
+
+  return {
+    /**
+     * A gate runs unless a config explicitly turns it off. `enabled` absent means "use
+     * the registry default"; only an explicit `false` disables. When no config exists
+     * anywhere, the registry default decides.
+     */
+    isEnabled(configKey, registryDefault) {
+      const entry = gateEntryOf(gatesLayer, configKey);
+      if (!entry || entry.enabled === undefined) return registryDefault;
+      return entry.enabled !== false;
+    },
+
+    /**
+     * The project's params for a gate (everything except `enabled`), or an empty object
+     * when none are declared. The gate merges these over its own built-in defaults —
+     * a declared param replaces the corresponding default wholesale.
+     */
+    paramsFor(configKey) {
+      const entry = gateEntryOf(gatesLayer, configKey);
+      if (!entry) return {};
+      const parameters = { ...entry };
+      delete parameters.enabled;
+      return parameters;
+    },
+  };
+}
+
+/**
+ * Whether a gate should run, standalone. `registryDefault` decides when the project (and
+ * global) config is silent about this gate; only an explicit `enabled: false` turns a gate
+ * off. Used by `runGate` at each gate's start.
+ */
+export function isGateEnabled(
+  configKey,
+  registryDefault,
+  startDirectory,
+  { home = homedir() } = {},
+) {
+  return loadGateConfig(startDirectory, { home }).isEnabled(
+    configKey,
+    registryDefault,
+  );
+}
+
+/**
+ * A single gate's project params (its whitelist/patterns), standalone. Returns {} when
+ * nothing is declared, so the gate falls back to its own built-in defaults.
+ */
+export function gateParameters(
+  configKey,
+  startDirectory,
+  { home = homedir() } = {},
+) {
+  return loadGateConfig(startDirectory, { home }).paramsFor(configKey);
+}

package/plugins/gates/hooks/lib/hook-io.mjs

@@ -0,0 +1,208 @@
+// Process I/O shared by every gate. Self-contained: Node built-ins only, so a gate keeps
+// working when installed outside this repo.
+//
+// There is no dispatcher: Claude Code runs one hook entry per gate natively (each with its
+// own `matcher`, all matching entries in parallel), so each gate is its own process and
+// reads its own stdin. This module holds what every gate needs, none of it gate-specific:
+//   1. Reading and parsing the hook payload Claude Code writes to stdin.
+//   2. Translating the registry's semantic tool groups (write/shell/...) into the concrete
+//      tool names Claude Code sends — used to derive each gate's `matcher` and, when a gate
+//      also inspects delegation prompts, to recognize the tool at runtime.
+//   3. Reading a deny/warn decision out of a gate's own JSON output shape.
+
+import { readFileSync } from 'node:fs';
+import { gateParameters, isGateEnabled } from './config.mjs';
+
+const STDIN_FILE_DESCRIPTOR = 0;
+
+/**
+ * Semantic tool groups (as declared in registry.json's `tools`) mapped to the concrete
+ * tool names Claude Code emits. Keeping the map here (not in the registry) keeps the
+ * catalog declarative: which tool names exist is a fact about the Claude Code runtime,
+ * not about the gate. `matcherFor` turns a group set into the `Tool1|Tool2` string a
+ * hooks.json entry uses; `toolNamesFor` gives the flat list a gate matches at runtime.
+ */
+export const TOOL_GROUPS = Object.freeze({
+  write: [
+    'Write',
+    'Edit',
+    'NotebookEdit',
+    'write_to_file',
+    'replace_file_content',
+  ],
+  shell: ['Bash', 'run_command'],
+  delegation: ['Agent', 'Task', 'invoke_subagent'],
+  question: ['AskUserQuestion'],
+  // The main agent materializing a change directly, whatever the surface.
+  execution: [
+    'Write',
+    'Edit',
+    'NotebookEdit',
+    'write_to_file',
+    'replace_file_content',
+    'Bash',
+    'run_command',
+    'mcp__ide__executeCode',
+  ],
+});
+
+/** Every concrete tool name a set of groups expands to, de-duplicated. */
+export function toolNamesFor(groups) {
+  const names = new Set();
+  for (const group of groups) {
+    for (const name of TOOL_GROUPS[group] ?? []) names.add(name);
+  }
+  return [...names];
+}
+
+/** The `matcher` string for a hooks.json entry: `Bash|Edit|Write`, or '' when empty. */
+export function matcherFor(groups) {
+  return toolNamesFor(groups).join('|');
+}
+
+/** Reads the raw hook payload from stdin. Returns null when stdin cannot be read. */
+export function readHookPayload() {
+  try {
+    return readFileSync(STDIN_FILE_DESCRIPTOR, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The tool name inside a raw payload. Returns null when the payload is unparseable —
+ * the caller cannot filter by tool then, so it must run every gate rather than skip
+ * silently (erring toward over-running protects; erring toward skipping leaves a mute hole).
+ */
+export function toolNameOf(rawPayload) {
+  try {
+    const payload = JSON.parse(rawPayload);
+    return payload?.tool_name ?? payload?.name ?? '';
+  } catch {
+    return null;
+  }
+}
+
+/** The session id inside a raw payload, or null when absent/unparseable. */
+export function sessionIdOf(rawPayload) {
+  try {
+    return JSON.parse(rawPayload)?.session_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The tool input object inside a raw payload, or {} when absent/unparseable. */
+export function toolInputOf(rawPayload) {
+  try {
+    const payload = JSON.parse(rawPayload);
+    return payload?.tool_input ?? payload?.input ?? {};
+  } catch {
+    return {};
+  }
+}
+
+const PRE_TOOL_USE_EVENT = 'PreToolUse';
+
+/**
+ * A gate answers Claude Code in exactly one of three ways, and every gate uses these
+ * emitters so the JSON shape is written once:
+ *   - deny:  the rule is deterministic and the action is wrong. Blocks the tool call.
+ *   - warn:  the question needs judgment; the gate surfaces context at the right moment
+ *            (additionalContext) and lets the call proceed.
+ *   - allow: nothing to say. The common path — silent and cheap.
+ * Each emitter exits the process (exit 0 always: a PreToolUse deny is expressed in the
+ * JSON, not in the exit code — reserving exit codes keeps a crash distinguishable).
+ *
+ * `label` is the gate id, prefixed to every message so a block names its source.
+ */
+export function deny(label, reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: PRE_TOOL_USE_EVENT,
+        permissionDecision: 'deny',
+        permissionDecisionReason: `[${label}] ${reason}`,
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+export function warn(label, context) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: PRE_TOOL_USE_EVENT,
+        additionalContext: `[${label}] ${context}`,
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+export function allow() {
+  process.exit(0);
+}
+
+/**
+ * The scaffolding every gate shares, so a gate file is just its rule. Given a gate's
+ * identity and a `check` function, this: reads stdin (allow when unreadable), turns the
+ * gate off when the project config disables it (allow), loads the project's params merged
+ * over the gate's own defaults, and runs `check`. `check` calls `deny`/`warn` to object,
+ * or returns to allow. A throw inside `check` is caught and turned into a deny — a gate
+ * that cannot evaluate must not silently permit.
+ *
+ * @param {object} gate
+ * @param {string} gate.id            registry id, used as the message label
+ * @param {string} gate.configKey     the config flag that enables/disables this gate
+ * @param {boolean} gate.enabledByDefault  the registry default when config is silent
+ * @param {object} [gate.defaultParams]    the gate's built-in params (the readable defaults)
+ * @param {(context: { rawPayload: string, toolName: string, toolInput: object,
+ *                     sessionId: string|null, parameters: object }) => void} check
+ */
+export async function runGate(gate, check) {
+  // Defaults-dump mode: when the CLI spawns a gate with this flag set, the gate prints its
+  // own descriptor (id, configKey, default flag and built-in params) and exits — before
+  // touching stdin. This lets `init` materialize each gate's defaults into the config it
+  // writes, with the gate as the single source of truth (no duplication in the registry).
+  if (process.env.CLAUDE_GATES_DUMP_DEFAULTS) {
+    process.stdout.write(
+      JSON.stringify({
+        id: gate.id,
+        configKey: gate.configKey,
+        enabledByDefault: gate.enabledByDefault,
+        defaultParams: gate.defaultParams ?? {},
+      }),
+    );
+    process.exit(0);
+  }
+
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+
+  if (!isGateEnabled(gate.configKey, gate.enabledByDefault, process.cwd()))
+    allow();
+
+  const declared = gateParameters(gate.configKey, process.cwd());
+  const parameters = { ...(gate.defaultParams ?? {}), ...declared };
+
+  try {
+    // `check` may be sync or async; awaiting a non-promise is transparent, so the same
+    // scaffolding serves both. Crucially, allow() runs only AFTER the check settles — an
+    // async gate that permits early would never block.
+    await check({
+      rawPayload,
+      toolName: toolNameOf(rawPayload) ?? '',
+      toolInput: toolInputOf(rawPayload),
+      sessionId: sessionIdOf(rawPayload),
+      parameters,
+    });
+  } catch (error) {
+    deny(
+      gate.id,
+      `The gate failed to evaluate and blocks the action for safety: ${error?.message ?? error}.`,
+    );
+  }
+  allow();
+}

package/plugins/tasks/hooks/lib/__tests__/task-store.test.mjs

@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { openTaskStore, STATUS } from '../task-store.mjs';
+
+// A temp project with a .git marker, so the store anchors its .ai/tasks/ there.
+function makeProject() {
+  const project = mkdtempSync(join(tmpdir(), 'task-store-'));
+  mkdirSync(join(project, '.git'));
+  return project;
+}
+
+function sampleTask(id) {
+  return {
+    id,
+    title: `task ${id}`,
+    description: 'desc',
+    status: STATUS.OPEN,
+    size: 'trivial',
+    createdAt: new Date().toISOString(),
+    messages: [],
+  };
+}
+
+test('openTaskStore anchors at the nearest project marker (.ai/ counts, not only .git)', () => {
+  // A project rooted only by .ai/ (no .git) must still resolve — the repo-less case.
+  const project = mkdtempSync(join(tmpdir(), 'ai-only-'));
+  mkdirSync(join(project, '.ai'));
+  const nested = join(project, 'src', 'deep');
+  mkdirSync(nested, { recursive: true });
+  const store = openTaskStore(nested);
+  assert.ok(
+    store,
+    'store resolves from a nested dir under an .ai/-rooted project',
+  );
+  assert.equal(store.root, project);
+});
+
+test('add and active: a new task shows up in active', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  const active = store.active();
+  assert.equal(active.length, 1);
+  assert.equal(active[0].id, 't1');
+  assert.deepEqual(store.history(), []);
+});
+
+test('update merges fields into the active task', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  store.update('t1', { status: STATUS.BLOCKED, note: 'waiting' });
+  const task = store.active()[0];
+  assert.equal(task.status, STATUS.BLOCKED);
+  assert.equal(task.note, 'waiting');
+  assert.equal(store.update('missing', {}), null);
+});
+
+test('close MOVES a task from active to history, never deletes', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  store.add(sampleTask('t2'));
+
+  const closed = store.close('t1', STATUS.DONE, 'finished');
+  assert.equal(closed.status, STATUS.DONE);
+  assert.equal(closed.closeReason, 'finished');
+  assert.ok(closed.closedAt);
+
+  assert.deepEqual(
+    store.active().map((task) => task.id),
+    ['t2'],
+  );
+  assert.deepEqual(
+    store.history().map((task) => task.id),
+    ['t1'],
+  );
+});
+
+test('abandon is a terminal close: moves to history with reason', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  store.close('t1', STATUS.ABANDONED, 'no longer needed');
+  assert.equal(store.active().length, 0);
+  assert.equal(store.history()[0].status, STATUS.ABANDONED);
+  assert.equal(store.history()[0].closeReason, 'no longer needed');
+});
+
+test('close rejects a non-terminal status and an unknown id', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  assert.equal(store.close('t1', STATUS.OPEN, 'x'), null);
+  assert.equal(store.close('missing', STATUS.DONE, 'x'), null);
+  assert.equal(store.active().length, 1);
+});
+
+test('counter persists and reads back', () => {
+  const store = openTaskStore(makeProject());
+  assert.equal(store.counter(), 0);
+  store.setCounter(7);
+  assert.equal(store.counter(), 7);
+});
+
+test('history is append-only across multiple closes', () => {
+  const store = openTaskStore(makeProject());
+  store.add(sampleTask('t1'));
+  store.add(sampleTask('t2'));
+  store.close('t1', STATUS.DONE, 'a');
+  store.close('t2', STATUS.ABANDONED, 'b');
+  assert.deepEqual(
+    store.history().map((task) => task.id),
+    ['t1', 't2'],
+  );
+});
+
+test('a corrupt active.json is treated as empty, then healed by a write', () => {
+  const project = makeProject();
+  const store = openTaskStore(project);
+  mkdirSync(join(project, '.ai', 'tasks'), { recursive: true });
+  const path = join(project, '.ai', 'tasks', 'active.json');
+  writeFileSync(path, '{broken');
+  assert.deepEqual(store.active(), []);
+  store.add(sampleTask('t1'));
+  assert.ok(existsSync(path));
+  assert.equal(JSON.parse(readFileSync(path, 'utf8')).tasks.length, 1);
+});

package/plugins/tasks/hooks/lib/task-store.mjs

@@ -0,0 +1,159 @@
+// The task store: the single source of truth for a project's tasks, on disk under
+// .ai/tasks/. Self-contained (Node built-ins only) so a hook can use it when the plugin is
+// installed on its own.
+//
+// justification: no existing tool covers this. Audited LOCAL deps (find-up, commander,
+// @clack/prompts, zod — none is a task store), CONTEXT7 (generic JSON-store libs), and WEB
+// (victor-software-house/task-tracker-plugin and Claude Code's native task manager both
+// persist tasks and survive compaction, but neither distills tasks from chat, none is a
+// zero-runtime-dependency library, and none fits the active/history + git-root shape here).
+// The generic persistence is a solved pattern; this store is the thin, dependency-free,
+// domain-specific piece the value layer (distil + remind + unlazy) sits on.
+//
+// Two files, mirroring the harness-sdd model:
+//   active.json   { tasks: [ {id, title, description, status, size, createdAt, messages[]} ] }
+//   history.json  { tasks: [ ...same shape + closedAt + closeReason ] }  — append-only
+// A task is never deleted: done and abandoned tasks MOVE from active to history, so the
+// record of what was decided (and dropped) is never lost.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const TASKS_DIR = join('.ai', 'tasks');
+const ACTIVE_FILE = 'active.json';
+const HISTORY_FILE = 'history.json';
+const COUNTER_FILE = 'counter.json';
+const JSON_INDENT = 2;
+// A project root holds `.git` or `.ai/` — the same set the CLI and the gates config use, so
+// a repo-less project (no git yet) still resolves. Anchoring on `.git` alone drops it.
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+
+/** Statuses a task can hold. Active: open/blocked. Terminal (moved to history): done/abandoned. */
+export const STATUS = Object.freeze({
+  OPEN: 'open',
+  BLOCKED: 'blocked',
+  DONE: 'done',
+  ABANDONED: 'abandoned',
+});
+
+const TERMINAL_STATUSES = new Set([STATUS.DONE, STATUS.ABANDONED]);
+
+/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
+export function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readCollection(path) {
+  if (!existsSync(path)) return { tasks: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return Array.isArray(parsed.tasks) ? parsed : { tasks: [] };
+  } catch {
+    return { tasks: [] };
+  }
+}
+
+function writeCollection(path, collection) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    `${JSON.stringify(collection, null, JSON_INDENT)}\n`,
+    'utf8',
+  );
+}
+
+/**
+ * Opens the store rooted at a project. All paths derive from the project root's .ai/tasks/.
+ * Returns a handle with read/mutate operations; each mutation persists immediately so a
+ * crash between calls never loses a recorded task. Null when there is no project (no .git).
+ */
+export function openTaskStore(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  if (!root) return null;
+
+  const directory = join(root, TASKS_DIR);
+  const activePath = join(directory, ACTIVE_FILE);
+  const historyPath = join(directory, HISTORY_FILE);
+  const counterPath = join(directory, COUNTER_FILE);
+
+  return {
+    root,
+    /** Open (non-terminal) tasks. */
+    active() {
+      return readCollection(activePath).tasks;
+    },
+    /** Terminal (done/abandoned) tasks, newest last. */
+    history() {
+      return readCollection(historyPath).tasks;
+    },
+    /** Adds a task to active and returns it. `id` is caller-supplied (stable, human-readable). */
+    add(task) {
+      const collection = readCollection(activePath);
+      collection.tasks.push(task);
+      writeCollection(activePath, collection);
+      return task;
+    },
+    /** Merges fields into the active task with matching id. Null if not found. */
+    update(id, fields) {
+      const collection = readCollection(activePath);
+      const task = collection.tasks.find((entry) => entry.id === id);
+      if (!task) return null;
+      Object.assign(task, fields);
+      writeCollection(activePath, collection);
+      return task;
+    },
+    /**
+     * Closes an active task: sets a terminal status + closedAt + closeReason, then MOVES it
+     * from active to history (append-only). Nothing is deleted. Returns the closed task, or
+     * null when the id or status is invalid.
+     */
+    close(id, status, reason) {
+      if (!TERMINAL_STATUSES.has(status)) return null;
+      const activeCollection = readCollection(activePath);
+      const index = activeCollection.tasks.findIndex(
+        (entry) => entry.id === id,
+      );
+      if (index === -1) return null;
+
+      const [task] = activeCollection.tasks.splice(index, 1);
+      task.status = status;
+      task.closedAt = new Date().toISOString();
+      task.closeReason = reason ?? '';
+
+      const historyCollection = readCollection(historyPath);
+      historyCollection.tasks.push(task);
+
+      writeCollection(historyPath, historyCollection);
+      writeCollection(activePath, activeCollection);
+      return task;
+    },
+    /** The message counter since the last reminder (0 when unset or unreadable). */
+    counter() {
+      if (!existsSync(counterPath)) return 0;
+      try {
+        return JSON.parse(readFileSync(counterPath, 'utf8')).count ?? 0;
+      } catch {
+        return 0;
+      }
+    },
+    /** Sets the message counter. */
+    setCounter(count) {
+      mkdirSync(directory, { recursive: true });
+      writeFileSync(
+        counterPath,
+        `${JSON.stringify({ count }, null, JSON_INDENT)}\n`,
+        'utf8',
+      );
+    },
+  };
+}