@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/daemon.js

@@ -0,0 +1,707 @@
+// Phase 10's background watcher (`smith daemon`). It closes the one gap the
+// roadmap still names: knowing what the factory needs required an operator to
+// keep a session open and re-run `smith status` by hand.
+//
+// What it is NOT is the more tempting thing. This daemon never dispatches an
+// agent, never merges, never writes to a worktree; scheduler.ts says why in
+// its own words ("Never dispatches an agent itself — architecture §12"), and a
+// process that survives the operator's terminal is the last place to relax
+// that. Its whole output is a list of findings and one refreshed projection.
+//
+// Everything it reports is derived from the event log by folds this repo
+// already owns — budgetAlarm.ts for spend, agents-registry.ts for stalls,
+// scheduler.ts for work that is due. Nothing here re-derives them, so the
+// daemon and `smith status` can never disagree.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_STALE_HOURS, detectStale, foldAgents, } from './agents-registry.js';
+import { admitProposals, } from './autonomy.js';
+import { checkBudgetAlarm } from './budgetAlarm.js';
+import { loadBudgetPolicy } from './budgets.js';
+import { loadCrosscheckPolicy } from './crosscheck.js';
+import { apply, foldTasks, rebuild } from './db/projector.js';
+import { summariseEpicWidth, UNMEASURED_HINT } from './epicWidth.js';
+import { SmithError } from './errors.js';
+import { listSessionIds, mergeSessionLogs, parseEventId, readEvents, } from './events.js';
+import { ageFindings, memoryOf } from './findingAge.js';
+import { STATE_DAEMON_DIR, STATE_DB_PATH, STATE_EVENTS_DIR } from './paths.js';
+import { unwatchedProjects } from './projects.js';
+import { computeProposals, loadSchedulerPolicy, } from './scheduler.js';
+import { foldSpecChanges } from './specChange.js';
+export class DaemonError extends SmithError {
+}
+/** A session log's first event, and the only one allowed to name another session. */
+const ROOT_EVENT_TYPE = 'session-start';
+const LOCK_FILE = 'daemon.pid';
+const STATUS_FILE = 'status.json';
+const MEMORY_FILE = 'findings.json';
+export const DEFAULT_INTERVAL_SECONDS = 300;
+/**
+ * One admission per proposal, positionally — `admitProposals` returns them in
+ * the order given, which is the only reason the callers may index alongside
+ * their own loop.
+ *
+ * The claims are folded here rather than passed in because a `RecheckProposal`
+ * names a task and no paths: without them the security match sees an opaque id
+ * and clears a recheck of `src/auth/session.ts`. They come out of the same
+ * `foldTasks` the CLI reads, from the events the caller already holds.
+ */
+function admitFor(proposals, events, lens) {
+    if (lens === undefined || proposals.length === 0)
+        return proposals.map(() => undefined);
+    const claimsByTask = new Map();
+    for (const task of foldTasks(events)) {
+        if (task.claims && task.claims.length > 0)
+            claimsByTask.set(task.taskId, task.claims);
+    }
+    return admitProposals(proposals, lens.autonomy, {
+        securityKeywords: lens.securityKeywords,
+        claimsByTask,
+    }).map(({ decision, code, reason }) => ({ decision, code, reason }));
+}
+function staleSubject(agent) {
+    return agent.taskId ?? agent.epicId ?? agent.agentId ?? agent.id;
+}
+/**
+ * Everything one session's lineage says about itself: spend against the epic
+ * cap, dispatches nobody can be billed for, agents that never came back, and
+ * completed work the recheck policy says is due another look.
+ *
+ * Pure — `events` is already-read, `now` is threaded in. The disk work is
+ * runTick's.
+ */
+export function inspectSession(sessionId, events, opts = {}) {
+    const now = opts.now ?? new Date();
+    const budgetPolicy = opts.budgetPolicy ?? loadBudgetPolicy();
+    const schedulerPolicy = opts.schedulerPolicy ?? loadSchedulerPolicy();
+    const staleHours = opts.staleHours ?? DEFAULT_STALE_HOURS;
+    const findings = [];
+    const budget = checkBudgetAlarm(events, budgetPolicy, { sessionId });
+    for (const epic of budget.epics) {
+        // `under` is the only status that is an answer rather than a question.
+        if (epic.status === 'under')
+            continue;
+        findings.push({
+            kind: 'budget',
+            severity: epic.status === 'unverifiable' ? 'info' : 'attention',
+            sessionId,
+            subject: epic.epicId,
+            // The status leads, and the numbers behind it are budgetAlarm's own
+            // sentence — two files describing one spend in two registers is how the
+            // daemon and `smith budget` start disagreeing.
+            detail: `${epic.status}: ${epic.detail}`,
+        });
+    }
+    if (budget.unattributedDispatches > 0) {
+        findings.push({
+            kind: 'unattributed-spend',
+            severity: 'info',
+            sessionId,
+            subject: `${budget.unattributedDispatches} dispatch(es)`,
+            detail: `${budget.unattributedDispatches} dispatch(es) (${budget.unattributedRoles.join(', ')}) ` +
+                'name no epic, so their tokens are in no cap. Attribute them or accept that the ' +
+                'session total is a floor.',
+        });
+    }
+    for (const agent of detectStale(foldAgents(events), now.toISOString(), staleHours)) {
+        findings.push({
+            kind: 'stale-agent',
+            severity: 'attention',
+            sessionId,
+            subject: staleSubject(agent),
+            detail: `${agent.agentRole} (${agent.provider}/${agent.modelTier}) has been live for ` +
+                `${agent.liveHours.toFixed(1)}h with no result, error or supersession — past the ` +
+                `${staleHours}h threshold. Dispatched ${agent.dispatchedAt}.`,
+        });
+    }
+    // A proposal nobody has answered. `blocking` is the worker's own word for
+    // "I cannot go further without this", which makes an unanswered blocking
+    // proposal a stalled task and not a queue item — the same split
+    // research_request draws.
+    //
+    // Folded, never staleness-checked: `isStale` reads the plan directory and
+    // this function is pure. The daemon's claim is that a decision is
+    // outstanding, which stays true whether or not a later version has overtaken
+    // the diff; `smith plan proposals` is where that second question is answered.
+    for (const proposal of foldSpecChanges(events, { status: 'open' })) {
+        findings.push({
+            kind: 'spec-change',
+            severity: proposal.blocking ? 'attention' : 'info',
+            sessionId,
+            subject: proposal.taskId,
+            detail: `${proposal.proposedBy} proposes amending ${proposal.criterionRef}: ${proposal.assumption} ` +
+                `(${proposal.severity}, ${proposal.blocking ? 'blocking' : 'non-blocking'}, ` +
+                `${proposal.sites.length} site(s)). Answer it with \`smith plan approve ` +
+                `${proposal.proposalId}\` or \`smith plan reject ${proposal.proposalId}\`.`,
+        });
+    }
+    const proposals = computeProposals({ events, now, policy: schedulerPolicy });
+    const admissions = admitFor(proposals, events, opts.admission);
+    for (const [index, proposal] of proposals.entries()) {
+        if (proposal.kind !== 'recheck')
+            continue;
+        const admission = admissions[index];
+        findings.push({
+            kind: 'recheck',
+            severity: 'info',
+            sessionId,
+            subject: proposal.taskId,
+            detail: `Recheck due (${proposal.reasons.join(', ')}): ${proposal.mergeCount} later overlapping ` +
+                `merge(s), ${proposal.daysElapsed} day(s) elapsed, confidence ${proposal.confidence}.`,
+            ...(admission === undefined ? {} : { admission }),
+        });
+    }
+    return findings;
+}
+/**
+ * The findings that belong to the repo and not to any one session: the growth
+ * cadence and the dependency-maintenance pass.
+ *
+ * Split out of inspectSession deliberately. Both are answered from the whole
+ * log, and a cadence attributed to a session is a cadence reported once per
+ * session — five open sessions, five identical "growth review due" lines, none
+ * of which is about that session.
+ */
+export function inspectFactory(events, opts = {}) {
+    const now = opts.now ?? new Date();
+    const policy = opts.schedulerPolicy ?? loadSchedulerPolicy();
+    const findings = [];
+    const proposals = computeProposals({
+        events,
+        now,
+        policy,
+        ...(opts.projectDirs === undefined ? {} : { projectDirs: opts.projectDirs }),
+        ...(opts.readOutdated === undefined ? {} : { readOutdated: opts.readOutdated }),
+    });
+    const admissions = admitFor(proposals, events, opts.admission);
+    for (const [index, proposal] of proposals.entries()) {
+        const admission = admissions[index];
+        if (proposal.kind === 'maintenance') {
+            findings.push({
+                kind: 'maintenance',
+                severity: 'info',
+                sessionId: null,
+                subject: `${proposal.projectDir}: ${proposal.packages.length} package(s)`,
+                detail: `${proposal.packages.map((p) => `${p.name} ${p.current}→${p.latest}`).join(', ')} ` +
+                    `(confidence ${proposal.confidence}, ` +
+                    `${proposal.autoSchedulable ? 'auto-schedulable' : 'needs an operator'}).`,
+                ...(admission === undefined ? {} : { admission }),
+            });
+        }
+        else if (proposal.kind === 'growth-review-due' && events.length > 0) {
+            // A cadence needs a log to be a cadence about. `proposeGrowthReview`
+            // fires immediately on `lastReviewAt === null`, which is right for a
+            // factory that has been working and never reviewed itself and wrong for
+            // one that has never done anything at all -- and the second is what an
+            // empty log means. The gate belongs on this branch alone: the pass also
+            // reads lockfiles and the project register, and neither of those waits
+            // on a session to have happened.
+            findings.push({
+                kind: 'growth-review',
+                severity: 'info',
+                sessionId: null,
+                subject: 'growth-review',
+                detail: `A product-growth review is due on the ${proposal.cadenceDays}-day cadence ` +
+                    `(last: ${proposal.lastReviewAt ?? 'never'}). The planner reads the living spec; ` +
+                    'this is the trigger, not the scope.',
+                ...(admission === undefined ? {} : { admission }),
+            });
+        }
+        // Rechecks are deliberately dropped here: inspectSession already reports
+        // each against the session that owns it, and a second copy with no session
+        // is a duplicate an operator cannot act on.
+    }
+    // The claim this repo rests on, watched instead of waited on. `smith epic
+    // width` answers it over all of history the moment somebody types it — and
+    // nobody types it, which is the gap a watcher exists to close.
+    //
+    // Of the NEWEST close only, and that restriction is the whole design.
+    // Closes are immutable and the fold covers every one of them, so reporting
+    // the fold here would raise the same `attention` every tick forever over an
+    // epic nobody can go back and fix. An attention count that cannot return to
+    // zero is precisely what the FindingSeverity note above forbids: it teaches
+    // an operator to stop reading the number, and takes the real alarms with it.
+    // The newest close is a statement about now — it clears itself the moment a
+    // wide epic closes, and all of the history stays one command away.
+    const width = summariseEpicWidth(events);
+    const newest = width.epics[0];
+    if (newest !== undefined) {
+        if (width.serialized.includes(newest.epicId)) {
+            // The summary's own rule, reused rather than restated, so the daemon and
+            // `smith epic width` cannot come to disagree about what narrow means.
+            findings.push({
+                kind: 'factory-width',
+                severity: 'attention',
+                sessionId: null,
+                subject: newest.epicId,
+                detail: `The last epic this factory closed ran narrow: its widest wave was admitted for ` +
+                    `${newest.widest.declared} tasks and ${newest.widest.observed} ran ` +
+                    `(closed ${newest.closedAt}, ${width.serialized.length} of ${width.epics.length} ` +
+                    'closes read here are narrow). `smith epic width` reads every close back; ' +
+                    '`smith wave audit --session <id>` reads the waves behind a live one.',
+            });
+        }
+        else if (width.hint === UNMEASURED_HINT) {
+            // Work to schedule, not a fault: nothing here is known to be wrong. What
+            // is wrong is that nothing is known, which is a different thing and the
+            // reason summariseEpicWidth refuses to let this state exit 0.
+            findings.push({
+                kind: 'factory-width',
+                severity: 'info',
+                sessionId: null,
+                subject: 'unmeasured',
+                detail: `${width.epics.length} epic(s) closed here and none recorded how wide it ran. ` +
+                    UNMEASURED_HINT,
+            });
+        }
+    }
+    // The other half of the sentence this repo is built to answer: it maintains
+    // itself AND the projects it built. `--project` has been able to name every
+    // repo since the maintenance pass went plural, and nothing noticed an
+    // operator who named fewer than all of them -- so a project could drop out
+    // of maintenance by being forgotten, which is the same silence, one level
+    // down, that repeating the flag was meant to end.
+    //
+    // Clearable in one flag, which is the test the factory-width note above sets
+    // for any new attention. The register deliberately omits a project it cannot
+    // find on disk, so nothing here can raise an alarm that has no action.
+    for (const ref of unwatchedRepos(opts)) {
+        findings.push({
+            kind: 'unwatched-project',
+            severity: 'attention',
+            sessionId: null,
+            // The resolved directory, for the same two reasons `maintenance` leads
+            // with it: sessionId is null so the subject is the only field that can
+            // tell two repos apart, and it is the exact string that clears this.
+            subject: ref.dir,
+            detail: `${ref.self ? 'This clone' : `\`${ref.name}\`, built by this factory`} is not in ` +
+                'this pass, so nothing is reading its lockfile and no maintenance ' +
+                `proposal can ever name it. Add \`--project ${ref.dir}\` to \`smith daemon ` +
+                'run|start` (and to `smith scheduler run|admit`). `smith projects list` ' +
+                'prints the whole flag line.',
+        });
+    }
+    return findings;
+}
+/**
+ * The repos the register knows and this pass was not pointed at.
+ *
+ * Wrapped in a catch because the register reads an operator-edited file and
+ * this is a watcher: D-21 -- a gate that only reports a fact must never crash
+ * over that fact. `factoryProjects` already refuses to throw; this makes an
+ * injected reader that does cost nothing but its own finding.
+ */
+function unwatchedRepos(opts) {
+    if (opts.readProjects === undefined)
+        return [];
+    try {
+        return unwatchedProjects(opts.readProjects(), opts.projectDirs ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * One pass over the state directory.
+ *
+ * Two rules hold it together. It reads every log ONCE and folds lineages in
+ * memory, so a five-session lineage reports one budget alarm rather than five
+ * (D-119's argument, read from the other end). And no single unreadable log or
+ * failed projection ends the tick: both become findings, because a watchdog
+ * that dies on the first corrupt line is a watchdog that is silent exactly
+ * when something is wrong.
+ */
+export async function runTick(opts = {}) {
+    const now = opts.now ?? new Date();
+    const stateDir = opts.stateDir ?? STATE_EVENTS_DIR;
+    const findings = [];
+    const logs = new Map();
+    for (const sessionId of listSessionIds(stateDir)) {
+        try {
+            logs.set(sessionId, await readEvents(sessionId, { stateDir }));
+        }
+        catch (err) {
+            findings.push({
+                kind: 'unreadable-log',
+                severity: 'attention',
+                sessionId,
+                subject: `${sessionId}.jsonl`,
+                detail: `The log could not be read: ${errorMessage(err)}`,
+            });
+        }
+    }
+    const parentOf = new Map();
+    for (const [sessionId, events] of logs) {
+        const root = events.find((e) => e.record.event_type === ROOT_EVENT_TYPE);
+        const parentEventId = root?.record.causal_parent ?? null;
+        let parent = null;
+        if (parentEventId !== null) {
+            try {
+                parent = parseEventId(parentEventId).sessionId;
+            }
+            catch {
+                parent = null;
+            }
+        }
+        parentOf.set(sessionId, parent === sessionId ? null : parent);
+    }
+    const ancestors = new Set();
+    for (const parent of parentOf.values()) {
+        if (parent !== null && logs.has(parent))
+            ancestors.add(parent);
+    }
+    const leaves = [...logs.keys()].filter((id) => !ancestors.has(id)).sort();
+    const lineageOf = (leaf) => {
+        const chain = [];
+        const seen = new Set();
+        let current = leaf;
+        while (current !== null && logs.has(current) && !seen.has(current)) {
+            seen.add(current);
+            chain.unshift(current);
+            current = parentOf.get(current) ?? null;
+        }
+        return chain.map((sessionId) => ({ sessionId, events: logs.get(sessionId) ?? [] }));
+    };
+    // A tick reports the admission line by default, where `inspectSession` and
+    // `inspectFactory` stay silent unless asked. The asymmetry is deliberate: a
+    // caller who reaches for one function is answering their own question and
+    // may not want two policy files read, whereas the whole point of a tick is
+    // to be the surface nobody is watching — a status file that omitted the one
+    // column saying whose queue a finding is in would be omitting it precisely
+    // when it matters. Reading policy here also fails loudly at the top of the
+    // tick rather than silently downgrading a finding to unadmitted.
+    const admission = opts.admission ?? {
+        autonomy: (opts.schedulerPolicy ?? loadSchedulerPolicy()).autonomy,
+        securityKeywords: loadCrosscheckPolicy().planQuorum.securityKeywords,
+    };
+    const inspectOpts = {
+        now,
+        admission,
+        ...(opts.budgetPolicy === undefined ? {} : { budgetPolicy: opts.budgetPolicy }),
+        ...(opts.schedulerPolicy === undefined ? {} : { schedulerPolicy: opts.schedulerPolicy }),
+        ...(opts.staleHours === undefined ? {} : { staleHours: opts.staleHours }),
+        ...(opts.projectDirs === undefined ? {} : { projectDirs: opts.projectDirs }),
+        ...(opts.readOutdated === undefined ? {} : { readOutdated: opts.readOutdated }),
+        ...(opts.readProjects === undefined ? {} : { readProjects: opts.readProjects }),
+    };
+    const projectDb = opts.projectDb ?? true;
+    const dbPath = opts.dbPath ?? STATE_DB_PATH;
+    const dbOpts = { stateDir, ...opts.dbOpts };
+    let projected = 0;
+    // Carries no session when there was none to blame. Clearable either way: the
+    // next tick that can open the file drops it.
+    const projectionFailed = (sessionId, err) => ({
+        kind: 'projection-failed',
+        severity: 'attention',
+        sessionId,
+        subject: dbPath,
+        detail: `The read-model refresh failed: ${errorMessage(err)}. The event log is unaffected — ` +
+            'it is the UI and `smith status` that are now stale.',
+    });
+    for (const leaf of leaves) {
+        findings.push(...inspectSession(leaf, mergeSessionLogs(lineageOf(leaf)), inspectOpts));
+        if (!projectDb)
+            continue;
+        try {
+            await apply(dbPath, leaf, dbOpts);
+            projected += 1;
+        }
+        catch (err) {
+            findings.push(projectionFailed(leaf, err));
+        }
+    }
+    // The read-model is not made of sessions alone. `milestones` is a full
+    // replacement of roadmap.md on every projector call -- projector.ts calls it
+    // "not session-scoped" in as many words -- and `apply()` inside the loop
+    // above was the only thing a running daemon ever called. So a tick that
+    // folded no session refreshed nothing, and on a fresh clone that meant no
+    // database file at all: the operator writes a roadmap, starts the watcher,
+    // opens the UI, and the Roadmap view and the project switcher are both
+    // empty until somebody happens to run `smith db rebuild` by hand. Rebuilding
+    // is the honest answer to "no session to fold" and not merely the
+    // convenient one: with an empty log it clears nothing and projects the
+    // roadmap, which is exactly what that hand-run command does. It stays cheap
+    // because it is unreachable the moment one session exists.
+    if (projectDb && leaves.length === 0) {
+        try {
+            await rebuild(dbPath, 'all', dbOpts);
+        }
+        catch (err) {
+            findings.push(projectionFailed(null, err));
+        }
+    }
+    // Always, including on a clone whose event log is empty. This used to be
+    // gated on there being a session to fold, which suppressed the right half
+    // for the wrong reason: growth-review is the only finding here that is a
+    // claim about elapsed history, and `inspectFactory` now gates that branch
+    // itself. Maintenance reads lockfiles and `unwatched-project` reads the
+    // register; a dependency falls behind on the registry's clock and a repo
+    // goes unwatched the moment it is scaffolded, so a factory that has built
+    // nothing still has repos to tend.
+    const all = [...logs.entries()].map(([sessionId, events]) => ({ sessionId, events }));
+    findings.push(...inspectFactory(mergeSessionLogs(all), inspectOpts));
+    const aged = ageFindings(opts.memory ?? {}, findings, now);
+    return {
+        at: now.toISOString(),
+        sessions: leaves,
+        findings: aged,
+        attention: aged.filter((f) => f.severity === 'attention').length,
+        newAttention: aged.filter((f) => f.severity === 'attention' && f.isNew).length,
+        autoAdmitted: aged.filter((f) => f.admission?.decision === 'auto').length,
+        operatorHeld: aged.filter((f) => f.admission?.decision === 'operator').length,
+        projected,
+    };
+}
+export function lockPath(dir) {
+    return path.join(dir, LOCK_FILE);
+}
+export function statusPath(dir) {
+    return path.join(dir, STATUS_FILE);
+}
+function readJsonFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function readLock(dir) {
+    const lock = readJsonFile(lockPath(dir));
+    if (lock === null || typeof lock.pid !== 'number')
+        return null;
+    return lock;
+}
+/** `kill(pid, 0)` — EPERM means a process exists that this user may not signal. */
+export function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Claim `dir` for `lock.pid`, returning the lock this one displaced (null when
+ * there was nothing to displace, or nothing readable).
+ *
+ * Two daemons ticking the same state dir would double every projection write
+ * and every finding, so a live incumbent is refused. A DEAD incumbent is not:
+ * a crashed daemon leaves its pid file behind, and refusing to start until a
+ * human runs `rm` would make the first crash permanent. Likewise an
+ * unparseable file — half a JSON document is what a crash mid-write looks
+ * like, and it is evidence of a dead writer, not a live one.
+ */
+export function acquireLock(dir, lock, opts = {}) {
+    const isAlive = opts.isAlive ?? processIsAlive;
+    mkdirSync(dir, { recursive: true });
+    const file = lockPath(dir);
+    const body = `${JSON.stringify(lock, null, 2)}\n`;
+    try {
+        writeFileSync(file, body, { encoding: 'utf8', flag: 'wx' });
+        return null;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    const incumbent = readLock(dir);
+    if (incumbent !== null && isAlive(incumbent.pid)) {
+        throw new DaemonError('daemon.already-running', `A daemon (pid ${incumbent.pid}, started ${incumbent.startedAt}) already holds ${file}. ` +
+            'Stop it with `smith daemon stop` before starting another.', { pid: incumbent.pid, lock_path: file });
+    }
+    writeFileSync(file, body, 'utf8');
+    return incumbent;
+}
+/** True when this call removed the lock; false when it belongs to someone else. */
+export function releaseLock(dir, pid) {
+    const lock = readLock(dir);
+    if (lock === null || lock.pid !== pid)
+        return false;
+    rmSync(lockPath(dir), { force: true });
+    return true;
+}
+// ---------------------------------------------------------------------------
+// The status file
+// ---------------------------------------------------------------------------
+/** tmp-then-rename, so a reader polling this file never sees half a document. */
+export function writeStatus(dir, report) {
+    mkdirSync(dir, { recursive: true });
+    const target = statusPath(dir);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    renameSync(tmp, target);
+}
+export function readStatus(dir) {
+    return readJsonFile(statusPath(dir));
+}
+// ---------------------------------------------------------------------------
+// The finding memory
+// ---------------------------------------------------------------------------
+export function memoryPath(dir) {
+    return path.join(dir, MEMORY_FILE);
+}
+/**
+ * The only state this daemon carries across ticks, and deliberately the least
+ * it could carry: identity -> when it was first seen.
+ *
+ * Missing or corrupt reads as empty rather than throwing, for the same reason
+ * `unreadable-log` is a finding and not a crash. A watchdog that dies over its
+ * own scratch file is silent exactly when something is wrong, and the cost of
+ * losing this one is a single tick that calls every standing finding new.
+ */
+export function readFindingMemory(dir) {
+    return readJsonFile(memoryPath(dir)) ?? {};
+}
+/** tmp-then-rename, like the status file: a half-written memory reads as none. */
+export function writeFindingMemory(dir, memory) {
+    mkdirSync(dir, { recursive: true });
+    const target = memoryPath(dir);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(memory, null, 2)}\n`, 'utf8');
+    renameSync(tmp, target);
+}
+/**
+ * How long a daemon may go quiet before the silence is itself the finding.
+ *
+ * Three intervals is the miss-two-heartbeats rule: one late tick is a slow fold
+ * of a long log, two in a row is a fault. The floor is there because a tick's
+ * cost is not proportional to the interval -- folding the event log takes what
+ * it takes -- so `--interval 1` would otherwise report a daemon as wedged for
+ * doing exactly the work it was told to do too often.
+ */
+const STALE_INTERVALS = 3;
+const STALE_FLOOR_SECONDS = 60;
+function staleToleranceSeconds(lock) {
+    // D-21: a report that only states a fact must not crash over that fact, and a
+    // hand-edited pid file is a bad lock rather than a reason to have no status.
+    const interval = typeof lock.intervalSeconds === 'number' && lock.intervalSeconds > 0
+        ? lock.intervalSeconds
+        : DEFAULT_INTERVAL_SECONDS;
+    return Math.max(interval * STALE_INTERVALS, STALE_FLOOR_SECONDS);
+}
+/** Seconds since `iso`, or null when there is no readable timestamp to date. */
+function ageSeconds(now, iso) {
+    if (iso === undefined)
+        return null;
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return null;
+    return Math.round((now.getTime() - then) / 1000);
+}
+export function daemonStatus(dir, opts = {}) {
+    const isAlive = opts.isAlive ?? processIsAlive;
+    const now = opts.now ?? new Date();
+    const lock = readLock(dir);
+    const lastTick = readStatus(dir);
+    const running = lock !== null && isAlive(lock.pid);
+    const reportAge = ageSeconds(now, lastTick?.at);
+    // The freshest thing this daemon is known to have done. `min` rather than the
+    // tick alone: a daemon that restarted after a long quiet spell has done
+    // something more recent than its predecessor's last report, and dating it
+    // from that report would alarm on a watcher that is two seconds old.
+    const lockAge = lock === null ? null : ageSeconds(now, lock.startedAt);
+    const ages = [reportAge, lockAge].filter((a) => a !== null);
+    const quietFor = ages.length === 0 ? null : Math.min(...ages);
+    return {
+        running,
+        stale: running && lock !== null && quietFor !== null && quietFor > staleToleranceSeconds(lock),
+        dir,
+        lock,
+        lastTick,
+        reportAgeSeconds: reportAge,
+    };
+}
+/**
+ * Deliberately NOT unref'd. An unref'd timer lets node decide the event loop
+ * is empty and exit mid-sleep — skipping the `finally` below, and leaving a
+ * lock behind naming a pid that is already gone.
+ */
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Hold the lock, tick, publish, repeat.
+ *
+ * The `finally` is the point of the whole function: a loop that exits still
+ * holding its lock — because a tick threw, because the operator hit ^C — is a
+ * loop nothing can restart without a human deleting a file.
+ */
+export async function runDaemon(opts) {
+    const pid = opts.pid ?? process.pid;
+    const intervalSeconds = opts.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS;
+    const startedAt = (opts.now ?? new Date()).toISOString();
+    const tick = opts.tick ?? runTick;
+    const sleep = opts.sleep ?? defaultSleep;
+    const shouldContinue = opts.shouldContinue ?? (() => true);
+    acquireLock(opts.dir, { pid, startedAt, intervalSeconds }, opts.isAlive === undefined ? {} : { isAlive: opts.isAlive });
+    const tickOptions = {
+        ...(opts.now === undefined ? {} : { now: opts.now }),
+        ...(opts.budgetPolicy === undefined ? {} : { budgetPolicy: opts.budgetPolicy }),
+        ...(opts.schedulerPolicy === undefined ? {} : { schedulerPolicy: opts.schedulerPolicy }),
+        ...(opts.staleHours === undefined ? {} : { staleHours: opts.staleHours }),
+        ...(opts.projectDirs === undefined ? {} : { projectDirs: opts.projectDirs }),
+        ...(opts.readProjects === undefined ? {} : { readProjects: opts.readProjects }),
+        ...(opts.stateDir === undefined ? {} : { stateDir: opts.stateDir }),
+        ...(opts.projectDb === undefined ? {} : { projectDb: opts.projectDb }),
+        ...(opts.dbPath === undefined ? {} : { dbPath: opts.dbPath }),
+        ...(opts.dbOpts === undefined ? {} : { dbOpts: opts.dbOpts }),
+    };
+    // Read from disk rather than held in a variable, so a daemon restarted by
+    // cron or by the operator picks up where the last process stopped. A tick
+    // knows nothing about the interval it runs on; this is what joins two.
+    const tickWithMemory = async () => {
+        const report = await tick({ ...tickOptions, memory: readFindingMemory(opts.dir) });
+        writeStatus(opts.dir, report);
+        writeFindingMemory(opts.dir, memoryOf(report.findings));
+        return report;
+    };
+    const reports = [];
+    try {
+        if (opts.once === true) {
+            reports.push(await tickWithMemory());
+            return reports;
+        }
+        while (shouldContinue()) {
+            reports.push(await tickWithMemory());
+            await sleep(intervalSeconds * 1000);
+        }
+        return reports;
+    }
+    finally {
+        releaseLock(opts.dir, pid);
+    }
+}
+/**
+ * SIGTERM the process the lock names, then clear the file.
+ *
+ * `stopped` answers "did this call signal a running daemon", so a stale lock
+ * left by a crash reports `stopped: false` with the pid it cleared — the
+ * operator learns the daemon was already gone rather than being told it was
+ * just stopped.
+ */
+export function stopDaemon(dir, opts = {}) {
+    const isAlive = opts.isAlive ?? processIsAlive;
+    const kill = opts.kill ??
+        ((pid) => {
+            process.kill(pid, 'SIGTERM');
+        });
+    const lock = readLock(dir);
+    if (lock === null)
+        return { stopped: false, pid: null };
+    const alive = isAlive(lock.pid);
+    if (alive)
+        kill(lock.pid);
+    rmSync(lockPath(dir), { force: true });
+    return { stopped: alive, pid: lock.pid };
+}
+/** Where `smith daemon` keeps its lock and its last tick, when nobody says otherwise. */
+export const DEFAULT_DAEMON_DIR = STATE_DAEMON_DIR;