@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/lib/signals/reply.js

@@ -0,0 +1,368 @@
+/**
+ * The storyboarded bot replies for the signals job
+ * (companies/indigo/projects/hot-signal-sync/design/bot-replies.md).
+ *
+ * Every reply is plain prose followed by ONE `hq-block` fence whose JSON is on
+ * one line: `{"v":1,"blocks":[...]}`. Block kinds, tones and icons come from
+ * closed enums. Values come only from the run record; a value the record does
+ * not carry drops its row. Pure functions: no clock, no I/O.
+ */
+export const REPLY_BLOCK_KINDS = ["keyValue", "callout", "badge", "progress", "decision"];
+export const REPLY_TONES = ["neutral", "info", "success", "warning", "danger"];
+export const REPLY_ICONS = ["check", "clock", "folder", "calendar"];
+/** One fence, JSON on one line, not indented. */
+export function hqBlockFence(blocks) {
+    return "```hq-block\n" + JSON.stringify({ v: 1, blocks }) + "\n```";
+}
+function build(prose, blocks, variant) {
+    return { text: `${prose}\n\n${hqBlockFence(blocks)}`, prose, blocks, variant };
+}
+/** "6:02 AM" in the given zone. */
+export function timeInWords(iso, timeZone) {
+    if (!iso)
+        return null;
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return new Intl.DateTimeFormat("en-US", { timeZone, hour: "numeric", minute: "2-digit", hour12: true })
+        .format(d)
+        .replace(/\u202f/g, " ");
+}
+/** "Mountain Time" from America/Denver: the long generic zone name, without "Standard"/"Daylight". */
+export function timezoneInWords(timeZone, at = new Date()) {
+    const name = (style) => {
+        try {
+            const part = new Intl.DateTimeFormat("en-US", { timeZone, timeZoneName: style })
+                .formatToParts(at)
+                .find((p) => p.type === "timeZoneName");
+            return part?.value ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const generic = name("longGeneric");
+    if (generic && !/^GMT/.test(generic))
+        return generic;
+    const long = name("long");
+    if (long && !/^GMT/.test(long))
+        return long.replace(/ (Standard|Daylight) /, " ");
+    return timeZone;
+}
+function titleCase(slug) {
+    return slug
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join(" ");
+}
+const ADAPTER_LABELS = {
+    meetings: "meetings",
+    granola: "meetings",
+    gmail: "email",
+    email: "email",
+    slack: "Slack",
+    linear: "Linear",
+    notion: "Notion",
+};
+const STEP_DOING = {
+    garden: "Tidying candidates",
+    adapters: "Reading sources",
+    extract: "Finding signals",
+    upload: "Uploading",
+};
+const STEP_NOUN = {
+    garden: "candidate tidying",
+    adapters: "source reading",
+    extract: "signals",
+    upload: "upload",
+};
+/** The engine's step order (engine.ts STEP_ORDER), for the "Not run" row. */
+const STEP_ORDER_NAMES = ["garden", "adapters", "extract", "garden", "upload"];
+function steps(record, name) {
+    return record.steps.filter((s) => s.name === name);
+}
+function companiesValue(summary, opts) {
+    const names = summary.companies
+        .filter((c) => c.status !== "skipped")
+        .map((c) => opts.companyNames?.[c.company] ?? titleCase(c.company));
+    return names.length ? names.join(", ") : null;
+}
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** The four keyValue rows, dropping any the record does not carry. */
+export function runCountItems(record, summary, opts) {
+    const items = [];
+    const companies = companiesValue(summary, opts);
+    if (companies)
+        items.push({ key: "Companies", value: companies });
+    const extract = steps(record, "extract").find((s) => s.status !== "skipped");
+    const adapters = steps(record, "adapters").find((s) => s.status !== "skipped");
+    const read = extract ? extract.itemsIn : adapters ? adapters.itemsOut : null;
+    if (read !== null) {
+        const parts = Object.entries(adapters?.byAdapter ?? {})
+            .reduce((m, [k, v]) => m.set(ADAPTER_LABELS[k] ?? k, (m.get(ADAPTER_LABELS[k] ?? k) ?? 0) + v), new Map());
+        const breakdown = [...parts].map(([k, v]) => `${k} ${v}`).join(", ");
+        items.push({ key: "Sources read", value: `${plural(read, "item")}${breakdown ? ` (${breakdown})` : ""}` });
+    }
+    if (extract)
+        items.push({ key: "Signals found", value: String(extract.itemsOut) });
+    const garden = steps(record, "garden").filter((s) => s.status !== "skipped");
+    if (garden.length) {
+        const tidied = garden.reduce((n, s) => n + s.itemsIn, 0);
+        const waiting = garden[garden.length - 1].itemsOut;
+        items.push({ key: "Candidates tidied", value: `${tidied}, ${waiting === 0 ? "none left waiting" : `${waiting} left waiting`}` });
+    }
+    return items;
+}
+function spendUsd(record) {
+    return record.steps.reduce((n, s) => n + (s.estimatedSpendUsd ?? 0), 0);
+}
+function spendBlock(record) {
+    if (!(record.maxBudgetUsd > 0))
+        return null;
+    const spend = spendUsd(record);
+    const value = Math.max(0, Math.min(100, Math.round((spend / record.maxBudgetUsd) * 100)));
+    return {
+        kind: "progress",
+        value,
+        label: `Spend $${spend.toFixed(2)} of the $${record.maxBudgetUsd.toFixed(2)} cap`,
+        tone: "neutral",
+    };
+}
+function openBriefDecision(date) {
+    return {
+        kind: "decision",
+        questionId: `signals-run-${date}-open-brief`,
+        question: "Your brief builds next.",
+        options: [{ id: "open-brief", label: "Create today's brief", recommended: true }],
+        allowOther: false,
+    };
+}
+/** "a, b and c". */
+function listInWords(parts) {
+    if (parts.length <= 1)
+        return parts.join("");
+    return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+function capitalize(text) {
+    return text ? text[0].toUpperCase() + text.slice(1) : text;
+}
+/**
+ * What the member can do about a failed or partial run. The detail
+ * (reconnect, signed-out) is on the failing step; the record carries only the
+ * coarse v2 kind (auth, config, transient).
+ */
+function failureGuidance(record, failed, company) {
+    const stepKind = failed?.errorKind ?? record.steps.find((s) => s.status === "failed" || s.status === "partial")?.errorKind;
+    if (stepKind === "reconnect")
+        return `A connection for ${company} needs reconnecting.`;
+    if (stepKind === "signed-out")
+        return "You are signed out of HQ. Sign in again with hq login.";
+    if (record.errorKind === "auth")
+        return `A connection for ${company} needs signing in again.`;
+    if (record.errorKind === "config")
+        return `Something in the signals setup for ${company} needs fixing first.`;
+    if (record.errorKind === "transient")
+        return "This looks temporary.";
+    return failed ? `${STEP_DOING[failed.name]} for ${company} failed.` : `Signals for ${company} failed.`;
+}
+/** First sentence of an error, trimmed to one plain line. */
+function oneSentence(text) {
+    const line = text.split(/\r?\n/).find((l) => l.trim())?.trim() ?? text.trim();
+    const m = /^(.+?[.!?])(\s|$)/.exec(line);
+    return (m ? m[1] : line).slice(0, 160);
+}
+/** partialReason in words: "step-failed:extract" -> "Finding signals failed." */
+function partialReasonInWords(reason) {
+    const m = /^step-(failed|partial):(\w+)$/.exec(reason);
+    if (m && m[2] in STEP_DOING) {
+        const doing = STEP_DOING[m[2]];
+        return m[1] === "failed" ? `${doing} failed.` : `${doing} finished with problems.`;
+    }
+    return reason;
+}
+const SKIPPED_BADGE = { kind: "badge", label: "Skipped", tone: "neutral" };
+/**
+ * The reply for one finished run of the signals job: run complete, catch-up,
+ * late start, finished with problems, or run failed (bot-replies.md sections
+ * 2, 2b and 3; status mapping from run-record-contract-v2.md).
+ *
+ * A failure offers "Wait for <time>" only when `retryScheduled` says the bot
+ * really scheduled the retry at the record's `nextRetryAt`. Without it (config
+ * and auth failures have no nextRetryAt, and an automatic retry is never
+ * retried again) the only option is "Try now".
+ */
+export function formatRunReply(record, summary, opts) {
+    const job = opts.jobName ?? "Morning signals";
+    const tz = opts.timeZone;
+    const finished = timeInWords(record.finishedAt, tz) ?? timeInWords(summary.finishedAt, tz) ?? "an unknown time";
+    const company = opts.companyNames?.[record.company] ?? titleCase(record.company);
+    if (record.alreadyRanToday) {
+        const ranAt = timeInWords(record.jobRanAt, tz) ?? finished;
+        return build(`${job} already ran today, at ${ranAt}. Nothing new to do.`, [
+            { kind: "badge", label: "Already ran today", tone: "neutral", icon: "check" },
+        ], "already-ran");
+    }
+    if (record.status === "skipped") {
+        const reason = record.skipReason ?? record.skippedReason ?? null;
+        if (reason === "prefs-off") {
+            return build(`${job} did not run for ${company}: signals and ontology capture are both off.`, [
+                SKIPPED_BADGE,
+                { kind: "callout", tone: "info", body: `Turn on signals_capture or ontology_capture for ${company} to include it.` },
+            ], "skipped");
+        }
+        if (reason === "signals-off") {
+            return build(`${job} did not run for ${company}: signals are off.`, [SKIPPED_BADGE], "skipped");
+        }
+        if (reason === "late-start") {
+            return build(`${job} started too late in the day, so nothing ran for ${company}.`, [SKIPPED_BADGE], "skipped");
+        }
+        return build(`${job} had nothing to run for ${company}.`, [SKIPPED_BADGE], "skipped");
+    }
+    const failedStep = record.steps.find((s) => s.status === "failed");
+    if (record.status === "failed") {
+        const retry = opts.retryScheduled ? timeInWords(record.nextRetryAt, tz) : null;
+        const blocks = [];
+        const title = failedStep?.error
+            ? oneSentence(failedStep.error)
+            : record.failureReason
+                ? oneSentence(record.failureReason)
+                : `Signals for ${company} failed.`;
+        const brief = "Your brief is not built until signals finish, so you never read a brief without fresh signals.";
+        const retryLine = retry
+            ? `I try again at ${retry}.`
+            : opts.wasRetry
+                ? "This was the automatic retry, so I do not try again before the next scheduled run."
+                : "I do not retry this on my own.";
+        const guidance = failureGuidance(record, failedStep, company);
+        const body = [retry && record.errorKind === "transient" ? `${guidance} Nothing for you to do.` : guidance, brief, retryLine].join(" ");
+        blocks.push({ kind: "callout", tone: "danger", title, body });
+        const idx = failedStep ? record.steps.indexOf(failedStep) : record.steps.length;
+        const done = record.steps.slice(0, idx).filter((s) => s.status === "ok" || s.status === "partial");
+        const rows = [];
+        const gardenDone = done.filter((s) => s.name === "garden");
+        if (gardenDone.length) {
+            const n = gardenDone.reduce((a, s) => a + s.itemsIn, 0);
+            const count = summary.companies.filter((c) => c.status !== "skipped").length;
+            rows.push({ key: "Finished", value: `Candidates tidied: ${n}${count > 1 ? ` across ${count} companies` : ""}` });
+        }
+        if (failedStep)
+            rows.push({ key: "Stopped at", value: `${STEP_DOING[failedStep.name]} for ${company}` });
+        const notRun = [...new Set(STEP_ORDER_NAMES.slice(record.steps.length).filter((n) => n !== "garden").map((n) => STEP_NOUN[n]))];
+        if (notRun.length)
+            rows.push({ key: "Not run", value: capitalize(listInWords(notRun)) });
+        if (rows.length)
+            blocks.push({ kind: "keyValue", items: rows });
+        blocks.push(retry
+            ? {
+                kind: "decision",
+                questionId: `signals-run-${summary.date}-retry`,
+                question: "Try again now, or wait for the retry?",
+                options: [
+                    { id: "try-now", label: "Try now", recommended: true },
+                    { id: "wait", label: `Wait for ${retry}` },
+                ],
+                allowOther: false,
+            }
+            : {
+                kind: "decision",
+                questionId: `signals-run-${summary.date}-retry`,
+                question: "Try again now?",
+                options: [{ id: "try-now", label: "Try now", recommended: true }],
+                allowOther: false,
+            });
+        return build(`${job} stopped at ${finished}.`, blocks, "failed");
+    }
+    const counts = runCountItems(record, summary, opts);
+    const spend = spendBlock(record);
+    const tail = [
+        ...(counts.length ? [{ kind: "keyValue", items: counts }] : []),
+        ...(spend ? [spend] : []),
+    ];
+    const due = timeInWords(opts.scheduledFor, tz);
+    const catchUpBadge = { kind: "badge", label: "Catch-up", tone: "warning", icon: "clock" };
+    const partialReason = record.partialReason ?? record.partial ?? null;
+    if (partialReason === "late-start") {
+        const catchUpLine = record.catchUp && due ? ` Your Mac was asleep at ${due}, so this was a catch-up run.` : "";
+        return build(`${job} started after 10 PM, so I only tidied candidates tonight. The full run happens at ${due ?? "the next scheduled time"}.${catchUpLine}`, [
+            { kind: "badge", label: "Late start, garden only", tone: "warning", icon: "clock" },
+            ...(record.catchUp ? [catchUpBadge] : []),
+            ...tail,
+        ], "late-start");
+    }
+    if (record.status === "partial") {
+        const title = record.failureReason
+            ? oneSentence(record.failureReason)
+            : partialReason
+                ? partialReasonInWords(partialReason)
+                : null;
+        const body = `${failureGuidance(record, failedStep, company)} Your brief builds with what came in. Say "Try now" to run signals again.`;
+        return build(`${job} finished with problems at ${finished}.`, [
+            { kind: "badge", label: "Finished with problems", tone: "warning" },
+            ...(record.catchUp ? [catchUpBadge] : []),
+            title ? { kind: "callout", tone: "warning", title, body } : { kind: "callout", tone: "warning", body },
+            ...tail,
+            openBriefDecision(summary.date),
+        ], "partial");
+    }
+    if (record.catchUp) {
+        const prose = due
+            ? `${job} finished at ${finished} instead of ${due}. Your Mac was asleep at ${due}, so I ran it when it woke.`
+            : `${job} finished at ${finished}, later than scheduled. Your Mac was asleep, so I ran it when it woke.`;
+        return build(prose, [catchUpBadge, ...tail, openBriefDecision(summary.date)], "catch-up");
+    }
+    return build(`${job} finished at ${finished}.`, [{ kind: "badge", label: "Complete", tone: "success", icon: "check" }, ...tail, openBriefDecision(summary.date)], "complete");
+}
+/** Another run holds the company's lock (engine exit 3): nothing was started. */
+export function formatLockedReply(locked, opts) {
+    const job = opts.jobName ?? "Morning signals";
+    const company = opts.companyNames?.[locked.company] ?? titleCase(locked.company);
+    const started = timeInWords(locked.startedAt, opts.timeZone);
+    return build(`${job} for ${company} is already running${started ? ` (a ${locked.trigger} run started at ${started})` : ""}. I did not start a second one.`, [{ kind: "badge", label: "Running", tone: "info", icon: "clock" }], "running");
+}
+/** A job that could not run the engine at all: the prose, then one danger callout with the reason. */
+export function formatJobErrorReply(prose, reason) {
+    return build(prose, [{ kind: "callout", tone: "danger", body: reason }], "failed");
+}
+/** "Every day at 6:00 AM" from a daily cron; null when the cron is not a plain daily or weekday time. */
+export function scheduleInWords(cron) {
+    const m = /^cron\((.+)\)$/.exec(cron.trim());
+    const fields = (m ? m[1] : cron).trim().split(/\s+/);
+    const [min, hour, dom, , dow] = fields;
+    if (!min || !hour || !/^\d+$/.test(min) || !/^\d+$/.test(hour))
+        return null;
+    if (dom !== "*" && dom !== "?")
+        return null;
+    const h = Number(hour);
+    const t = `${((h + 11) % 12) + 1}:${min.padStart(2, "0")} ${h < 12 ? "AM" : "PM"}`;
+    if (dow === "*" || dow === "?" || dow === undefined)
+        return `Every day at ${t}`;
+    if (dow === "1-5" || dow === "MON-FRI")
+        return `Every weekday at ${t}`;
+    return null;
+}
+/** The job-created reply (bot-replies.md section 1). The zone comes from the job record, in words. */
+export function formatJobCreatedReply(job, timezoneWords = timezoneInWords(job.timezone)) {
+    const name = job.name ?? "Morning signals";
+    const when = scheduleInWords(job.cron);
+    const items = [];
+    if (when)
+        items.push({ key: "Runs", value: `${when}, ${timezoneWords}`, icon: "clock" });
+    if (job.companies?.length)
+        items.push({ key: "Covers", value: job.companies.join(", "), icon: "folder" });
+    if (job.hasBriefJob)
+        items.push({ key: "Then", value: "Your daily brief, which now waits for it", icon: "calendar" });
+    const at = when ? when.replace(/^Every (day|weekday) at /, "") : "the scheduled time";
+    const blocks = [];
+    if (items.length)
+        blocks.push({ kind: "keyValue", items });
+    blocks.push({
+        kind: "callout",
+        tone: "info",
+        body: `If your Mac is asleep at ${at}, I run it as soon as it wakes and mark that run a catch-up. The job and its last run are under Bot jobs on my profile.`,
+    });
+    return build(`Done. I set up a job called ${name}.`, blocks, "complete");
+}
+//# sourceMappingURL=reply.js.map

package/dist/lib/signals/run-lock.d.ts

@@ -0,0 +1,36 @@
+export declare const LOCK_STALE_MS: number;
+export interface LockHolder {
+    pid: number;
+    startedAt: string;
+    trigger: string;
+}
+export interface LockTakeover extends LockHolder {
+    takenOverAt: string;
+    reason: "pid-dead" | "expired" | "unreadable";
+}
+export type AcquireResult = {
+    ok: true;
+    takeover: LockTakeover | null;
+    release: () => void;
+} | {
+    ok: false;
+    holder: LockHolder;
+};
+export declare function companyLockRel(date: string, company: string): string;
+/** process.kill(pid, 0): ESRCH means gone; EPERM means alive under another user. */
+export declare function defaultIsPidAlive(pid: number): boolean;
+export declare function acquireCompanyLock(input: {
+    hqRoot: string;
+    date: string;
+    company: string;
+    trigger: string;
+    now: () => Date;
+    isPidAlive?: (pid: number) => boolean;
+}): AcquireResult;
+/**
+ * Short exclusive section around a read-modify-write of summary.json, so
+ * two runs for different companies cannot drop each other's entry. The
+ * lock is held for milliseconds; one older than 30 seconds is stale.
+ */
+export declare function withSummaryLock<T>(hqRoot: string, date: string, fn: () => T): T;
+//# sourceMappingURL=run-lock.d.ts.map

package/dist/lib/signals/run-lock.js

@@ -0,0 +1,148 @@
+/**
+ * Per-company run lock and the summary lock for the signals engine
+ * (run record contract v2).
+ *
+ * Lock file: workspace/signals/runs/{date}/{company}.lock, created with
+ * O_EXCL ("wx") and holding JSON { pid, startedAt, trigger }. A lock is stale
+ * when its pid is not alive or its startedAt is older than 3 hours; a stale
+ * lock is removed and taken over, and the caller logs the takeover in the
+ * run record.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertAllowedPath } from "./write-guard.js";
+export const LOCK_STALE_MS = 3 * 60 * 60 * 1000;
+/** An unreadable lock younger than this is treated as being written right now. */
+const UNREADABLE_GRACE_MS = 60 * 1000;
+export function companyLockRel(date, company) {
+    return `workspace/signals/runs/${date}/${company}.lock`;
+}
+/** process.kill(pid, 0): ESRCH means gone; EPERM means alive under another user. */
+export function defaultIsPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function readHolder(abs) {
+    try {
+        const v = JSON.parse(fs.readFileSync(abs, "utf8"));
+        if (typeof v.pid === "number" && typeof v.startedAt === "string" && typeof v.trigger === "string") {
+            return { pid: v.pid, startedAt: v.startedAt, trigger: v.trigger };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+function createExclusive(abs, body) {
+    let fd;
+    try {
+        fd = fs.openSync(abs, "wx");
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return true;
+}
+export function acquireCompanyLock(input) {
+    const isAlive = input.isPidAlive ?? defaultIsPidAlive;
+    const abs = assertAllowedPath(input.hqRoot, companyLockRel(input.date, input.company), { company: input.company });
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    let takeover = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const mine = { pid: process.pid, startedAt: input.now().toISOString(), trigger: input.trigger };
+        if (createExclusive(abs, JSON.stringify(mine))) {
+            const release = () => {
+                const current = readHolder(abs);
+                if (current && current.pid === mine.pid && current.startedAt === mine.startedAt) {
+                    fs.rmSync(abs, { force: true });
+                }
+            };
+            return { ok: true, takeover, release };
+        }
+        const holder = readHolder(abs);
+        const nowMs = input.now().getTime();
+        let reason = null;
+        if (!holder) {
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(abs).mtimeMs;
+            }
+            catch {
+                continue; // removed between our open and stat: try again
+            }
+            if (Math.abs(Date.now() - mtimeMs) < UNREADABLE_GRACE_MS) {
+                return { ok: false, holder: { pid: 0, startedAt: new Date(mtimeMs).toISOString(), trigger: "unknown" } };
+            }
+            reason = "unreadable";
+        }
+        else if (!isAlive(holder.pid)) {
+            reason = "pid-dead";
+        }
+        else if (nowMs - Date.parse(holder.startedAt) > LOCK_STALE_MS) {
+            reason = "expired";
+        }
+        if (reason === null && holder)
+            return { ok: false, holder };
+        takeover = {
+            pid: holder?.pid ?? 0,
+            startedAt: holder?.startedAt ?? "",
+            trigger: holder?.trigger ?? "unknown",
+            takenOverAt: input.now().toISOString(),
+            reason: reason ?? "unreadable",
+        };
+        fs.rmSync(abs, { force: true });
+    }
+    const holder = readHolder(abs);
+    return { ok: false, holder: holder ?? { pid: 0, startedAt: input.now().toISOString(), trigger: "unknown" } };
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Short exclusive section around a read-modify-write of summary.json, so
+ * two runs for different companies cannot drop each other's entry. The
+ * lock is held for milliseconds; one older than 30 seconds is stale.
+ */
+export function withSummaryLock(hqRoot, date, fn) {
+    const abs = assertAllowedPath(hqRoot, `workspace/signals/runs/${date}/summary.lock`);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    for (let i = 0;; i += 1) {
+        if (createExclusive(abs, String(process.pid)))
+            break;
+        try {
+            if (Date.now() - fs.statSync(abs).mtimeMs > 30_000) {
+                fs.rmSync(abs, { force: true });
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        if (i >= 250)
+            throw new Error("hq signals: summary.json is locked by another run");
+        sleepSync(20);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(abs, { force: true });
+    }
+}
+//# sourceMappingURL=run-lock.js.map

package/dist/lib/signals/run-record.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shape check for workspace/signals/runs/{date}/{company}.json (run record
+ * contract v2). It accepts schemaVersion 2 records only. v1 records (no
+ * schemaVersion, record status "ok", detailed record errorKind) were written
+ * only by the unreleased US-002 drafts, and the engine treats a prior record
+ * without jobRanAt as "the job has not run today", so no hq-cli reader needs
+ * to accept them. Out-of-repo readers (the desktop app) handle v1 themselves,
+ * per the contract.
+ *
+ * The enum lists are typed against the engine's own types with `exhaustive`,
+ * so adding or removing a value in the engine without updating the list here
+ * is a compile error.
+ */
+import { type RunRecord } from "./engine.js";
+/** Record statuses. "dry-run" only appears on in-memory records: a dry run writes nothing. */
+export declare const RUN_STATUSES: readonly ["running", "complete", "partial", "failed", "skipped", "dry-run"];
+/** Coarse record-level error kind, set on failed and partial records only. */
+export declare const RUN_ERROR_KINDS: readonly ["transient", "config", "auth"];
+export declare const STEP_NAMES: readonly ["garden", "adapters", "extract", "upload"];
+export declare const STEP_STATUSES: readonly ["ok", "skipped", "failed", "partial"];
+/** Detailed per-step error kind. */
+export declare const STEP_ERROR_KINDS: readonly ["reconnect", "signed-out", "transient", "config", "other"];
+export declare function isRunRecord(v: unknown): v is RunRecord;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/lib/signals/run-record.js

@@ -0,0 +1,82 @@
+/**
+ * Shape check for workspace/signals/runs/{date}/{company}.json (run record
+ * contract v2). It accepts schemaVersion 2 records only. v1 records (no
+ * schemaVersion, record status "ok", detailed record errorKind) were written
+ * only by the unreleased US-002 drafts, and the engine treats a prior record
+ * without jobRanAt as "the job has not run today", so no hq-cli reader needs
+ * to accept them. Out-of-repo readers (the desktop app) handle v1 themselves,
+ * per the contract.
+ *
+ * The enum lists are typed against the engine's own types with `exhaustive`,
+ * so adding or removing a value in the engine without updating the list here
+ * is a compile error.
+ */
+import { RUN_RECORD_SCHEMA_VERSION, SIGNALS_TRIGGERS } from "./engine.js";
+/**
+ * Returns the list unchanged. Fails to compile when the list holds a value
+ * outside Union, or misses one of Union's members.
+ */
+const exhaustive = () => (list) => list;
+/** Record statuses. "dry-run" only appears on in-memory records: a dry run writes nothing. */
+export const RUN_STATUSES = exhaustive()(["running", "complete", "partial", "failed", "skipped", "dry-run"]);
+/** Coarse record-level error kind, set on failed and partial records only. */
+export const RUN_ERROR_KINDS = exhaustive()(["transient", "config", "auth"]);
+export const STEP_NAMES = exhaustive()(["garden", "adapters", "extract", "upload"]);
+export const STEP_STATUSES = exhaustive()(["ok", "skipped", "failed", "partial"]);
+/** Detailed per-step error kind. */
+export const STEP_ERROR_KINDS = exhaustive()(["reconnect", "signed-out", "transient", "config", "other"]);
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const oneOf = (list, v) => typeof v === "string" && list.includes(v);
+const strOrNull = (v) => v === null || typeof v === "string";
+const optional = (v, check) => v === undefined || check(v);
+function isStepRecord(v) {
+    return (isObj(v) &&
+        oneOf(STEP_NAMES, v.name) &&
+        oneOf(STEP_STATUSES, v.status) &&
+        isNum(v.itemsIn) &&
+        isNum(v.itemsOut) &&
+        isNum(v.durationMs) &&
+        optional(v.errorKind, (k) => oneOf(STEP_ERROR_KINDS, k)));
+}
+const isCounts = (v) => isObj(v) && isNum(v.sourcesIn) && isNum(v.signalsOut);
+export function isRunRecord(v) {
+    if (!isObj(v))
+        return false;
+    const shape = v.schemaVersion === RUN_RECORD_SCHEMA_VERSION &&
+        typeof v.company === "string" &&
+        v.company.length > 0 &&
+        typeof v.startedAt === "string" &&
+        strOrNull(v.finishedAt) &&
+        oneOf(SIGNALS_TRIGGERS, v.trigger) &&
+        isNum(v.pid) &&
+        typeof v.catchUp === "boolean" &&
+        typeof v.dryRun === "boolean" &&
+        oneOf(RUN_STATUSES, v.status) &&
+        strOrNull(v.skipReason) &&
+        optional(v.skippedReason, (x) => typeof x === "string") &&
+        (v.currentStep === null || oneOf(STEP_NAMES, v.currentStep)) &&
+        Array.isArray(v.steps) &&
+        v.steps.every(isStepRecord) &&
+        isNum(v.maxBudgetUsd) &&
+        isNum(v.maxTurns) &&
+        strOrNull(v.jobRanAt) &&
+        strOrNull(v.nextRetryAt) &&
+        (v.errorKind === null || oneOf(RUN_ERROR_KINDS, v.errorKind)) &&
+        strOrNull(v.failureReason) &&
+        strOrNull(v.partialReason) &&
+        strOrNull(v.partial) &&
+        typeof v.alreadyRanToday === "boolean" &&
+        isCounts(v.counts) &&
+        optional(v.lockTakeover, isObj);
+    if (!shape)
+        return false;
+    // Contract invariants: finishedAt is null exactly while running, and the
+    // record-level errorKind is only set on failed and partial records.
+    if ((v.status === "running") !== (v.finishedAt === null))
+        return false;
+    if (v.errorKind !== null && v.status !== "failed" && v.status !== "partial")
+        return false;
+    return true;
+}
+//# sourceMappingURL=run-record.js.map