@indigoai-us/hq-cli 5.345.190 → 5.345.193

package/dist/lib/signals/engine.d.ts

@@ -0,0 +1,196 @@
+import { localDate } from "./local-date.js";
+import { type LockTakeover } from "./run-lock.js";
+import { type UploadDeps } from "./steps/upload.js";
+import { type SignalsRunAlertSenders } from "./failure-alert.js";
+import type { RaiseSignalsFailureAlertsResult } from "../hot-channels/alert.js";
+import type { ErrorKind, HotChannelSyncFn, SignalsStep, SpawnSyncFn, StepFailure, StepName, StepStatus } from "./steps/types.js";
+import type { AdapterFlagReader } from "./adapters-catalog.js";
+export declare const SIGNALS_TRIGGERS: readonly ["job", "chat", "manual", "brief"];
+export type SignalsTrigger = (typeof SIGNALS_TRIGGERS)[number];
+export declare const SIGNALS_STEP_CHOICES: readonly ["garden", "extract", "adapters", "upload", "all"];
+export type SignalsStepChoice = (typeof SIGNALS_STEP_CHOICES)[number];
+export declare const STEP_ORDER: StepName[];
+export declare const RUN_RECORD_SCHEMA_VERSION: 2;
+/** A failed run with a transient error is due for a retry this long after it finished. */
+export declare const RETRY_DELAY_MS: number;
+export interface StepRecord {
+    name: StepName;
+    itemsIn: number;
+    itemsOut: number;
+    durationMs: number;
+    status: StepStatus;
+    skippedReason?: string;
+    error?: string;
+    /** The step's own error detail (reconnect, signed-out, ...). The record-level errorKind is the coarse v2 kind. */
+    errorKind?: ErrorKind;
+    modelTurns?: number;
+    estimatedSpendUsd?: number;
+    byAdapter?: Record<string, number>;
+    itemsInByAdapter?: Record<string, number>;
+    tokenLevels?: Record<string, string>;
+    adapterSkips?: Record<string, string>;
+    uploaded?: {
+        count: number;
+        bytes: number;
+    };
+    plan?: string[];
+    detail?: Record<string, unknown>;
+    skipped?: number;
+    review?: number;
+    failures?: StepFailure[];
+    skippedItems?: {
+        file: string;
+        reason: string;
+    }[];
+    rejectedCandidates?: number;
+}
+/** "dry-run" is only ever returned in memory; a dry run writes no record. */
+export type RunStatus = "running" | "complete" | "partial" | "failed" | "skipped" | "dry-run";
+export type RunErrorKind = "transient" | "config" | "auth";
+export interface RunRecord {
+    schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;
+    company: string;
+    startedAt: string;
+    finishedAt: string | null;
+    trigger: SignalsTrigger;
+    pid: number;
+    catchUp: boolean;
+    dryRun: boolean;
+    status: RunStatus;
+    /** prefs-off, late-start, ... on a skipped record; else null. */
+    skipReason: string | null;
+    /** v1 name of skipReason, kept for older readers. */
+    skippedReason?: string;
+    currentStep: StepName | null;
+    steps: StepRecord[];
+    maxBudgetUsd: number;
+    maxTurns: number;
+    /** Set when a job run finishes complete or partial; carried forward by every later run that day. */
+    jobRanAt: string | null;
+    /** On failed with errorKind transient: finishedAt + 15 minutes. */
+    nextRetryAt: string | null;
+    errorKind: RunErrorKind | null;
+    /** One plain-language sentence on failed and partial records. */
+    failureReason: string | null;
+    /** late-start, step-failed:{step}, step-partial:{step}, or null. */
+    partialReason: string | null;
+    /** v1 name of partialReason, kept for older readers. */
+    partial: string | null;
+    /** In-memory only: this call found the day's job already ran and did nothing. */
+    alreadyRanToday: boolean;
+    counts: {
+        sourcesIn: number;
+        signalsOut: number;
+    };
+    lockTakeover?: LockTakeover;
+}
+/** A company another run is holding the lock for. Nothing was started for it. */
+export interface LockedCompany {
+    company: string;
+    status: "running";
+    startedAt: string;
+    trigger: string;
+}
+export interface RunSummaryEntry {
+    company: string;
+    status: RunStatus;
+    trigger: SignalsTrigger;
+    /** The record's catchUp flag, so it always matches the company's record. */
+    catchUp: boolean;
+    finishedAt: string | null;
+    skipReason?: string;
+    skippedReason?: string;
+    itemsIn: number;
+    itemsOut: number;
+    estimatedSpendUsd: number;
+}
+export interface RunSummary {
+    schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;
+    date: string;
+    trigger: SignalsTrigger;
+    companies: RunSummaryEntry[];
+    totals: {
+        itemsIn: number;
+        itemsOut: number;
+        estimatedSpendUsd: number;
+    };
+    status: RunStatus;
+    finishedAt: string;
+}
+export interface RunSignalsResult {
+    date: string;
+    records: RunRecord[];
+    locked: LockedCompany[];
+    /** Summary of this call's companies. summary.json on disk holds every company's latest entry. */
+    summary: RunSummary;
+    /**
+     * The signals-failure alert result per company whose run landed sources and
+     * produced no signals (US-018). Omitted when no alert sender was given.
+     */
+    alerts?: Record<string, RaiseSignalsFailureAlertsResult>;
+}
+export interface RunSignalsOptions {
+    hqRoot: string;
+    company?: string;
+    dryRun?: boolean;
+    step?: SignalsStepChoice;
+    trigger?: SignalsTrigger;
+    force?: boolean;
+    catchUp?: boolean;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    now?: () => Date;
+    spawn?: SpawnSyncFn;
+    hotChannelSync?: HotChannelSyncFn;
+    /** Adapter ids the adapters step gates and syncs. Defaults to the builtin registry. */
+    registeredAdapterIds?: readonly string[];
+    uploadDeps?: Partial<UploadDeps>;
+    /**
+     * Company flag reader for the adapters step's gate. Unset in production:
+     * the hot-channel sync then reads the adapter flags through the shared
+     * hq-flags evaluator with the signed-in session.
+     */
+    isFlagOn?: AdapterFlagReader;
+    steps?: Partial<Record<StepName, SignalsStep>>;
+    /**
+     * Where the signals-failure alert goes (US-018): after the run, a company
+     * whose extract step read sources and produced nothing (or failed after new
+     * landings) alerts the owner through the ledger alert path, deduped hourly.
+     * Unset = no alert check.
+     */
+    signalsAlert?: SignalsRunAlertSenders;
+    /** Lock liveness check; defaults to process.kill(pid, 0). */
+    isPidAlive?: (pid: number) => boolean;
+}
+/** Bad input from the caller (company slug, missing company): exit 2. */
+export declare class SignalsUsageError extends Error {
+    constructor(message: string);
+}
+/** Broken local setup (missing or failing knowledge-prefs.sh): errorKind config. */
+export declare class SignalsConfigError extends Error {
+    constructor(message: string);
+}
+export declare const defaultSpawn: SpawnSyncFn;
+export { localDate };
+export declare function runRecordRel(date: string, company: string): string;
+export declare function summaryRel(date: string): string;
+/** Companies under companies/ that are also listed in companies/manifest.yaml. */
+export declare function listCompanies(hqRoot: string): string[];
+/** Reads one knowledge preference. Throws SignalsConfigError when the script is missing or fails. */
+export declare function readPref(hqRoot: string, company: string, field: string, spawn: SpawnSyncFn): boolean;
+/** Coarse v2 kind for a step's detailed kind. */
+export declare function toRunErrorKind(kind: ErrorKind | undefined): RunErrorKind;
+/** Fills the v2 outcome fields of a finished record from its steps. */
+export declare function finalizeRecord(record: RunRecord, input: {
+    lateStart: boolean;
+    lateStartHour: number;
+    finishedAt: Date;
+}): void;
+export declare function runSignals(opts: RunSignalsOptions): Promise<RunSignalsResult>;
+/**
+ * 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 declare function signalsExitCode(result: RunSignalsResult): 0 | 1 | 3;
+//# sourceMappingURL=engine.d.ts.map

package/dist/lib/signals/engine.js

@@ -0,0 +1,495 @@
+/**
+ * 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 } 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 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 } : {}),
+                };
+                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