@agent-flow-board/bridge 0.2.0 → 0.4.0

package/dist/checks/importlegacy.js

@@ -0,0 +1,300 @@
+// `check import-legacy --from <afb-checks folder> --org <slug> [--dry-run] [--json]`: MOVES THE SETUP OF THE STANDALONE afb-checks TOOL INTO THE BRIDGE, READ ONLY ON THE OLD FOLDER.
+// It reads ONLY <from>/data/projects/<org>/*.json (the project definitions: repo, appDir, boardProject, recipe, url, extraHosts) and the check scripts
+// <from>/checks/<org>/<item>/<key>.mjs. It never lists or reads anything else under the old folder: no profiles, no secrets, no keys, no sign-ins.
+// Each project is registered again through registry.ts with adoption OFF and no pin; a repo registration is made only when its folder is inside an owner-approved
+// root (otherwise it is listed with the exact command the owner needs). Each script is checked with lintCheck and copied unchanged (headers kept) into the scripts
+// folder; a script that fails the lint is not copied, and one that differs from an existing script is a conflict and is left as it is.
+// -- DEP-MODULES -- //
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+// -- MODULES -- //
+import { Refusal, UsageError } from './approve.js';
+import { appendAudit } from './audit.js';
+import { checkRepoFolder } from './guardrails.js';
+import { lintCheck } from './guard.js';
+import { NAME, ORG_SLUG, scriptPath } from './paths.js';
+import { PROJECT_KEY, REGISTRATION_NAME, findRegistration, registerProject } from './registry.js';
+import { rootHolding } from './roots.js';
+// -- CONSTANTS -- //
+/** A script larger than this is not a check. */
+const MAX_SCRIPT_BYTES = 1_000_000;
+const MAX_PROJECT_BYTES = 200_000;
+// -- FUNCTIONS: SMALL HELPERS -- //
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => (typeof v === 'string' && v ? v : undefined);
+/** A plain file (not a link) as bytes, or null. Refuses anything larger than `max`. */
+function readPlain(file, max) {
+    try {
+        const st = lstatSync(file);
+        if (!st.isFile() || st.size > max)
+            return null;
+        return readFileSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** The names in a folder that pass `ok`, sorted. A folder that is a link is not entered. */
+function listNames(dir, ok) {
+    try {
+        if (lstatSync(dir).isSymbolicLink())
+            return [];
+        return readdirSync(dir).filter(ok).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function parseProject(raw) {
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw.toString('utf8'));
+        if (!isRecord(v))
+            return null;
+        return {
+            repo: text(v.repo),
+            appDir: text(v.appDir),
+            boardProject: text(v.boardProject),
+            recipe: v.recipe === true,
+            database: v.database,
+            url: text(v.url),
+            extraHosts: Array.isArray(v.extraHosts)
+                ? v.extraHosts.filter((h) => typeof h === 'string')
+                : undefined,
+            build: text(v.build),
+            start: text(v.start),
+            ready: text(v.ready)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// -- FUNCTIONS: PROJECTS -- //
+function importProject(org, name, old, dryRun) {
+    const skip = (reason, next) => ({
+        kind: 'skipped',
+        skip: { name, reason, ...(next ? { next } : {}) }
+    });
+    const boardProject = old.boardProject ?? name;
+    if (!PROJECT_KEY.test(boardProject))
+        return skip(`its board project "${boardProject.slice(0, 20)}" is not a project key`);
+    const existing = findRegistration(org, name);
+    if (existing)
+        return { kind: 'unchanged' };
+    // A live site needs the owner's code; it is never made here
+    if (old.url) {
+        const hosts = old.extraHosts?.length ? ` --extra-hosts ${old.extraHosts.join(',')}` : '';
+        return skip('a live site is registered only with a code from the owner', `check approve --request --action register --target ${name}, then check project ${name} --org ${org} --board-project ${boardProject} --url ${old.url}${hosts} --approval <code>`);
+    }
+    if (!old.repo)
+        return skip('the project file names neither a repo folder nor a live site');
+    const folder = resolve(old.repo);
+    if (!existsSync(folder))
+        return skip('its repo folder is not on this machine');
+    const root = rootHolding(folder);
+    if (!root) {
+        const parent = dirname(folder);
+        return skip('its repo folder is not inside a folder the owner approved', `check approve --request --action roots --target "${parent}", then check roots add "${parent}" --approval <code>, then import again`);
+    }
+    const input = {
+        org,
+        name,
+        boardProject,
+        repo: folder,
+        ...(old.appDir ? { appDir: old.appDir } : {}),
+        recipe: old.recipe === true,
+        adoptEnv: false,
+        uploadSignedInPictures: false
+    };
+    if (dryRun) {
+        const problem = checkRepoFolder(old.appDir ? join(folder, old.appDir) : folder);
+        return problem ? skip(problem) : { kind: 'registered' };
+    }
+    try {
+        registerProject(input);
+        return { kind: 'registered' };
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            return skip(e.message);
+        throw e;
+    }
+}
+// -- FUNCTIONS: SCRIPTS -- //
+function importScripts(from, org, dryRun) {
+    const out = {
+        found: 0,
+        copied: 0,
+        same: 0,
+        conflicts: [],
+        rejected: []
+    };
+    const base = join(from, 'checks', org);
+    for (const item of listNames(base, (n) => NAME.test(n))) {
+        const itemDir = join(base, item);
+        for (const file of listNames(itemDir, (n) => n.endsWith('.mjs'))) {
+            const key = file.slice(0, -'.mjs'.length);
+            if (!NAME.test(key))
+                continue;
+            const bytes = readPlain(join(itemDir, file), MAX_SCRIPT_BYTES);
+            if (!bytes)
+                continue;
+            out.found++;
+            const reasons = lintCheck(bytes.toString('utf8'));
+            if (reasons.length) {
+                out.rejected.push({ item, key, reasons });
+                continue;
+            }
+            const target = scriptPath(org, item, key);
+            if (existsSync(target)) {
+                const have = readPlain(target, MAX_SCRIPT_BYTES);
+                if (have && have.equals(bytes))
+                    out.same++;
+                else
+                    out.conflicts.push(`${item}/${key}`);
+                continue;
+            }
+            if (!dryRun) {
+                mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+                // 'wx': never replaces a script that appeared in the meantime
+                try {
+                    writeFileSync(target, bytes, { mode: 0o600, flag: 'wx' });
+                }
+                catch (e) {
+                    if (e.code === 'EEXIST') {
+                        out.conflicts.push(`${item}/${key}`);
+                        continue;
+                    }
+                    throw e;
+                }
+            }
+            out.copied++;
+        }
+    }
+    return out;
+}
+// -- FUNCTIONS: THE IMPORT -- //
+/** Reads the old folder (project files and scripts only) and brings both into the bridge. Throws a Refusal or UsageError for input it cannot use. */
+export function importLegacy(opts) {
+    const dryRun = opts.dryRun === true;
+    const org = opts.org;
+    if (!ORG_SLUG.test(org))
+        throw new UsageError('--org takes an organisation slug.');
+    const from = resolve(opts.from);
+    try {
+        if (!lstatSync(from).isDirectory())
+            throw new Error('not a folder');
+    }
+    catch {
+        throw new Refusal(`${basename(from)} is not a folder that exists.`);
+    }
+    const projectsDir = join(from, 'data', 'projects', org);
+    const names = listNames(projectsDir, (n) => n.endsWith('.json')).map((n) => n.slice(0, -5));
+    const projects = {
+        found: 0,
+        registered: [],
+        unchanged: [],
+        skipped: []
+    };
+    const notes = [];
+    for (const name of names) {
+        projects.found++;
+        if (!REGISTRATION_NAME.test(name)) {
+            projects.skipped.push({
+                name: name.slice(0, 40),
+                reason: 'its name is not a registration name'
+            });
+            continue;
+        }
+        const old = parseProject(readPlain(join(projectsDir, `${name}.json`), MAX_PROJECT_BYTES));
+        if (!old) {
+            projects.skipped.push({ name, reason: 'its project file cannot be read' });
+            continue;
+        }
+        if (!old.recipe && (old.build || old.start))
+            notes.push(`${name}: the old build and start commands are not copied; the bridge reads the package scripts or a recipe (.afb-checks.json).`);
+        const r = importProject(org, name, old, dryRun);
+        if (r.kind === 'skipped')
+            projects.skipped.push(r.skip);
+        else if (r.kind === 'registered')
+            projects.registered.push(name);
+        else
+            projects.unchanged.push(name);
+    }
+    const scripts = importScripts(from, org, dryRun);
+    const todo = [];
+    for (const s of projects.skipped)
+        if (s.next)
+            todo.push(`${s.name}: ${s.next}`);
+    if (projects.registered.length || projects.unchanged.length) {
+        todo.push(`Secrets are not moved (they are sealed with the old key). Import them again with an approval code: ${[...projects.registered, ...projects.unchanged].map((n) => `check approve --request --action secrets --target ${n}`).join('; ')}, then check secrets import ... --approval <code>.`);
+        todo.push(`Make the sign-ins again: ${[...projects.registered, ...projects.unchanged].map((n) => `check login ${n} --org ${org}`).join('; ')}.`);
+    }
+    if (scripts.conflicts.length)
+        todo.push('Compare the conflicting scripts with the ones in the bridge scripts folder and keep the right one by hand; nothing was overwritten.');
+    todo.push('When the bridge has taken over, stop the old worker and its service (the owner does this).');
+    const summary = {
+        ok: !projects.skipped.length && !scripts.conflicts.length && !scripts.rejected.length,
+        dryRun,
+        org,
+        projects,
+        scripts,
+        notes,
+        todo
+    };
+    if (!dryRun)
+        appendAudit('import-legacy', {
+            org,
+            projects: projects.found,
+            registered: projects.registered.length,
+            skipped: projects.skipped.length,
+            scripts: scripts.found,
+            copied: scripts.copied,
+            conflicts: scripts.conflicts.length,
+            rejected: scripts.rejected.length
+        });
+    return summary;
+}
+/** `check import-legacy --from <folder> --org <slug> [--dry-run] [--json]`. Exit 0 all imported, 1 something was skipped or needs the owner, 2 could not run. */
+export async function importLegacyCommand(args, ctx) {
+    const json = ctx.json ?? args.includes('--json');
+    const list = args[0] === 'import-legacy' ? args.slice(1) : args;
+    const flag = (name) => {
+        const i = list.indexOf(name);
+        const v = i >= 0 ? list[i + 1] : undefined;
+        return v === undefined || v.startsWith('--') ? undefined : v;
+    };
+    try {
+        const from = flag('--from');
+        const org = flag('--org');
+        if (!from || !org)
+            throw new UsageError('Usage: agent-flow-board check import-legacy --from <afb-checks folder> --org <slug> [--dry-run] [--json]');
+        const s = importLegacy({ from, org, dryRun: list.includes('--dry-run') });
+        if (json)
+            ctx.out(JSON.stringify(s));
+        else {
+            ctx.log(`${s.dryRun ? 'Would import' : 'Imported'} for ${s.org}: ${s.projects.registered.length} of ${s.projects.found} project(s) registered (${s.projects.unchanged.length} already there), ${s.scripts.copied} of ${s.scripts.found} script(s) copied (${s.scripts.same} already the same).`);
+            for (const p of s.projects.skipped)
+                ctx.log(`Skipped ${p.name}: ${p.reason}.${p.next ? ` Needs: ${p.next}` : ''}`);
+            for (const c of s.scripts.conflicts)
+                ctx.log(`Conflict (left as it is): ${c}`);
+            for (const r of s.scripts.rejected)
+                ctx.log(`Not copied ${r.item}/${r.key}: ${r.reasons.join(', ')}`);
+            for (const n of s.notes)
+                ctx.log(`Note: ${n}`);
+            for (const t of s.todo)
+                ctx.log(`To do (owner): ${t}`);
+        }
+        return s.ok ? 0 : 1;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (json)
+            ctx.out(JSON.stringify({ ok: false, event: 'error', error: message }));
+        else
+            ctx.log(message);
+        return e instanceof Refusal ? 1 : 2;
+    }
+}

package/dist/checks/install.js

@@ -0,0 +1,150 @@
+// THE INSTALL OF A PRIVATE COPY: WHICH COMMAND, WHETHER IT MAY BE CACHED, AND HOW A PACKAGE MANAGER IS STARTED ON WINDOWS.
+// The commands are constants: nothing in the repo can change them. They install exactly what the lock file says and, where the package manager
+// allows it, with the package scripts switched off (a postinstall script would run a program the agent wrote).
+// -- DEP-MODULES -- //
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+// -- CONSTANTS -- //
+/** The programs that are .cmd shims on Windows. */
+const SHIMMED = /^(yarn|npm|pnpm|npx)$/;
+/** The files an install depends on. */
+const LOCK_INPUTS = [
+    'yarn.lock',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+    '.pnpmfile.cjs',
+    '.yarnrc.yml'
+];
+// -- FUNCTIONS -- //
+const has = (dir, file) => existsSync(join(dir, file));
+/** Which package manager the lock file in `dir` names, or null when there is none (a frozen install needs one) or no package.json. */
+export function packageManagerOf(dir) {
+    if (!has(dir, 'package.json'))
+        return null;
+    if (has(dir, 'yarn.lock'))
+        return 'yarn';
+    if (has(dir, 'package-lock.json'))
+        return 'npm';
+    if (has(dir, 'pnpm-lock.yaml'))
+        return 'pnpm';
+    return null;
+}
+/**
+ * The frozen install command for `dir`, or null when it has no lock file. Yarn with a .yarnrc.yml is Yarn 4, whose own `--immutable` is the frozen
+ * form; the others get --ignore-scripts.
+ */
+export function installCommand(dir) {
+    switch (packageManagerOf(dir)) {
+        case 'yarn':
+            return has(dir, '.yarnrc.yml')
+                ? ['yarn', 'install', '--immutable']
+                : ['yarn', 'install', '--frozen-lockfile', '--ignore-scripts'];
+        case 'npm':
+            return ['npm', 'ci', '--ignore-scripts'];
+        case 'pnpm':
+            return ['pnpm', 'install', '--frozen-lockfile', '--ignore-scripts'];
+        default:
+            return null;
+    }
+}
+/**
+ * True when the finished install of `dir` may be kept and copied into another folder. A pnpm install never is: pnpm writes the absolute path of its
+ * store into node_modules/.modules.yaml, and its links point into that store, so a copy in another folder is refused by the next pnpm run.
+ */
+export function installCacheable(dir) {
+    const manager = packageManagerOf(dir);
+    if (!manager || manager === 'pnpm')
+        return false;
+    // A node_modules that pnpm made is never cached whatever lock file sits beside it
+    if (has(dir, join('node_modules', '.modules.yaml')) || has(dir, '.modules.yaml'))
+        return false;
+    return true;
+}
+/** A hash of the files an install depends on: what the installed dependencies depend on. */
+export function lockHash(dir) {
+    const h = createHash('sha1');
+    for (const f of LOCK_INPUTS)
+        if (has(dir, f))
+            h.update(f).update(readFileSync(join(dir, f)));
+    return h.digest('hex');
+}
+/** The first file on PATH named `name` with one of the executable extensions, or null. Case-insensitive on Windows. */
+export function findOnPath(name, pathEnv, exts, exists = existsSync) {
+    for (const dir of pathEnv.split(delimiter).filter(Boolean))
+        for (const ext of exts) {
+            const file = join(dir, name + ext);
+            if (exists(file))
+                return file;
+        }
+    return null;
+}
+/**
+ * What to start for a command. On Windows yarn, npm and pnpm are usually .cmd shims, which a plain spawn cannot find and Node refuses to start
+ * directly (EINVAL): they go through `cmd.exe /d /s /c name.cmd`, unless a real .exe of that name is first on PATH. The arguments came from a command
+ * that was already checked (words, flags and a port, no shell characters), so cmd.exe has nothing to interpret. Elsewhere the argv is unchanged.
+ */
+export function programArgv(argv, opts = {}) {
+    const [file, ...args] = argv;
+    if (!file || (opts.platform ?? process.platform) !== 'win32' || !SHIMMED.test(file))
+        return argv;
+    const found = findOnPath(file, opts.pathEnv ?? '', ['.exe', '.cmd', '.bat'], opts.exists);
+    if (found && found.toLowerCase().endsWith('.exe'))
+        return [found, ...args];
+    return ['cmd.exe', '/d', '/s', '/c', `${file}.cmd`, ...args];
+}
+/** The PATH of an environment object, whatever its case (Windows calls it Path). */
+export function pathOf(env) {
+    for (const k of Object.keys(env))
+        if (k.toLowerCase() === 'path')
+            return env[k] ?? '';
+    return '';
+}
+/**
+ * The folder an install runs in: `appCwd` when it holds a lock file, else the nearest folder above it, up to `stopAt` (the root of the private copy), that does.
+ * A monorepo keeps one lock file at the top and the apps below it. Null when there is none, and the install is skipped.
+ */
+export function installDirFor(appCwd, stopAt) {
+    const top = resolve(stopAt);
+    let dir = resolve(appCwd);
+    for (let i = 0; i < 32; i++) {
+        if (packageManagerOf(dir))
+            return dir;
+        if (dir === top)
+            return null;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        // Never above the copy
+        const rel = relative(top, up);
+        if (rel.startsWith('..') || isAbsolute(rel))
+            return null;
+        dir = up;
+    }
+    return null;
+}
+/** How a version is asked for. A test replaces it. */
+export const versionIo = {
+    run: (argv, opts) => new Promise((resolveRun) => {
+        const [file, ...args] = programArgv(argv, { pathEnv: pathOf(opts.env) });
+        if (!file)
+            return resolveRun('');
+        execFile(file, args, { cwd: opts.cwd, env: opts.env, windowsHide: true, timeout: 30_000 }, (err, stdout) => resolveRun(err ? '' : (String(stdout).trim().split(/\r?\n/)[0] ?? '')));
+    })
+};
+const versions = new Map();
+/** The version of a package manager as `<pm> --version` prints it, asked once per process. An empty string when it cannot be asked (the cache key then differs from every real version). */
+export async function packageManagerVersion(pm, cwd, env = process.env) {
+    const known = versions.get(pm);
+    if (known !== undefined)
+        return known;
+    const version = (await versionIo.run([pm, '--version'], { cwd, env })).slice(0, 40);
+    // A failed ask is not remembered: the next run asks again
+    if (version)
+        versions.set(pm, version);
+    return version;
+}
+/** Forgets the versions asked so far (tests). */
+export const forgetPackageManagerVersions = () => versions.clear();

package/dist/checks/live.js

@@ -0,0 +1,76 @@
+// LIVE-SITE REGISTRATIONS: A REGISTRATION WITH A URL AND NO REPO. NOTHING IS BUILT OR STARTED; THE RUN IS UNVERIFIED AND NEVER WRITES.
+// This file only judges the settings (url and extraHosts) and hands the guard its options. Writes are never allowed on a live site: a check
+// there drives pages and reads, and the guard stops every POST, PUT, PATCH and DELETE.
+// -- MODULES -- //
+import { FORBIDDEN_PORTS } from './guardrails.js';
+// -- CONSTANTS -- //
+const MAX_EXTRA_HOSTS = 16;
+/** A plain DNS name: dot separated labels of letters, digits and dashes. No wildcard, port, path or underscore. */
+const HOST_NAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
+const LOCAL_HOSTS = new Set([
+    'localhost',
+    '127.0.0.1',
+    '[::1]',
+    '::1',
+    '0.0.0.0',
+    'host.docker.internal'
+]);
+// -- FUNCTIONS -- //
+const isLoopbackName = (h) => LOCAL_HOSTS.has(h) || h.endsWith('.localhost') || /^127\./.test(h) || h === '[::]';
+/** True for a dotted IPv4 address (also the short and number forms a browser accepts) or anything holding a colon (IPv6). */
+const isIpLiteral = (h) => h.includes(':') || h.startsWith('[') || /^[0-9.]+$/.test(h) || /^0x[0-9a-f]+$/i.test(h);
+/** One plain sentence per problem with the live-site settings. An empty list means they are acceptable. */
+export function liveSiteProblems(cfg) {
+    const problems = [];
+    if (cfg.url !== undefined) {
+        let u = null;
+        try {
+            u = new URL(String(cfg.url));
+        }
+        catch {
+            problems.push('The site address is not a web address.');
+        }
+        if (u) {
+            if (u.protocol !== 'http:' && u.protocol !== 'https:')
+                problems.push('The site address must start with http:// or https://.');
+            else {
+                if (u.username || u.password)
+                    problems.push('The site address may not hold a user name or password.');
+                const host = u.hostname.toLowerCase();
+                if (isLoopbackName(host)) {
+                    const port = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+                    if (FORBIDDEN_PORTS.has(port))
+                        problems.push(`The site address uses port ${port}, which a check never uses.`);
+                }
+            }
+        }
+    }
+    const extra = cfg.extraHosts ?? [];
+    if (!Array.isArray(extra))
+        return [...problems, 'The extra hosts must be a list of host names.'];
+    if (extra.length > MAX_EXTRA_HOSTS)
+        problems.push(`At most ${MAX_EXTRA_HOSTS} extra hosts are allowed.`);
+    for (const raw of extra) {
+        const h = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+        const shown = typeof raw === 'string' ? raw.slice(0, 60) : String(typeof raw);
+        if (!h || (!HOST_NAME.test(h) && !isIpLiteral(h)))
+            problems.push(`The extra host "${shown}" is not an exact host name (no wildcard, port, path or address).`);
+        else if (isIpLiteral(h))
+            problems.push(`The extra host "${shown}" is an IP address. Only host names are allowed.`);
+        else if (isLoopbackName(h))
+            problems.push(`The extra host "${shown}" is this machine, which is never an extra host.`);
+    }
+    return problems;
+}
+/** What the child's guard is given for a live site: writes never allowed, and only the exact extra hosts reachable besides the site. */
+export function liveSiteGuardOptions(cfg) {
+    const bad = liveSiteProblems(cfg);
+    if (bad.length)
+        throw new Error(bad[0]);
+    return {
+        allowWrites: false,
+        extraHosts: [...new Set((cfg.extraHosts ?? []).map((h) => h.trim().toLowerCase()))]
+    };
+}
+/** True when the settings describe a live site (a url and no repo to build). */
+export const isLiveSite = (cfg) => typeof cfg.url === 'string' && cfg.url !== '';

package/dist/checks/lock.js

@@ -7,12 +7,18 @@ import { randomBytes } from 'node:crypto';
 import { linkSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 // -- MODULES -- //
+import { renameRetry } from './fsretry.js';
 import { assertName, ensureDir, locksDir } from './paths.js';
 // -- CONSTANTS -- //
 /** A lock whose content cannot be read is only treated as stale after this long (it is created whole, so this means a damaged file). */
 const UNREADABLE_GRACE_MS = 2_000;
-/** For a lock that only a dead process may lose, such as the worker lock. */
+/** For a lock that only a dead process may lose. */
 export const NEVER_STALE_MS = Number.MAX_SAFE_INTEGER;
+/**
+ * The worker lock is lost by a dead process, and also by a heartbeat that stopped: a crashed worker whose process id was handed to another program would otherwise lock
+ * out `check watch` for ever. The worker touches its lock every few seconds (watch.ts), so this is long enough to survive a busy machine.
+ */
+export const WORKER_STALE_MS = 3 * 60_000;
 // -- FUNCTIONS -- //
 /** True when a process with this id exists (it may belong to another user, which still counts as alive). */
 export function pidAlive(pid) {
@@ -138,6 +144,24 @@ function makeLock(file, token) {
     let released = false;
     return {
         file,
+        touch() {
+            if (released)
+                return;
+            const text = readText(file);
+            const body = text === null ? null : parseBody(text);
+            if (!body || body.token !== token)
+                return;
+            const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+            try {
+                const next = { ...body, at: new Date().toISOString() };
+                writeFileSync(tmp, JSON.stringify(next) + '\n', { mode: 0o600 });
+                renameRetry(tmp, file);
+            }
+            catch {
+                // The next touch tries again
+                rmSync(tmp, { force: true });
+            }
+        },
         release() {
             if (released)
                 return;
@@ -175,9 +199,9 @@ export function lockHolderPid(name) {
     return body && pidAlive(body.pid) ? body.pid : null;
 }
 /**
- * The one-worker-per-machine lock of `check watch`. Only a dead process loses it (the work inside runs for hours), so the stale age is never reached.
- * Returns null when another worker holds it; the caller says so in one plain line.
+ * The one-worker-per-machine lock of `check watch`. A dead process loses it, and so does one whose heartbeat stopped for three minutes (a reused process id).
+ * The worker calls `touch()` on its lock regularly. Returns null when another worker holds it; the caller says so in one plain line.
  */
 export function machineLock(name) {
-    return acquireLock(`machine-${name}`, { staleMs: NEVER_STALE_MS });
+    return acquireLock(`machine-${name}`, { staleMs: WORKER_STALE_MS });
 }