@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/lib/signals/engine.js

@@ -0,0 +1,504 @@
+/**
+ * Orchestrator for `hq signals run`. Callable programmatically via
+ * runSignals(); clock, spawn and HQ root are injected for tests.
+ *
+ * Step order: garden -> adapters -> extract -> garden -> upload.
+ * Records (run record contract v2): workspace/signals/runs/{date}/{company}.json
+ * is the source of truth for one company's day; summary.json in the same
+ * folder is read-modify-written per company and never drops other companies.
+ * Each company runs under workspace/signals/runs/{date}/{company}.lock.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { loadSignalsSettings } from "./settings.js";
+import { localDate } from "./local-date.js";
+import { guardedWrite, WriteGuardError } from "./write-guard.js";
+import { acquireCompanyLock, withSummaryLock } from "./run-lock.js";
+import { gardenStep } from "./steps/garden.js";
+import { adaptersStep } from "./steps/adapters.js";
+import { extractStep, redoItemChannel } from "./steps/extract.js";
+import { uploadStep } from "./steps/upload.js";
+import { raiseSignalsRunAlerts } from "./failure-alert.js";
+export const SIGNALS_TRIGGERS = ["job", "chat", "manual", "brief"];
+export const SIGNALS_STEP_CHOICES = ["garden", "extract", "adapters", "upload", "all"];
+export const STEP_ORDER = ["garden", "adapters", "extract", "garden", "upload"];
+export const RUN_RECORD_SCHEMA_VERSION = 2;
+/** A failed run with a transient error is due for a retry this long after it finished. */
+export const RETRY_DELAY_MS = 15 * 60 * 1000;
+/** Bad input from the caller (company slug, missing company): exit 2. */
+export class SignalsUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SignalsUsageError";
+    }
+}
+/** Broken local setup (missing or failing knowledge-prefs.sh): errorKind config. */
+export class SignalsConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SignalsConfigError";
+    }
+}
+export const defaultSpawn = (cmd, args, opts) => {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd,
+        env: opts.env ?? process.env,
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+        ...(opts.timeoutMs !== undefined ? { timeout: opts.timeoutMs, killSignal: "SIGKILL" } : {}),
+    });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error };
+};
+const DEFAULT_STEPS = {
+    garden: gardenStep,
+    adapters: adaptersStep,
+    extract: extractStep,
+    upload: uploadStep,
+};
+// Lives in its own module so steps can use it without importing the engine.
+export { localDate };
+export function runRecordRel(date, company) {
+    return `workspace/signals/runs/${date}/${company}.json`;
+}
+export function summaryRel(date) {
+    return `workspace/signals/runs/${date}/summary.json`;
+}
+const SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** Companies under companies/ that are also listed in companies/manifest.yaml. */
+export function listCompanies(hqRoot) {
+    let manifest;
+    try {
+        manifest = yaml.load(fs.readFileSync(path.join(hqRoot, "companies", "manifest.yaml"), "utf8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`hq signals: cannot read companies/manifest.yaml: ${msg}\n`);
+        return [];
+    }
+    const listed = manifest?.companies ?? {};
+    return Object.keys(listed)
+        .filter((co) => SLUG_RE.test(co) && fs.existsSync(path.join(hqRoot, "companies", co)))
+        .sort();
+}
+const TRUE_VALUES = new Set(["true", "yes", "on", "1"]);
+/** Reads one knowledge preference. Throws SignalsConfigError when the script is missing or fails. */
+export function readPref(hqRoot, company, field, spawn) {
+    const script = path.join(hqRoot, "core", "scripts", "knowledge-prefs.sh");
+    if (!fs.existsSync(script)) {
+        throw new SignalsConfigError("core/scripts/knowledge-prefs.sh is missing, so the capture settings could not be read");
+    }
+    const r = spawn("bash", [script, "get", company, field], {
+        cwd: hqRoot,
+        env: { ...process.env, HQ_ROOT: hqRoot },
+    });
+    if (r.error || r.status !== 0) {
+        const detail = (r.error?.message ?? r.stderr.trim()) || `exit ${String(r.status)}`;
+        throw new SignalsConfigError(`knowledge-prefs.sh could not read ${field}: ${detail.slice(0, 200)}`);
+    }
+    return TRUE_VALUES.has(r.stdout.trim().toLowerCase());
+}
+function readJson(hqRoot, rel) {
+    const abs = path.join(hqRoot, rel);
+    if (!fs.existsSync(abs))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(abs, "utf8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`hq signals: ignoring unreadable ${rel}: ${msg}\n`);
+        return null;
+    }
+}
+function baseStatus(steps) {
+    if (steps.some((s) => s.status === "failed")) {
+        return steps.some((s) => s.status === "ok" || s.status === "partial") ? "partial" : "failed";
+    }
+    if (steps.some((s) => s.status === "partial"))
+        return "partial";
+    if (steps.length > 0 && steps.every((s) => s.status === "skipped"))
+        return "skipped";
+    return "complete";
+}
+const KIND_RANK = { auth: 3, config: 2, transient: 1 };
+/** Coarse v2 kind for a step's detailed kind. */
+export function toRunErrorKind(kind) {
+    if (kind === "reconnect" || kind === "signed-out")
+        return "auth";
+    if (kind === "config")
+        return "config";
+    return "transient";
+}
+function stepErrorKindFor(err) {
+    return err instanceof SignalsConfigError || err instanceof WriteGuardError ? "config" : "other";
+}
+function sentence(text) {
+    const t = text.trim().replace(/[.\s]+$/, "");
+    return `${t}.`;
+}
+/** Fills the v2 outcome fields of a finished record from its steps. */
+export function finalizeRecord(record, input) {
+    record.currentStep = null;
+    record.finishedAt = input.finishedAt.toISOString();
+    const problems = record.steps.filter((s) => s.status === "failed" || s.status === "partial");
+    // A skip decided before any step (prefs-off, late-start with nothing to run) stays a skip.
+    let status = record.skipReason ? "skipped" : baseStatus(record.steps);
+    let partialReason = null;
+    let failureReason = null;
+    if (input.lateStart && status !== "failed" && status !== "skipped") {
+        status = "partial";
+        partialReason = "late-start";
+        failureReason = `The run started after ${String(input.lateStartHour).padStart(2, "0")}:00, so only the garden step ran.`;
+    }
+    else if (status === "partial" || status === "failed") {
+        const first = problems.find((s) => s.status === "failed") ?? problems[0];
+        if (first) {
+            if (status === "partial")
+                partialReason = `step-${first.status === "failed" ? "failed" : "partial"}:${first.name}`;
+            failureReason =
+                first.status === "failed"
+                    ? sentence(`The ${first.name} step failed${first.error ? `: ${first.error}` : ""}`)
+                    : sentence(`The ${first.name} step finished with problems${first.error ? `: ${first.error}` : ""}`);
+        }
+    }
+    let errorKind = null;
+    if (status === "partial" || status === "failed") {
+        errorKind = "transient";
+        for (const s of problems) {
+            const k = toRunErrorKind(s.errorKind);
+            if (KIND_RANK[k] > KIND_RANK[errorKind])
+                errorKind = k;
+        }
+    }
+    record.status = status;
+    record.partialReason = partialReason;
+    record.partial = partialReason;
+    record.failureReason = failureReason;
+    record.errorKind = errorKind;
+    record.nextRetryAt =
+        status === "failed" && errorKind === "transient"
+            ? new Date(input.finishedAt.getTime() + RETRY_DELAY_MS).toISOString()
+            : null;
+    if (status === "skipped") {
+        record.skipReason = record.skipReason ?? record.steps.find((s) => s.skippedReason)?.skippedReason ?? "nothing-to-run";
+        record.skippedReason = record.skipReason;
+    }
+    if (record.trigger === "job" && (status === "complete" || status === "partial")) {
+        record.jobRanAt = record.finishedAt;
+    }
+    record.counts = {
+        sourcesIn: record.steps.filter((s) => s.name === "adapters").reduce((n, s) => n + s.itemsOut, 0),
+        signalsOut: record.steps.filter((s) => s.name === "extract").reduce((n, s) => n + s.itemsOut, 0),
+    };
+}
+function summaryEntry(r) {
+    const sum = (f) => r.steps.reduce((n, s) => n + f(s), 0);
+    return {
+        company: r.company,
+        status: r.status,
+        trigger: r.trigger,
+        catchUp: r.catchUp === true,
+        finishedAt: r.finishedAt,
+        ...(r.skipReason ? { skipReason: r.skipReason, skippedReason: r.skipReason } : {}),
+        itemsIn: sum((s) => s.itemsIn),
+        itemsOut: sum((s) => s.itemsOut),
+        estimatedSpendUsd: sum((s) => s.estimatedSpendUsd ?? 0),
+    };
+}
+function buildSummary(date, trigger, entries, finishedAt, dryRun) {
+    const totals = { itemsIn: 0, itemsOut: 0, estimatedSpendUsd: 0 };
+    for (const e of entries) {
+        totals.itemsIn += e.itemsIn;
+        totals.itemsOut += e.itemsOut;
+        totals.estimatedSpendUsd += e.estimatedSpendUsd;
+    }
+    const statuses = entries.map((e) => e.status);
+    const status = dryRun
+        ? "dry-run"
+        : statuses.includes("failed")
+            ? "failed"
+            : statuses.includes("partial")
+                ? "partial"
+                : statuses.includes("running")
+                    ? "running"
+                    : statuses.length > 0 && statuses.every((s) => s === "skipped")
+                        ? "skipped"
+                        : "complete";
+    return { schemaVersion: RUN_RECORD_SCHEMA_VERSION, date, trigger, companies: entries, totals, status, finishedAt };
+}
+/** Replaces this company's entry in summary.json, keeping every other company's. */
+function updateSummaryFile(hqRoot, date, record, finishedAt) {
+    withSummaryLock(hqRoot, date, () => {
+        const existing = readJson(hqRoot, summaryRel(date));
+        const others = (Array.isArray(existing?.companies) ? existing.companies : []).filter((e) => typeof e === "object" && e !== null && typeof e.company === "string" && e.company !== record.company);
+        const entries = [...others, summaryEntry(record)].sort((a, b) => a.company.localeCompare(b.company));
+        const summary = buildSummary(date, record.trigger, entries, finishedAt, false);
+        guardedWrite(hqRoot, summaryRel(date), `${JSON.stringify(summary, null, 2)}\n`);
+    });
+}
+export async function runSignals(opts) {
+    const hqRoot = path.resolve(opts.hqRoot);
+    const now = opts.now ?? (() => new Date());
+    const spawn = opts.spawn ?? defaultSpawn;
+    const trigger = opts.trigger ?? "manual";
+    const stepChoice = opts.step ?? "all";
+    const dryRun = opts.dryRun === true;
+    const settings = loadSignalsSettings(hqRoot);
+    const maxTurns = opts.maxTurns ?? settings.maxTurns;
+    const maxBudgetUsd = opts.maxBudgetUsd ?? settings.maxBudgetUsd;
+    const stepImpls = { ...DEFAULT_STEPS, ...(opts.steps ?? {}) };
+    if (opts.company !== undefined && !SLUG_RE.test(opts.company)) {
+        throw new SignalsUsageError(`invalid company slug: ${opts.company}`);
+    }
+    if (opts.company !== undefined && !fs.existsSync(path.join(hqRoot, "companies", opts.company))) {
+        throw new SignalsUsageError(`no company directory: companies/${opts.company}`);
+    }
+    const redo = opts.redo ?? [];
+    if (redo.length > 0) {
+        if (opts.company === undefined)
+            throw new SignalsUsageError("--redo needs --company");
+        const bad = redo.find((f) => redoItemChannel(f) === null);
+        if (bad !== undefined)
+            throw new SignalsUsageError(`--redo item must be sources/<channel>/<file>.md: ${bad}`);
+    }
+    const companies = opts.company !== undefined ? [opts.company] : listCompanies(hqRoot);
+    const start = now();
+    const date = localDate(start);
+    const lateStart = trigger === "job" && start.getHours() >= settings.lateStartHour;
+    let plan = stepChoice === "all" ? STEP_ORDER : STEP_ORDER.filter((s) => s === stepChoice);
+    if (stepChoice !== "all")
+        plan = plan.slice(0, 1);
+    if (lateStart)
+        plan = plan.filter((s) => s === "garden").slice(0, 1);
+    const records = [];
+    const locked = [];
+    for (const company of companies) {
+        const rel = runRecordRel(date, company);
+        // One company scope per run: every write for this company is held to
+        // companies/{company}/ (plus the workspace and personal signals roots), and
+        // a link that resolves into another company's folder is refused.
+        const write = (r, data) => guardedWrite(hqRoot, r, data, { company });
+        // 1. Take the company lock (a dry run writes nothing, so it takes none).
+        let release = null;
+        let takeover = null;
+        if (!dryRun) {
+            const got = acquireCompanyLock({ hqRoot, date, company, trigger, now, ...(opts.isPidAlive ? { isPidAlive: opts.isPidAlive } : {}) });
+            if (!got.ok) {
+                process.stderr.write(`hq signals: ${company}: another run (${got.holder.trigger}, started ${got.holder.startedAt}) holds the lock; nothing started\n`);
+                locked.push({ company, status: "running", startedAt: got.holder.startedAt, trigger: got.holder.trigger });
+                continue;
+            }
+            release = got.release;
+            takeover = got.takeover;
+        }
+        const record = {
+            schemaVersion: RUN_RECORD_SCHEMA_VERSION,
+            company,
+            startedAt: now().toISOString(),
+            finishedAt: null,
+            trigger,
+            pid: process.pid,
+            catchUp: opts.catchUp === true,
+            dryRun,
+            status: "running",
+            skipReason: null,
+            currentStep: null,
+            steps: [],
+            maxBudgetUsd,
+            maxTurns,
+            jobRanAt: null,
+            nextRetryAt: null,
+            errorKind: null,
+            failureReason: null,
+            partialReason: null,
+            partial: null,
+            alreadyRanToday: false,
+            counts: { sourcesIn: 0, signalsOut: 0 },
+            ...(takeover ? { lockTakeover: takeover } : {}),
+        };
+        const persist = () => {
+            if (!dryRun)
+                write(rel, `${JSON.stringify(record, null, 2)}\n`);
+        };
+        const finish = () => {
+            const decidedSkip = record.skipReason;
+            finalizeRecord(record, { lateStart, lateStartHour: settings.lateStartHour, finishedAt: now() });
+            if (dryRun) {
+                if (!decidedSkip) {
+                    record.status = "dry-run";
+                    record.skipReason = null;
+                    delete record.skippedReason;
+                }
+                return;
+            }
+            persist();
+            updateSummaryFile(hqRoot, date, record, record.finishedAt ?? now().toISOString());
+        };
+        try {
+            if (takeover) {
+                process.stderr.write(`hq signals: ${company}: took over a stale lock (${takeover.reason}) from pid ${takeover.pid}, started ${takeover.startedAt}\n`);
+            }
+            // 2. The day's job already ran: do nothing and leave the record as it is.
+            const prior = readJson(hqRoot, rel);
+            const priorJobRanAt = typeof prior?.jobRanAt === "string" ? prior.jobRanAt : null;
+            if (trigger === "job" && !opts.force && prior && priorJobRanAt) {
+                process.stderr.write(`hq signals: ${company}: already-ran (the job ran at ${priorJobRanAt})\n`);
+                records.push({ ...prior, alreadyRanToday: true });
+                continue;
+            }
+            record.jobRanAt = priorJobRanAt;
+            // 3. Mark the run as running before any step.
+            persist();
+            let signalsOn;
+            let ontologyOn;
+            try {
+                signalsOn = readPref(hqRoot, company, "signals_capture", spawn);
+                ontologyOn = readPref(hqRoot, company, "ontology_capture", spawn);
+            }
+            catch (err) {
+                if (!(err instanceof SignalsConfigError))
+                    throw err;
+                record.currentStep = null;
+                record.finishedAt = now().toISOString();
+                record.status = dryRun ? "dry-run" : "failed";
+                record.errorKind = "config";
+                record.failureReason = sentence(err.message.charAt(0).toUpperCase() + err.message.slice(1));
+                record.nextRetryAt = null;
+                if (!dryRun) {
+                    persist();
+                    updateSummaryFile(hqRoot, date, record, record.finishedAt ?? now().toISOString());
+                }
+                records.push(record);
+                continue;
+            }
+            if (!signalsOn && !ontologyOn) {
+                record.skipReason = "prefs-off";
+                finish();
+                records.push(record);
+                continue;
+            }
+            if (plan.length === 0) {
+                record.skipReason = lateStart ? "late-start" : "nothing-to-run";
+                finish();
+                records.push(record);
+                continue;
+            }
+            // 4. Run the steps.
+            for (const name of plan) {
+                record.currentStep = name;
+                persist();
+                const t0 = now().getTime();
+                const ctx = {
+                    hqRoot,
+                    company,
+                    dryRun,
+                    trigger,
+                    catchUp: record.catchUp,
+                    maxTurns,
+                    maxBudgetUsd,
+                    now,
+                    spawn,
+                    write,
+                    ...(opts.hotChannelSync ? { hotChannelSync: opts.hotChannelSync } : {}),
+                    ...(opts.uploadDeps ? { uploadDeps: opts.uploadDeps } : {}),
+                    ...(opts.isFlagOn ? { isFlagOn: opts.isFlagOn } : {}),
+                    ...(opts.registeredAdapterIds ? { registeredAdapterIds: opts.registeredAdapterIds } : {}),
+                    ...(redo.length > 0 ? { redo } : {}),
+                };
+                let stepRec;
+                const planner = stepImpls[name].dryRun;
+                if (dryRun && planner) {
+                    // A step with a read-only planner reports what it would do.
+                    try {
+                        const res = await planner.call(stepImpls[name], ctx);
+                        const { errorKind: _ignored, ...rest } = res;
+                        stepRec = { name, ...rest, status: "skipped", skippedReason: "dry-run", durationMs: 0 };
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        stepRec = {
+                            name,
+                            itemsIn: 0,
+                            itemsOut: 0,
+                            durationMs: 0,
+                            status: "skipped",
+                            skippedReason: "dry-run",
+                            plan: [`plan failed: ${msg.slice(0, 200)}`],
+                        };
+                    }
+                }
+                else if (dryRun) {
+                    stepRec = { name, itemsIn: 0, itemsOut: 0, durationMs: 0, status: "skipped", skippedReason: "dry-run" };
+                }
+                else {
+                    try {
+                        const res = await stepImpls[name].run(ctx);
+                        stepRec = { name, ...res, durationMs: Math.max(0, now().getTime() - t0) };
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        stepRec = {
+                            name,
+                            itemsIn: 0,
+                            itemsOut: 0,
+                            durationMs: Math.max(0, now().getTime() - t0),
+                            status: "failed",
+                            error: msg.slice(0, 500),
+                            errorKind: stepErrorKindFor(err),
+                        };
+                    }
+                }
+                record.steps.push(stepRec);
+                persist();
+            }
+            // 5. Final record and summary entry.
+            finish();
+            records.push(record);
+        }
+        catch (err) {
+            // Anything outside a step (a refused write, say): record the failure
+            // instead of leaving a "running" record behind.
+            const msg = err instanceof Error ? err.message : String(err);
+            record.currentStep = null;
+            record.finishedAt = now().toISOString();
+            record.status = dryRun ? "dry-run" : "failed";
+            record.errorKind = err instanceof WriteGuardError ? "config" : "transient";
+            record.failureReason = sentence(`The run stopped: ${msg.slice(0, 300)}`);
+            record.nextRetryAt =
+                record.errorKind === "transient" ? new Date(new Date(record.finishedAt).getTime() + RETRY_DELAY_MS).toISOString() : null;
+            try {
+                persist();
+            }
+            catch {
+                // the failure is already reported on stderr below
+            }
+            process.stderr.write(`hq signals: ${company}: ${msg}\n`);
+            records.push(record);
+        }
+        finally {
+            release?.();
+        }
+    }
+    const summary = buildSummary(date, trigger, records.map(summaryEntry), now().toISOString(), dryRun);
+    if (!dryRun && opts.signalsAlert) {
+        // The signals-failure alert (US-018). Already-ran and dry-run records are never judged.
+        const alerts = await raiseSignalsRunAlerts({ hqRoot, records, senders: opts.signalsAlert, now });
+        return { date, records, locked, summary, alerts };
+    }
+    return { date, records, locked, summary };
+}
+/**
+ * Exit code for `hq signals run`: 1 when a company failed (a job that already
+ * ran today does not count), else 3 when another run held a company's lock,
+ * else 0 (complete, partial, skipped, already ran).
+ */
+export function signalsExitCode(result) {
+    if (result.records.some((r) => !r.alreadyRanToday && r.status === "failed"))
+        return 1;
+    if (result.locked.length > 0)
+        return 3;
+    return 0;
+}
+//# sourceMappingURL=engine.js.map

package/dist/lib/signals/failure-alert.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The signals-failure alert for the `hq signals run` engine (Hot-Signal Sync
+ * US-018).
+ *
+ * The engine's run record already counts what each step took in and put out.
+ * A run whose extract step read sources and produced no candidates is a
+ * silent stall, the shape of the 2026-10-14 stall. Only sources extract reads
+ * count: hot-channel landings (Slack, Linear, Gmail) that no declared source
+ * channel covers never reach extract, so they cannot show a stall. This module
+ * checks the run record for that shape and hands the failure to the existing
+ * ledger alert path (`raiseSignalsFailureAlerts` in
+ * `src/lib/hot-channels/alert.ts`), so the alert text, the owner DM and the
+ * hourly dedupe in `sources/_runs/@{personKey}/_alerts.json` are the same ones
+ * the hot-channel sync uses. No new posting path is added here.
+ */
+import { type RaiseSignalsFailureAlertsResult } from "../hot-channels/alert.js";
+import type { RunLedgerEntry } from "../hot-channels/ledger.js";
+import type { RunRecord, StepRecord } from "./engine.js";
+/**
+ * Extract skips that are not a stall: no source channel to read, or the
+ * ontology worker is not installed. Both are reported in the run record
+ * already, and an hourly alert would only repeat them.
+ */
+export declare const EXTRACT_SKIPS_WITHOUT_ALERT: ReadonlySet<string>;
+/** The adapter name the engine's alert uses in the shared dedupe file: one key per company vault. */
+export declare const SIGNALS_RUN_ALERT_ADAPTER = "signals-run";
+/** Who the alert is for, and the key of their dedupe file. */
+export interface SignalsAlertPerson {
+    /** The audience key of the person's `sources/_runs/@{personKey}/` folder. */
+    personKey: string;
+    /** Shown in the alert text; usually the person's email. */
+    personName?: string;
+    /** The Cognito sub, recorded on the ledger line the alert is built from. */
+    personUid?: string;
+}
+/** Where the engine sends a signals-failure alert. */
+export interface SignalsRunAlertSenders {
+    /** The primary alert to the owner; throws when it was not delivered. */
+    sendOwnerDm: (text: string) => Promise<void>;
+    /**
+     * The person whose dedupe file is used. Defaults to the signed-in person
+     * (the same key `hq sources sync` uses). Null skips the alert.
+     */
+    resolvePerson?: (company: string) => SignalsAlertPerson | null | Promise<SignalsAlertPerson | null>;
+    log?: (message: string) => void;
+    /**
+     * False for a sender no one reads later, such as the terminal of a manual
+     * `hq signals run`. Its alert neither reads nor writes the hourly dedupe, so
+     * it never suppresses the owner DM the bot sends for the same company.
+     * Default true.
+     */
+    recordsDelivery?: boolean;
+}
+/** The signed-in person, as `runCompanyHotChannelSync` resolves them; null when no one is signed in. */
+export declare function resolveSignedInAlertPerson(): SignalsAlertPerson | null;
+/** Source items the extract step read: its worklist items minus the ones the worklist skipped. */
+export declare function extractSourcesRead(extract: StepRecord): number;
+/**
+ * True when a run's sources produced no signals. The run must be real (not a
+ * dry run, not a repeat of an earlier job run) and have both an adapters and an
+ * extract step (one-step runs and late starts are not judged), and extract
+ * must have produced no candidates. Then either:
+ * - extract ran and read at least one source item, or
+ * - extract did not finish (failed, or skipped for a reason other than
+ *   `no-sources` / `ontology-worker-missing`) after the adapters step landed
+ *   new sources.
+ * Hot-channel landings extract never reads do not count on their own, so a
+ * day with Slack activity and no declared-source items is not a stall.
+ */
+export declare function isSignalsRunFailure(record: RunRecord): boolean;
+/**
+ * The run record as one ledger line, so the existing alert path formats,
+ * sends and dedupes it. `sourcesLanded` is the source items extract read (or,
+ * when extract read none, what the adapters step landed) and
+ * `signalsGenerated` is what extract produced.
+ */
+export declare function signalsRunLedgerLine(record: RunRecord, person: SignalsAlertPerson): RunLedgerEntry;
+/**
+ * Alert the owner for each run record that landed sources and produced no
+ * signals. Never throws; a failed send is logged and left unrecorded, so the
+ * next run tries again. Returns the alert result per company that alerted.
+ */
+export declare function raiseSignalsRunAlerts(input: {
+    hqRoot: string;
+    records: readonly RunRecord[];
+    senders: SignalsRunAlertSenders;
+    now: () => Date;
+}): Promise<Record<string, RaiseSignalsFailureAlertsResult>>;
+//# sourceMappingURL=failure-alert.d.ts.map