@indigoai-us/hq-cli 5.345.191 → 5.345.194

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

@@ -0,0 +1,105 @@
+export declare const SANITIZED_CONTRIBUTION_SCHEMA = "sanitized-contribution.v1";
+export declare const SANITIZER_VERSION = "local-sanitizer/v1";
+export declare const SCHEMA_VERSION = "local-signal/v1";
+export declare const DEFAULT_PROMPT_VERSION = "hq-signals-extract/v1";
+export declare const MEMBER_SIGNALS_ROOT = "member-signals/";
+export declare const SIGNAL_TYPES: readonly ["summary", "key_point", "decision", "action_item", "participant_contribution", "risk", "commitment", "question"];
+export type SignalType = (typeof SIGNAL_TYPES)[number];
+export declare const MAX_CONTENT_CHARS = 600;
+export declare const MAX_CITATIONS = 8;
+export declare const MAX_ENTITIES = 16;
+export declare const MAX_FIELD_CHARS = 256;
+export declare const MEETING_SOURCE_RE: RegExp;
+export interface SanitizedContributionV1 {
+    schema: string;
+    sanitizerVersion: string;
+    observationId: string;
+    signalType: SignalType;
+    content: string;
+    citations: Array<{
+        startMs: number;
+        endMs: number;
+    }>;
+    sourceRef: string;
+    sourceDigest: string;
+    entityRefs: string[];
+    provisionalEntities: string[];
+    owner?: string;
+    reasoning?: string;
+    speaker?: string;
+    companyUid: string;
+    memberUid: string;
+    audienceKey: string;
+    audienceVersion: number;
+    audienceReceiptRef: string;
+    promptVersion: string;
+    schemaVersion: string;
+    classification: string;
+    projectionState: string;
+    projectionWatermark: string;
+}
+/** Same key set as hq-pro CONTRIBUTION_KEYS. */
+export declare const CONTRIBUTION_KEYS: ReadonlySet<string>;
+export declare function normalizeContent(s: string): string;
+export declare function computeObservationId(c: {
+    memberUid: string;
+    sourceRef: string;
+    sourceDigest: string;
+    signalType: string;
+    audienceKey: string;
+    content: string;
+    promptVersion: string;
+    schemaVersion: string;
+}): string;
+export declare function sha256Digest(text: string): string;
+/** Audience keys are `sha256:<hex>`; `:` is not a key-safe path character. */
+export declare function audienceKeySegment(audienceKey: string): string;
+export declare function memberSignalsPrefix(memberUid: string): string;
+/** Canonical destination; the server requires this exact key. */
+export declare function contributionKey(memberUid: string, audienceKey: string, signalType: SignalType, observationId: string): string;
+/** Returns the list of problems; empty means the server's shape check passes. */
+export declare function validateContributionShape(raw: unknown): string[];
+/**
+ * Remove quoted passages longer than one sentence: a raw transcript excerpt
+ * of two or more sentences is replaced with `[quote removed]`.
+ */
+export declare function stripLongQuotes(s: string): string;
+/** Cap at MAX_CONTENT_CHARS code points, cutting at a word boundary. */
+export declare function capContent(s: string, max?: number): string;
+/** `HH:MM:SS`, `MM:SS`, or seconds → milliseconds. */
+export declare function parseLocationMs(v: unknown): number | null;
+export declare function splitFrontmatter(text: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+export interface AudienceReceiptLocal {
+    ref: string;
+    audienceKey: string;
+    audienceVersion: number;
+    sourceDigest: string;
+    invitedMemberUids: string[];
+}
+/** Highest-version audience receipt for a meeting, read from the local company tree. */
+export declare function readAudienceReceipt(companyRoot: string, meetingId: string): AudienceReceiptLocal | null;
+export interface SanitizeInput {
+    /** Absolute path of `companies/{co}`. */
+    companyRoot: string;
+    /** Company-relative path of the signal: `signals/@{key}/{type}/{sha}.md` or `signals/{type}/{sha}.md`. */
+    signalRel: string;
+    memberUid: string;
+    companyUid: string;
+    projectionState: string;
+    projectionWatermark: string;
+}
+export type SanitizeResult = {
+    ok: true;
+    contribution: SanitizedContributionV1;
+    destination: string;
+    sha: string;
+} | {
+    ok: false;
+    reason: string;
+    sha: string;
+};
+export declare function sanitizeSignal(input: SanitizeInput): SanitizeResult;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/lib/signals/sanitize.js

@@ -0,0 +1,439 @@
+/**
+ * TypeScript sanitizer for local promoted signals (Hot-Signal Sync US-005).
+ *
+ * Turns `companies/{co}/signals/@{key}/{type}/{sha}.md` (or
+ * `signals/{type}/{sha}.md`, audience `company`) into a
+ * `sanitized-contribution.v1` object, the body hq-pro's
+ * `POST /v1/files/contributions/company/{slug}/meetings` accepts.
+ *
+ * The shape, caps and observation id mirror hq-pro
+ * `src/signals/member-contributions/contribution.ts` (origin/main 9f172092d)
+ * exactly: the server rejects anything else with CONTRIBUTION_REJECTED. The
+ * desktop's Rust sanitizer (`local_signals/sanitize.rs`) is the reference
+ * producer; this file is its CLI twin.
+ *
+ * What the contribution never carries to member-signals: citation quote text,
+ * the signal body beyond MAX_CONTENT_CHARS, quoted passages longer than one
+ * sentence, and any field not in CONTRIBUTION_KEYS.
+ *
+ * This limits the contribution only. Hot-Signal Sync does not change vault
+ * sync (owner decision 2026-11-01: "we shouldn't interrupt existing processes
+ * until we are sure things are working"). The promoted signal file itself
+ * (companies/{co}/signals/@{key}/{type}/{sha}.md, with its full body and
+ * citation quotes) and company sources/ stay local today, because hq-cloud
+ * refuses client uploads of signals/** and sources/**. Sharing promoted
+ * signals with the company through audience ACLs is a later, separate
+ * hq-cloud change. The signals and ontology _candidates folders are in the
+ * shipped .hqignore.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+export const SANITIZED_CONTRIBUTION_SCHEMA = "sanitized-contribution.v1";
+export const SANITIZER_VERSION = "local-sanitizer/v1";
+export const SCHEMA_VERSION = "local-signal/v1";
+export const DEFAULT_PROMPT_VERSION = "hq-signals-extract/v1";
+export const MEMBER_SIGNALS_ROOT = "member-signals/";
+const OBSERVATION_ID_DOMAIN = "hq-local-meeting-observation-id/v1";
+export const SIGNAL_TYPES = [
+    "summary",
+    "key_point",
+    "decision",
+    "action_item",
+    "participant_contribution",
+    "risk",
+    "commitment",
+    "question",
+];
+export const MAX_CONTENT_CHARS = 600;
+export const MAX_CITATIONS = 8;
+export const MAX_ENTITIES = 16;
+export const MAX_FIELD_CHARS = 256;
+const MAX_ENTITY_CHARS = 200;
+const UID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const SEGMENT_RE = /^[A-Za-z0-9_.-]{1,256}$/;
+const OBSERVATION_ID_RE = /^[0-9a-f]{64}$/;
+export const MEETING_SOURCE_RE = /^sources\/meetings\/([^/\\]+)\.md$/;
+/** Same key set as hq-pro CONTRIBUTION_KEYS. */
+export const CONTRIBUTION_KEYS = new Set([
+    "schema", "sanitizerVersion", "observationId", "signalType", "content", "citations", "sourceRef",
+    "sourceDigest", "entityRefs", "provisionalEntities", "owner", "reasoning", "speaker", "companyUid",
+    "memberUid", "audienceKey", "audienceVersion", "audienceReceiptRef", "promptVersion", "schemaVersion",
+    "classification", "projectionState", "projectionWatermark",
+]);
+// ── identity (byte-for-byte with hq-pro) ─────────────────────────────────────
+const WHITE_SPACE_RE = new RegExp("[" +
+    [0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20, 0x85, 0xa0, 0x1680, 0x2028, 0x2029, 0x202f, 0x205f, 0x3000]
+        .map((c) => `\\u${c.toString(16).padStart(4, "0")}`)
+        .join("") +
+    "\\u2000-\\u200a]+");
+export function normalizeContent(s) {
+    return s
+        .split(WHITE_SPACE_RE)
+        .filter((w) => w.length > 0)
+        .join(" ")
+        .toLowerCase();
+}
+export function computeObservationId(c) {
+    const h = createHash("sha256");
+    for (const part of [
+        OBSERVATION_ID_DOMAIN,
+        c.memberUid,
+        c.sourceRef,
+        c.sourceDigest,
+        c.signalType,
+        c.audienceKey,
+        normalizeContent(c.content),
+        c.promptVersion,
+        c.schemaVersion,
+    ]) {
+        const bytes = Buffer.from(part, "utf8");
+        const len = Buffer.alloc(8);
+        len.writeBigUInt64BE(BigInt(bytes.length));
+        h.update(len);
+        h.update(bytes);
+    }
+    return h.digest("hex");
+}
+export function sha256Digest(text) {
+    return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+/** Audience keys are `sha256:<hex>`; `:` is not a key-safe path character. */
+export function audienceKeySegment(audienceKey) {
+    return audienceKey.replace(/^sha256:/, "sha256-");
+}
+export function memberSignalsPrefix(memberUid) {
+    if (!UID_RE.test(memberUid))
+        throw new Error("invalid member uid");
+    return `${MEMBER_SIGNALS_ROOT}${memberUid}/`;
+}
+/** Canonical destination; the server requires this exact key. */
+export function contributionKey(memberUid, audienceKey, signalType, observationId) {
+    const seg = audienceKeySegment(audienceKey);
+    if (!SEGMENT_RE.test(seg) || !OBSERVATION_ID_RE.test(observationId))
+        throw new Error("invalid contribution path");
+    return `${memberSignalsPrefix(memberUid)}observations/meetings/@${seg}/${signalType}/${observationId}.md`;
+}
+// ── shape validation (mirror of hq-pro parseShape) ───────────────────────────
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function hasControlChar(v) {
+    for (const ch of v) {
+        const c = ch.codePointAt(0) ?? 0;
+        if (c < 0x20 || c === 0x7f)
+            return true;
+    }
+    return false;
+}
+function boundedString(v, max = MAX_FIELD_CHARS) {
+    return typeof v === "string" && v.trim().length > 0 && [...v].length <= max && !hasControlChar(v);
+}
+/** Returns the list of problems; empty means the server's shape check passes. */
+export function validateContributionShape(raw) {
+    const detail = [];
+    if (!isRecord(raw))
+        return ["contribution must be an object"];
+    for (const k of Object.keys(raw))
+        if (!CONTRIBUTION_KEYS.has(k))
+            detail.push(`unknown field ${k}`);
+    const str = [
+        "schema", "sanitizerVersion", "observationId", "sourceRef", "sourceDigest", "companyUid", "memberUid",
+        "audienceKey", "audienceReceiptRef", "promptVersion", "schemaVersion", "classification",
+        "projectionState", "projectionWatermark",
+    ];
+    for (const k of str)
+        if (!boundedString(raw[k]))
+            detail.push(`${k} must be a bounded string`);
+    if (!SIGNAL_TYPES.includes(raw.signalType))
+        detail.push("signalType is not a registered type");
+    if (!boundedString(raw.content, MAX_CONTENT_CHARS))
+        detail.push("content is empty or too long");
+    if (!Number.isInteger(raw.audienceVersion) || raw.audienceVersion < 1)
+        detail.push("audienceVersion must be a positive integer");
+    const cites = raw.citations;
+    if (!Array.isArray(cites) || cites.length === 0 || cites.length > MAX_CITATIONS) {
+        detail.push(`citations must hold 1-${MAX_CITATIONS} ranges`);
+    }
+    else {
+        for (const c of cites) {
+            if (!isRecord(c) || Object.keys(c).some((k) => k !== "startMs" && k !== "endMs") ||
+                !Number.isInteger(c.startMs) || !Number.isInteger(c.endMs) ||
+                c.startMs < 0 || c.startMs > c.endMs) {
+                detail.push("citation must be {startMs <= endMs}");
+                break;
+            }
+        }
+    }
+    for (const k of ["entityRefs", "provisionalEntities"]) {
+        const v = raw[k];
+        if (!Array.isArray(v) || v.length > MAX_ENTITIES || !v.every((x) => boundedString(x, MAX_ENTITY_CHARS))) {
+            detail.push(`${k} must be at most ${MAX_ENTITIES} bounded strings`);
+        }
+    }
+    for (const k of ["owner", "reasoning", "speaker"]) {
+        if (raw[k] !== undefined && !boundedString(raw[k], MAX_ENTITY_CHARS))
+            detail.push(`${k} must be a bounded string`);
+    }
+    if (raw.schema !== SANITIZED_CONTRIBUTION_SCHEMA)
+        detail.push("schema must be sanitized-contribution.v1");
+    if (raw.sanitizerVersion !== SANITIZER_VERSION)
+        detail.push("sanitizerVersion must be local-sanitizer/v1");
+    if (raw.schemaVersion !== SCHEMA_VERSION)
+        detail.push("schemaVersion must be local-signal/v1");
+    if (raw.classification !== "company-eligible")
+        detail.push("classification must be company-eligible");
+    return detail;
+}
+// ── text scrubbing ───────────────────────────────────────────────────────────
+/** Collapse all whitespace (and control characters) to single spaces. */
+function flatten(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u001f\u007f]+/g, " ").split(WHITE_SPACE_RE).filter(Boolean).join(" ").trim();
+}
+function sentenceCount(s) {
+    return s.split(/[.!?]+(?:\s+|$)/).filter((x) => x.trim().length > 0).length;
+}
+/**
+ * Remove quoted passages longer than one sentence: a raw transcript excerpt
+ * of two or more sentences is replaced with `[quote removed]`.
+ */
+export function stripLongQuotes(s) {
+    const patterns = [/"([^"]*)"/g, /“([^”]*)”/g, /^>.*$/gm];
+    let out = s;
+    out = out.replace(patterns[2], (m) => (sentenceCount(m.replace(/^>\s?/, "")) > 1 ? "[quote removed]" : m.replace(/^>\s?/, "")));
+    for (const re of patterns.slice(0, 2)) {
+        out = out.replace(re, (m, inner) => (sentenceCount(inner) > 1 ? "[quote removed]" : m));
+    }
+    return out;
+}
+/** Strip markdown headings and emphasis; keep the words. */
+function stripMarkdown(s) {
+    return s
+        .replace(/^#{1,6}\s+.*$/gm, " ")
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/__([^_]+)__/g, "$1")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/^\s*[-*]\s+/gm, "");
+}
+/** Cap at MAX_CONTENT_CHARS code points, cutting at a word boundary. */
+export function capContent(s, max = MAX_CONTENT_CHARS) {
+    const chars = [...s];
+    if (chars.length <= max)
+        return s;
+    const cut = chars.slice(0, max - 1).join("");
+    const space = cut.lastIndexOf(" ");
+    return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+function boundedOrUndefined(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const f = flatten(v);
+    return f.length > 0 && [...f].length <= MAX_ENTITY_CHARS ? f : undefined;
+}
+function stringList(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const x of v) {
+        const s = typeof x === "string" ? x : isRecord(x) && typeof x.name === "string" ? x.name : null;
+        const b = s === null ? undefined : boundedOrUndefined(s);
+        if (b && !out.includes(b))
+            out.push(b);
+        if (out.length >= MAX_ENTITIES)
+            break;
+    }
+    return out;
+}
+/** `HH:MM:SS`, `MM:SS`, or seconds → milliseconds. */
+export function parseLocationMs(v) {
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+        return Math.round(v * 1000);
+    if (typeof v !== "string")
+        return null;
+    const m = /^\s*(?:(\d+):)?(\d{1,2}):(\d{2}(?:\.\d+)?)\s*$/.exec(v);
+    if (!m)
+        return null;
+    const h = m[1] ? Number(m[1]) : 0;
+    return Math.round((h * 3600 + Number(m[2]) * 60 + Number(m[3])) * 1000);
+}
+function citationRanges(raw, sourceRef) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const c of raw) {
+        if (!isRecord(c))
+            continue;
+        if (typeof c.source_ref === "string" && c.source_ref !== sourceRef)
+            continue;
+        const start = Number.isInteger(c.start_ms) ? c.start_ms : Number.isInteger(c.startMs) ? c.startMs : parseLocationMs(c.location ?? c.timestamp);
+        if (start === null || start < 0)
+            continue;
+        const endRaw = Number.isInteger(c.end_ms) ? c.end_ms : Number.isInteger(c.endMs) ? c.endMs : null;
+        const end = endRaw !== null && endRaw >= start ? endRaw : start;
+        out.push({ startMs: start, endMs: end });
+        if (out.length >= MAX_CITATIONS)
+            break;
+    }
+    return out;
+}
+// ── local files ──────────────────────────────────────────────────────────────
+export function splitFrontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!m)
+        return { frontmatter: {}, body: text };
+    let parsed;
+    try {
+        parsed = yaml.load(m[1]);
+    }
+    catch {
+        parsed = null;
+    }
+    return { frontmatter: isRecord(parsed) ? parsed : {}, body: m[2] };
+}
+/** Highest-version audience receipt for a meeting, read from the local company tree. */
+export function readAudienceReceipt(companyRoot, meetingId) {
+    const dir = path.join(companyRoot, "sources", "meetings");
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const n of names) {
+        if (!n.startsWith(`${meetingId}.audience`))
+            continue;
+        const m = n === `${meetingId}.audience.json` ? ["", "1"] : new RegExp(`^${meetingId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.audience\\.v(\\d+)\\.json$`).exec(n);
+        if (!m)
+            continue;
+        const v = Number(m[1]);
+        if (!best || v > best.version)
+            best = { version: v, name: n };
+    }
+    if (!best)
+        return null;
+    try {
+        const r = JSON.parse(fs.readFileSync(path.join(dir, best.name), "utf8"));
+        if (typeof r.audienceKey !== "string" || !Number.isInteger(r.audienceVersion) || typeof r.sourceDigest !== "string")
+            return null;
+        return {
+            ref: `sources/meetings/${best.name}`,
+            audienceKey: r.audienceKey,
+            audienceVersion: r.audienceVersion,
+            sourceDigest: r.sourceDigest,
+            invitedMemberUids: Array.isArray(r.invitedMemberUids) ? r.invitedMemberUids.filter((x) => typeof x === "string") : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const SIGNAL_REL_RE = /^signals\/(?:@([^/]+)\/)?([a-z_]+)\/([^/]+)\.md$/;
+export function sanitizeSignal(input) {
+    const m = SIGNAL_REL_RE.exec(input.signalRel);
+    const sha = m?.[3] ?? path.basename(input.signalRel, ".md");
+    const fail = (reason) => ({ ok: false, reason, sha });
+    if (!m)
+        return fail("not-a-signal-path");
+    const folderType = m[2];
+    let text;
+    try {
+        text = fs.readFileSync(path.join(input.companyRoot, input.signalRel), "utf8");
+    }
+    catch {
+        return fail("unreadable");
+    }
+    const { frontmatter: fm, body } = splitFrontmatter(text);
+    const signalType = (typeof fm.type === "string" ? fm.type : folderType);
+    if (!SIGNAL_TYPES.includes(signalType) || signalType !== folderType)
+        return fail("unknown-type");
+    const sourceRef = typeof fm.source_ref === "string" ? fm.source_ref : "";
+    const meeting = MEETING_SOURCE_RE.exec(sourceRef);
+    if (!meeting)
+        return fail("non-meeting-source");
+    const receipt = readAudienceReceipt(input.companyRoot, meeting[1]);
+    if (!receipt)
+        return fail("no-audience-receipt");
+    if (!receipt.invitedMemberUids.includes(input.memberUid))
+        return fail("not-in-audience");
+    // sourceDigest: sha256 of the local source body when readable. The server
+    // checks the digest against the frozen receipt and its own bucket copy, so
+    // when the local copy differs (edited, or parsed with different frontmatter
+    // rules) the receipt's frozen digest is the one that can pass.
+    let sourceDigest = receipt.sourceDigest;
+    try {
+        const src = fs.readFileSync(path.join(input.companyRoot, sourceRef), "utf8");
+        const local = sha256Digest(splitFrontmatter(src).body);
+        if (local === receipt.sourceDigest)
+            sourceDigest = local;
+    }
+    catch {
+        // Source not on disk: the receipt's frozen digest stands.
+    }
+    const citations = citationRanges(fm.citations, sourceRef);
+    if (citations.length === 0)
+        return fail("no-timestamps");
+    const rawContent = typeof fm.canonical_content === "string" && fm.canonical_content.trim()
+        ? fm.canonical_content
+        : stripMarkdown(body);
+    const content = capContent(flatten(stripLongQuotes(rawContent)));
+    if (!content)
+        return fail("empty-content");
+    const promptVersion = boundedOrUndefined(fm.prompt_version) ?? DEFAULT_PROMPT_VERSION;
+    const entityRefs = stringList(fm.entity_refs);
+    const provisionalEntities = stringList(fm.provisional_entities ?? fm.entity_mentions).filter((e) => !entityRefs.includes(e));
+    const base = {
+        memberUid: input.memberUid,
+        sourceRef,
+        sourceDigest,
+        signalType,
+        audienceKey: receipt.audienceKey,
+        content,
+        promptVersion,
+        schemaVersion: SCHEMA_VERSION,
+    };
+    const observationId = computeObservationId(base);
+    const contribution = {
+        schema: SANITIZED_CONTRIBUTION_SCHEMA,
+        sanitizerVersion: SANITIZER_VERSION,
+        observationId,
+        signalType,
+        content,
+        citations,
+        sourceRef,
+        sourceDigest,
+        entityRefs,
+        provisionalEntities,
+        companyUid: input.companyUid,
+        memberUid: input.memberUid,
+        audienceKey: receipt.audienceKey,
+        audienceVersion: receipt.audienceVersion,
+        audienceReceiptRef: receipt.ref,
+        promptVersion,
+        schemaVersion: SCHEMA_VERSION,
+        classification: "company-eligible",
+        projectionState: input.projectionState,
+        projectionWatermark: input.projectionWatermark,
+    };
+    const owner = boundedOrUndefined(fm.owner);
+    if (owner)
+        contribution.owner = owner;
+    const speaker = boundedOrUndefined(fm.speaker);
+    if (speaker)
+        contribution.speaker = speaker;
+    const problems = validateContributionShape(contribution);
+    if (problems.length > 0)
+        return fail(`shape: ${problems[0]}`);
+    let destination;
+    try {
+        destination = contributionKey(input.memberUid, receipt.audienceKey, signalType, observationId);
+    }
+    catch {
+        return fail("unaddressable");
+    }
+    return { ok: true, contribution, destination, sha };
+}
+//# sourceMappingURL=sanitize.js.map

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

@@ -0,0 +1,10 @@
+export interface SignalsSettings {
+    maxTurns: number;
+    maxBudgetUsd: number;
+    lateStartHour: number;
+    briefWaitMinutes: number;
+}
+export declare const DEFAULT_SIGNALS_SETTINGS: SignalsSettings;
+export declare const SIGNALS_SETTINGS_REL: string;
+export declare function loadSignalsSettings(hqRoot: string): SignalsSettings;
+//# sourceMappingURL=settings.d.ts.map

package/dist/lib/signals/settings.js

@@ -0,0 +1,48 @@
+/** Loads core/settings/signals.yaml from the HQ root, with built-in defaults. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+export const DEFAULT_SIGNALS_SETTINGS = {
+    maxTurns: 40,
+    maxBudgetUsd: 2.0,
+    lateStartHour: 22,
+    briefWaitMinutes: 20,
+};
+/** maxTurns: whole number >= 1. lateStartHour: whole hour 1-24 (0 would make every job late; 24 turns it off). */
+const VALID = {
+    maxTurns: (v) => Number.isInteger(v) && v >= 1,
+    maxBudgetUsd: (v) => Number.isFinite(v) && v >= 0,
+    lateStartHour: (v) => Number.isInteger(v) && v >= 1 && v <= 24,
+    briefWaitMinutes: (v) => Number.isFinite(v) && v >= 0,
+};
+export const SIGNALS_SETTINGS_REL = path.join("core", "settings", "signals.yaml");
+export function loadSignalsSettings(hqRoot) {
+    const out = { ...DEFAULT_SIGNALS_SETTINGS };
+    let raw;
+    try {
+        raw = yaml.load(fs.readFileSync(path.join(hqRoot, SIGNALS_SETTINGS_REL), "utf8"));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`hq signals: ignoring unreadable ${SIGNALS_SETTINGS_REL}: ${msg}\n`);
+        }
+        return out;
+    }
+    if (!raw || typeof raw !== "object")
+        return out;
+    const obj = raw;
+    for (const key of Object.keys(out)) {
+        const v = obj[key];
+        if (v === undefined)
+            continue;
+        if (typeof v === "number" && VALID[key](v)) {
+            out[key] = v;
+        }
+        else {
+            process.stderr.write(`hq signals: ignoring invalid ${key} in ${SIGNALS_SETTINGS_REL}: ${String(v)}\n`);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=settings.js.map

package/dist/lib/signals/steps/adapters.d.ts

@@ -0,0 +1,14 @@
+import type { OnDemandSyncReport } from "../../hot-channels/run.js";
+import type { HotChannelSyncFn, SignalsStep, StepContext, StepResult } from "./types.js";
+export declare const defaultHotChannelSync: HotChannelSyncFn;
+export declare function mapSyncReport(report: OnDemandSyncReport): StepResult;
+/**
+ * Mirror the signed-in person's vault cursors
+ * (`companies/{co}/sources/_cursors/@{personKey}/{key}.json`, written by the
+ * loop only after a page's sources land) to the local watermark
+ * `workspace/signals/watermarks/{co}/{key}.json`. Teammates' cursor
+ * directories are never read: their watermarks are not this machine's.
+ */
+export declare function mirrorWatermarks(ctx: Pick<StepContext, "hqRoot" | "company" | "write">, personKey: string): string[];
+export declare const adaptersStep: SignalsStep;
+//# sourceMappingURL=adapters.d.ts.map