@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/lock/lock.mjs

@@ -0,0 +1,202 @@
+// lock.mjs — shared per-resource process lock (public core API).
+//
+// Two runs of the same scheduled task on the same host MUST NOT overlap:
+// a second concurrent run consumes the same inputs (staging areas, work
+// queues) and produces duplicate effects and git races. This module is
+// the platform-wide primitive for "at most one of me at a time" —
+// consumed default-on by `pa launch`, adoptable by any direct-run tool.
+//
+// Implementation: a JSON PID file at a caller-chosen path. Contents:
+//   { "pid": 12345, "acquiredAt": "2026-07-06T12:00:00Z" }
+//
+// Staleness policy (two signals, in order):
+//   1. Dead PID — primary. If the recorded process no longer exists, the
+//      lock is stale regardless of age and is broken immediately.
+//   2. Age threshold — backstop. If the recorded process appears alive
+//      but the lock is older than `staleAfterMs`, it is broken anyway.
+//      This covers PID reuse (the recorded pid now names an unrelated
+//      process, so signal 1 reports "alive" forever) and hosts where
+//      process liveness cannot be determined reliably.
+//
+// Default threshold: 2 hours (DEFAULT_STALE_AFTER_MS). Rationale: the
+// motivating consumers are scheduled agent sweeps whose legitimate
+// runtimes are routinely tens of minutes (a supervised distillation
+// sweep has been observed at 1288+ seconds); a short window (e.g. the
+// 10 minutes the sync tool uses for its seconds-long git runs) would
+// steal a live lock mid-sweep. 2 hours safely clears observed long runs
+// while still self-healing a pid-reuse wedge within one-to-two ticks of
+// a typical 4-hourly schedule. Callers with faster, well-bounded jobs
+// SHOULD pass a tighter `staleAfterMs`; callers with longer legitimate
+// runtimes MUST raise it.
+//
+// Unreadable lock files: a lock file that exists but cannot be parsed
+// (crash mid-write, manual corruption) can never release itself and its
+// pid cannot be checked. It is treated as held until its file mtime
+// exceeds `staleAfterMs`, then broken. This keeps the age threshold as
+// the universal backstop: no lock state can wedge a schedule forever.
+//
+// Contention contract: `acquire` returns `{ acquired: false, reason }`
+// on live contention — it never throws for "someone else holds it".
+// Callers decide the exit semantics (the platform convention for cron
+// consumers is a logged skip + exit 0, matching sync's `noop-locked`).
+//
+// First-run path: neither the lock file nor its parent directory need
+// exist. A missing directory is created on demand (write → ENOENT →
+// mkdir -p → retry) so the empty state is the common case, not an error.
+//
+// Cross-platform: pure node stdlib. Liveness uses `process.kill(pid, 0)`
+// which works on Windows as well as POSIX; tests inject
+// `isProcessAlive` / `now` / `fs` so no real processes or clocks are
+// needed (tooling standard §8 — dependency injection over mocking).
+
+import { readFile, writeFile, unlink, stat, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export const DEFAULT_STALE_AFTER_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+/**
+ * Acquire a per-resource process lock.
+ *
+ * @param {string} lockPath  Absolute path of the lock file. Convention:
+ *   one path per protected resource (e.g. `.cache/launch/<taskId>.lock`).
+ * @param {object} [opts]
+ * @param {number} [opts.staleAfterMs]  Age past which a lock is broken
+ *   even if its pid looks alive. Default: DEFAULT_STALE_AFTER_MS (2 h).
+ * @param {() => number} [opts.now]  Clock seam for tests.
+ * @param {number} [opts.pid]  Owner pid recorded in the lock file.
+ * @param {(pid: number) => boolean} [opts.isProcessAlive]  Liveness seam.
+ * @param {object} [opts.fs]  fs seam ({ readFile, writeFile, unlink,
+ *   stat, mkdir }) for tests.
+ * @returns {Promise<
+ *   | { acquired: false, holder: { pid: number|null, acquiredAt: string|null }, reason: string }
+ *   | { acquired: true, record: { pid: number, acquiredAt: string },
+ *       stale: null | { pid: number|null, acquiredAt: string|null, reason: 'dead-pid'|'age-exceeded'|'unreadable' },
+ *       release: () => Promise<void> }
+ * >}
+ */
+export async function acquireLock(lockPath, {
+  staleAfterMs = DEFAULT_STALE_AFTER_MS,
+  now = () => Date.now(),
+  pid = process.pid,
+  isProcessAlive = defaultIsProcessAlive,
+  fs = defaultFs,
+} = {}) {
+  // Read the existing lock, if any.
+  let raw = null;
+  try {
+    raw = await fs.readFile(lockPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    // No lock file — proceed to acquire (the common first-run case).
+  }
+
+  let stale = null;
+  if (raw != null) {
+    let existing = null;
+    try {
+      existing = JSON.parse(raw);
+    } catch {
+      existing = null;
+    }
+
+    if (existing && Number.isFinite(existing.pid) && existing.acquiredAt) {
+      const ageMs = now() - new Date(existing.acquiredAt).getTime();
+      const alive = isProcessAlive(existing.pid);
+      if (alive && (!Number.isFinite(ageMs) || ageMs < staleAfterMs)) {
+        // Live lock — contention. (A non-finite age means a mangled
+        // timestamp; with a live pid we err on the side of holding.)
+        return {
+          acquired: false,
+          holder: { pid: existing.pid, acquiredAt: existing.acquiredAt },
+          reason: `held by pid ${existing.pid} since ${existing.acquiredAt}`,
+        };
+      }
+      stale = {
+        pid: existing.pid,
+        acquiredAt: existing.acquiredAt,
+        reason: alive ? 'age-exceeded' : 'dead-pid',
+      };
+    } else {
+      // Unparseable lock file — pid can't be checked, so the age
+      // threshold (via file mtime) is the only backstop.
+      let mtimeMs = null;
+      try {
+        mtimeMs = (await fs.stat(lockPath)).mtimeMs;
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+        // Vanished between read and stat — treat as absent.
+      }
+      if (mtimeMs != null && now() - mtimeMs < staleAfterMs) {
+        return {
+          acquired: false,
+          holder: { pid: null, acquiredAt: null },
+          reason: `unreadable lock file at ${lockPath} — treating as held until stale`,
+        };
+      }
+      if (mtimeMs != null) {
+        stale = { pid: null, acquiredAt: null, reason: 'unreadable' };
+      }
+    }
+  }
+
+  const record = {
+    pid,
+    acquiredAt: new Date(now()).toISOString().replace(/\.\d+Z$/, 'Z'),
+  };
+  await writeWithMkdir(fs, lockPath, JSON.stringify(record));
+
+  return {
+    acquired: true,
+    record,
+    stale,
+    async release() {
+      try {
+        // Defensive: only remove if it's still ours. A long-running run
+        // whose lock went stale and was stolen by a later run must not
+        // delete the later run's lock when it finally exits.
+        const currentRaw = await fs.readFile(lockPath, 'utf8');
+        const current = JSON.parse(currentRaw);
+        if (current.pid === pid && current.acquiredAt === record.acquiredAt) {
+          await fs.unlink(lockPath);
+        }
+      } catch (err) {
+        if (err && err.code === 'ENOENT') return;
+        if (err instanceof SyntaxError) return; // clobbered — not ours to delete
+        throw err;
+      }
+    },
+  };
+}
+
+async function writeWithMkdir(fs, lockPath, content) {
+  try {
+    await fs.writeFile(lockPath, content);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    // Parent directory missing — first run. Create it and retry once.
+    await fs.mkdir(dirname(lockPath), { recursive: true });
+    await fs.writeFile(lockPath, content);
+  }
+}
+
+function defaultIsProcessAlive(p) {
+  try {
+    // Signal 0 == "does this process exist and can we signal it?".
+    // Throws ESRCH if not. EPERM (someone else's process) also means
+    // alive — treated conservatively as alive.
+    process.kill(p, 0);
+    return true;
+  } catch (err) {
+    if (err.code === 'ESRCH') return false;
+    if (err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+const defaultFs = {
+  readFile,
+  writeFile,
+  unlink,
+  stat,
+  mkdir,
+};

package/dist/engineering-pa-core/src/memory-sync/cli-support.mjs

@@ -0,0 +1,12 @@
+// cli-support.mjs — tiny shared primitives for CLI layer.
+
+export class ExitError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.exitCode = code;
+  }
+}
+
+export function log(msg) {
+  process.stderr.write(`[memory-sync] ${msg}\n`);
+}

package/dist/engineering-pa-core/src/memory-sync/cli.mjs

@@ -0,0 +1,56 @@
+// cli.mjs — memory-sync command router.
+//
+// Preserves the pull/push verb contract from the shell implementation and
+// maps domain errors to the standard exit-code ladder (see README §Exit codes).
+
+import { pull } from './commands/pull.mjs';
+import { push } from './commands/push.mjs';
+import { ExitError, log } from './cli-support.mjs';
+
+const USAGE = `Usage: memory-sync <pull|push|--help>
+  pull         Mirror repo memory dir -> local Claude Code cache
+  push         Mirror local Claude Code cache -> repo memory dir
+  -h, --help   Show this help
+Exit codes: 0 ok, 1 usage, 2 source dir missing, 3 io failure`;
+
+export async function main(argv) {
+  const code = await run(argv);
+  process.exit(code ?? 0);
+}
+
+/**
+ * Exported for tests: returns an exit code rather than calling process.exit.
+ */
+export async function run(argv, opts = {}) {
+  const mode = argv[0];
+  if (mode === '-h' || mode === '--help' || mode === 'help') {
+    process.stdout.write(USAGE + '\n');
+    return 0;
+  }
+  if (mode == null || mode === '') {
+    process.stderr.write(USAGE + '\n');
+    return 1;
+  }
+  if (mode !== 'pull' && mode !== 'push') {
+    log(`unknown verb: ${mode}`);
+    process.stderr.write(USAGE + '\n');
+    return 1;
+  }
+  if (argv.length > 1) {
+    log(`unexpected arguments: ${argv.slice(1).join(' ')}`);
+    process.stderr.write(USAGE + '\n');
+    return 1;
+  }
+
+  try {
+    if (mode === 'pull') return await pull(opts);
+    return await push(opts);
+  } catch (err) {
+    if (err instanceof ExitError) {
+      log(err.message);
+      return err.exitCode;
+    }
+    log(`internal error: ${err.message || err}`);
+    return 3;
+  }
+}

package/dist/engineering-pa-core/src/memory-sync/commands/pull.mjs

@@ -0,0 +1,44 @@
+// commands/pull.mjs — mirror repo memory dir -> local Claude Code cache.
+
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findRepoRoot, cacheDirFor } from '../repo.mjs';
+import { mirror } from '../mirror.mjs';
+import { ExitError, log } from '../cli-support.mjs';
+
+async function isDir(p) {
+  try {
+    const s = await stat(p);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function pull({ cwd = process.cwd() } = {}) {
+  const { root, worktree } = await findRepoRoot(cwd);
+  if (!root) throw new ExitError('not inside a git repo', 2);
+  if (worktree) {
+    log('in a git worktree — skipping pull');
+    return 0;
+  }
+
+  const repoDir = join(root, 'operator', 'memory');
+  const cacheDir = cacheDirFor(root);
+
+  if (!(await isDir(repoDir))) {
+    throw new ExitError(`repo memory dir missing: ${repoDir}`, 2);
+  }
+  if (!(await isDir(cacheDir))) {
+    throw new ExitError(`local cache missing: ${cacheDir}`, 2);
+  }
+
+  let n;
+  try {
+    n = await mirror(repoDir, cacheDir);
+  } catch (err) {
+    throw new ExitError(`mirror failed: ${err.message || err}`, 3);
+  }
+  log(`pull: ${n} files mirrored from repo to cache`);
+  return 0;
+}

package/dist/engineering-pa-core/src/memory-sync/commands/push.mjs

@@ -0,0 +1,46 @@
+// commands/push.mjs — mirror local Claude Code cache -> repo memory dir.
+
+import { mkdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findRepoRoot, cacheDirFor } from '../repo.mjs';
+import { mirror } from '../mirror.mjs';
+import { ExitError, log } from '../cli-support.mjs';
+
+async function isDir(p) {
+  try {
+    const s = await stat(p);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function push({ cwd = process.cwd() } = {}) {
+  const { root, worktree } = await findRepoRoot(cwd);
+  if (!root) throw new ExitError('not inside a git repo', 2);
+  if (worktree) {
+    log('in a git worktree — skipping push');
+    return 0;
+  }
+
+  const repoDir = join(root, 'operator', 'memory');
+  const cacheDir = cacheDirFor(root);
+
+  if (!(await isDir(cacheDir))) {
+    throw new ExitError(`local cache missing: ${cacheDir}`, 2);
+  }
+  try {
+    await mkdir(repoDir, { recursive: true });
+  } catch (err) {
+    throw new ExitError(`cannot create repo memory dir: ${err.message || err}`, 3);
+  }
+
+  let n;
+  try {
+    n = await mirror(cacheDir, repoDir);
+  } catch (err) {
+    throw new ExitError(`mirror failed: ${err.message || err}`, 3);
+  }
+  log(`push: ${n} files mirrored from cache to repo`);
+  return 0;
+}

package/dist/engineering-pa-core/src/memory-sync/mirror.mjs

@@ -0,0 +1,114 @@
+// mirror.mjs — recursive directory mirror with deletion semantics.
+//
+// This is the single chokepoint for filesystem mutation in the tool.
+// `mirror(src, dst)` makes `dst` a byte-for-byte copy of `src`:
+//
+//   1. every regular file under `src` is copied to `dst` (mkdir -p as needed),
+//      preserving mtime where possible
+//   2. every file under `dst` that does not exist under `src` is removed
+//   3. empty directories under `dst` left behind after deletions are pruned
+//
+// Errors in this module map to the tool's exit code 3 (IO failure). The
+// caller is responsible for verifying `src` exists — that is a different
+// class of failure (exit 2) and lives in the command layer.
+
+import { mkdir, readdir, copyFile, stat, utimes, rm, rmdir } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+
+/**
+ * Recursively list every regular file under `root`, returning paths relative
+ * to `root` (always using forward slashes for stable comparison).
+ */
+async function listFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    for (const ent of entries) {
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        await walk(full);
+      } else if (ent.isFile()) {
+        out.push(relative(root, full).split('\\').join('/'));
+      }
+      // symlinks / sockets / etc. are intentionally skipped — matches the
+      // shell implementation which used `find -type f`
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+/**
+ * Remove empty directories under `root` from the bottom up. The `root`
+ * itself is never removed.
+ */
+async function pruneEmptyDirs(root) {
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) await walk(join(dir, ent.name));
+    }
+    if (dir === root) return;
+    try {
+      const remaining = await readdir(dir);
+      if (remaining.length === 0) await rmdir(dir);
+    } catch (err) {
+      if (err.code !== 'ENOENT' && err.code !== 'ENOTEMPTY') throw err;
+    }
+  }
+  await walk(root);
+}
+
+/**
+ * Mirror src -> dst. See module header for full semantics.
+ * Returns the number of files present in `dst` after the mirror completes
+ * (which equals the count of files in `src`).
+ */
+export async function mirror(src, dst) {
+  await mkdir(dst, { recursive: true });
+
+  const srcFiles = await listFiles(src);
+  const srcSet = new Set(srcFiles);
+
+  // Copy everything from src to dst. We copy unconditionally rather than
+  // comparing mtimes: the source wins, full stop. This matches `rsync -a
+  // --delete` behaviour the shell version used.
+  for (const rel of srcFiles) {
+    const from = join(src, rel);
+    const to = join(dst, rel);
+    await mkdir(dirname(to), { recursive: true });
+    await copyFile(from, to);
+    // Preserve mtime and atime from source so tooling that relies on
+    // timestamps (rsync's -a behaviour) stays consistent.
+    try {
+      const s = await stat(from);
+      await utimes(to, s.atime, s.mtime);
+    } catch {
+      // utimes can fail on some filesystems; not fatal.
+    }
+  }
+
+  // Delete anything in dst that isn't in src.
+  const dstFiles = await listFiles(dst);
+  for (const rel of dstFiles) {
+    if (!srcSet.has(rel)) {
+      await rm(join(dst, rel), { force: true });
+    }
+  }
+
+  await pruneEmptyDirs(dst);
+
+  return srcFiles.length;
+}

package/dist/engineering-pa-core/src/memory-sync/repo.mjs

@@ -0,0 +1,65 @@
+// repo.mjs — repo root discovery and cache-dir derivation.
+//
+// Pure helpers, no I/O side effects beyond `stat`-class lookups. Mirrors the
+// semantics of the original sync.sh:
+//
+//   - findRepoRoot() walks up from a start dir looking for a `.git` directory.
+//     If it finds a `.git` *file* first (i.e. this is a worktree), it reports
+//     that via the `worktree` flag so the caller can skip cleanly.
+//   - cacheDirFor(repo) sanitises the repo path by replacing '/' with '-' and
+//     composes `$HOME/.claude/projects/<sanitised>/memory`. This matches the
+//     path Claude Code itself uses for its per-project memory cache.
+
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch {
+    return 'missing';
+  }
+}
+
+/**
+ * Walk up from `start` looking for a `.git` entry.
+ *
+ * Returns `{ root, worktree }` where:
+ *   - `root` is the directory containing the `.git` entry (or null if none)
+ *   - `worktree` is true when the `.git` entry is a regular file (git worktree)
+ *     and false when it is a directory (primary checkout)
+ *
+ * If nothing is found before the filesystem root, returns `{ root: null, worktree: false }`.
+ */
+export async function findRepoRoot(start) {
+  let d = start;
+  // Guard against infinite loops on malformed paths
+  while (d && d !== dirname(d)) {
+    const gitPath = join(d, '.git');
+    const kind = await pathKind(gitPath);
+    if (kind === 'dir') return { root: d, worktree: false };
+    if (kind === 'file') return { root: d, worktree: true };
+    d = dirname(d);
+  }
+  return { root: null, worktree: false };
+}
+
+/**
+ * Given a repository absolute path, return the path of the Claude Code
+ * per-project memory cache directory for that repo.
+ *
+ * The cache lives under `$HOME/.claude/projects/<sanitised>/memory` where
+ * `<sanitised>` is the repo path with every '/' (or platform separator)
+ * replaced by '-'. This matches Claude Code's own sanitisation.
+ */
+export function cacheDirFor(repoPath, { home = homedir() } = {}) {
+  // Sanitise both '/' and '\\' to '-' so we produce a stable key regardless
+  // of the host platform's path-separator conventions. Claude Code itself
+  // uses this sanitisation to namespace per-project caches.
+  const sanitised = repoPath.replace(/[\\/]/g, '-');
+  return join(home, '.claude', 'projects', sanitised, 'memory');
+}

package/dist/engineering-pa-core/src/scheduler/detect.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * detect.mjs -- Detect available scheduling backends
+ *
+ * Outputs a JSON report of OS type and available scheduling facilities.
+ * Used by the PA to determine which backend to offer during setup.
+ *
+ * Usage: node node_modules/@stravica-ai/engineering-pa-core/src/scheduler/detect.mjs
+ */
+
+import { execSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Check whether a command exists on this system.
+ * @param {string} cmd
+ * @returns {boolean}
+ */
+function commandExists(cmd) {
+  try {
+    const check = process.platform === 'win32'
+      ? `where ${cmd} 2>nul`
+      : `command -v ${cmd} 2>/dev/null`;
+    execSync(check, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect OS and available scheduling backends.
+ * @returns {{ os: string, available: Array<{ backend: string, recommended: boolean, notes: string }> }}
+ */
+export function detect() {
+  const os = process.platform === 'darwin' ? 'darwin'
+    : process.platform === 'linux' ? 'linux'
+    : process.platform === 'win32' ? 'win32'
+    : 'unknown';
+
+  const available = [];
+  let hasSystemd = false;
+
+  // launchd (macOS only)
+  if (os === 'darwin' && commandExists('launchctl')) {
+    available.push({ backend: 'launchd', recommended: true, notes: 'Native macOS, survives reboots' });
+  }
+
+  // systemd (Linux only)
+  if (os === 'linux' && commandExists('systemctl')) {
+    try {
+      execSync('systemctl --user status', { stdio: 'pipe' });
+      available.push({ backend: 'systemd', recommended: true, notes: 'Native Linux, survives reboots' });
+      hasSystemd = true;
+    } catch {
+      // systemctl exists but user-level not available — skip
+    }
+  }
+
+  // cron (macOS and Linux)
+  if (commandExists('crontab')) {
+    if (os === 'darwin') {
+      available.push({ backend: 'cron', recommended: false, notes: 'Available but launchd preferred on macOS' });
+    } else if (os === 'linux') {
+      if (hasSystemd) {
+        available.push({ backend: 'cron', recommended: false, notes: 'Available but systemd preferred on Linux' });
+      } else {
+        available.push({ backend: 'cron', recommended: true, notes: 'Classic scheduler, widely available' });
+      }
+    }
+  }
+
+  // schtasks (Windows)
+  if (os === 'win32' && commandExists('schtasks.exe')) {
+    available.push({ backend: 'schtasks', recommended: true, notes: 'Native Windows Task Scheduler' });
+  }
+
+  // Docker (any OS)
+  if (commandExists('docker')) {
+    try {
+      execSync('docker info', { stdio: 'pipe' });
+      available.push({ backend: 'docker', recommended: false, notes: 'Docker detected and running' });
+    } catch {
+      // docker exists but daemon not running
+    }
+  }
+
+  return { os, available };
+}
+
+// ── CLI entry point ──────────────────────────────────────────────────
+//
+// BUG 3 fix — see install.mjs for the full rationale: realpath both sides
+// instead of the previous realpath-vs-symlink endsWith comparison, which
+// silently no-op'd under pnpm.
+
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectlyInvoked()) {
+  const result = detect();
+  process.stdout.write(JSON.stringify(result) + '\n');
+}

package/dist/engineering-pa-core/src/scheduler/host.mjs

@@ -0,0 +1,38 @@
+/**
+ * host.mjs -- shared hostname normalisation + matching for schedule host
+ * enforcement.
+ *
+ * Same short-name-before-first-dot algorithm used by the estate's
+ * device-resolution tooling (operator/extensions/tools/library-sync's
+ * resolveDeviceId) — kept deliberately simple and dependency-free so this
+ * module has zero coupling to the registry data model: schedule host
+ * enforcement only needs "does this string match the current machine",
+ * not "which registry device am I".
+ */
+
+import { hostname as osHostname } from 'node:os';
+
+/** The portion of a hostname before its first "." — case preserved. */
+export function shortHost(h) {
+  if (typeof h !== 'string' || h.length === 0) return '';
+  return h.split('.')[0];
+}
+
+/**
+ * Does `scheduleHost` (a schedule's declared `host` field) match the
+ * current machine? Absent/empty `scheduleHost` is treated as "no
+ * constraint declared" -> always matches (callers surface that as a
+ * warning, not a refusal — see evaluateHostGate in install.mjs).
+ *
+ * Match order: exact string equality, then short-name-before-first-dot
+ * equality (so `smarthome01` matches `smarthome01.local` and vice versa).
+ *
+ * @param {string|null|undefined} scheduleHost
+ * @param {string} [currentHost] - defaults to the real os.hostname()
+ * @returns {boolean}
+ */
+export function hostMatches(scheduleHost, currentHost = osHostname()) {
+  if (scheduleHost == null || scheduleHost === '') return true;
+  if (scheduleHost === currentHost) return true;
+  return shortHost(scheduleHost) === shortHost(currentHost);
+}