@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/lib/hot-channels/sync-lock.js

@@ -17,6 +17,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { assertVaultPath } from "../signals/write-guard.js";
 import { assertNotIntegrationSecretsPath, personDirName } from "./cursors.js";
 /** A lock whose last heartbeat is older than this is stale. */
 export const SYNC_LOCK_STALE_MS = 30 * 60 * 1000;
@@ -42,7 +43,8 @@ export function syncLockPath(vaultRoot, personKey) {
 function serialize(body) {
     return `${JSON.stringify(body)}\n`;
 }
-async function tryCreate(file, body) {
+async function tryCreate(file, body, check) {
+    check(file);
     try {
         await fs.writeFile(file, serialize(body), { encoding: "utf8", flag: "wx" });
         return true;
@@ -102,6 +104,10 @@ export async function acquireSyncLock(vaultRoot, personKey, options = {}) {
     const heartbeatMs = options.heartbeatMs ?? SYNC_LOCK_HEARTBEAT_MS;
     const alive = options.pidAlive ?? pidAlive;
     const file = syncLockPath(vaultRoot, personKey);
+    const check = (p) => {
+        assertVaultPath(vaultRoot, p);
+    };
+    check(file);
     await fs.mkdir(path.dirname(file), { recursive: true });
     const startedAt = now().toISOString();
     const body = { pid: process.pid, host: os.hostname(), startedAt, heartbeatAt: startedAt };
@@ -120,6 +126,8 @@ export async function acquireSyncLock(vaultRoot, personKey, options = {}) {
             if (released || !(await ownsFile()))
                 return;
             const tmp = `${file}.${randomUUID()}.tmp`;
+            check(tmp);
+            check(file);
             await fs.writeFile(tmp, serialize({ ...body, heartbeatAt: now().toISOString() }), "utf8");
             await fs.rename(tmp, file);
         };
@@ -140,19 +148,21 @@ export async function acquireSyncLock(vaultRoot, personKey, options = {}) {
                 released = true;
                 if (timer)
                     clearInterval(timer);
-                if (await ownsFile())
+                if (await ownsFile()) {
+                    check(file);
                     await fs.rm(file, { force: true });
+                }
             },
         };
     };
-    if (await tryCreate(file, body))
+    if (await tryCreate(file, body, check))
         return held();
     const stale = await isStale(file, now().getTime(), staleMs, alive);
     if (stale === false)
         return null;
-    if (stale === true && !(await takeOverStale(file, now, staleMs, alive)))
+    if (stale === true && !(await takeOverStale(file, now, staleMs, alive, check)))
         return null;
-    return (await tryCreate(file, body)) ? held() : null;
+    return (await tryCreate(file, body, check)) ? held() : null;
 }
 /** A takeover guard older than this belongs to a contender that died mid-takeover. */
 const TAKEOVER_GUARD_STALE_MS = 60 * 1000;
@@ -164,8 +174,10 @@ const TAKEOVER_GUARD_STALE_MS = 60 * 1000;
  * (its holder released and a new run took the lock), it is put back. Returns
  * false when this contender should give up.
  */
-async function takeOverStale(file, now, staleMs, alive) {
+async function takeOverStale(file, now, staleMs, alive, check) {
     const guard = `${file}.takeover`;
+    check(guard);
+    check(file);
     const takeGuard = async () => {
         try {
             await fs.writeFile(guard, `${process.pid}\n`, { encoding: "utf8", flag: "wx" });
@@ -188,6 +200,7 @@ async function takeOverStale(file, now, staleMs, alive) {
         if (age < TAKEOVER_GUARD_STALE_MS)
             return false;
         const staleGuard = `${guard}.stale-${randomUUID()}`;
+        check(staleGuard);
         await fs.rename(guard, staleGuard).catch(() => undefined);
         await fs.rm(staleGuard, { force: true });
         if (!(await takeGuard()))
@@ -200,6 +213,7 @@ async function takeOverStale(file, now, staleMs, alive) {
         if ((await isStale(file, now().getTime(), staleMs, alive)) !== true)
             return false;
         const aside = `${file}.stale-${process.pid}-${randomUUID()}`;
+        check(aside);
         try {
             await fs.rename(file, aside);
         }
@@ -210,6 +224,7 @@ async function takeOverStale(file, now, staleMs, alive) {
         }
         const moved = await fs.readFile(aside, "utf8").catch(() => null);
         if (moved !== seen) {
+            check(file);
             await fs.link(aside, file).catch(() => undefined);
             await fs.rm(aside, { force: true });
             return false;
@@ -218,6 +233,7 @@ async function takeOverStale(file, now, staleMs, alive) {
         return true;
     }
     finally {
+        check(guard);
         await fs.rm(guard, { force: true });
     }
 }

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -49,6 +49,11 @@ export interface InstallPaths {
     windowsTaskXmlPath: string;
     /** Windows: `DOMAIN\user` the task is registered for (logon trigger + principal). */
     windowsUser: string;
+    /**
+     * Windows: Task Scheduler name to register. Defaults to WINDOWS_TASK_NAME;
+     * set to the per-user name when the shared name is taken by another account.
+     */
+    windowsTaskName?: string;
     /**
      * Windows: `conhost.exe` used as `conhost --headless node hq ...` so the
      * logon-triggered daemon gets no visible console window. Undefined when the
@@ -257,6 +262,23 @@ export declare function renderSystemdSystemUnit(paths: InstallPaths): string;
  * resolveWindowsHeadlessLauncher); otherwise node is run directly.
  */
 export declare function renderWindowsTaskXml(paths: InstallPaths): string;
+/** Sidecar under the daemon dir naming the task this user registered. */
+export declare const WINDOWS_TASK_NAME_FILE = "windows-task-name";
+/**
+ * Per-user task name, e.g. `ai.getindigo.hq-mesh-daemon.alice`. Task names
+ * live in one machine-wide namespace: when the shared name already belongs to
+ * a task another account registered, a standard user cannot see, replace, or
+ * delete it, and `schtasks /Create /F` fails with "Access is denied". The
+ * per-user name avoids that collision.
+ */
+export declare function windowsPerUserTaskName(windowsUser: string): string;
+/** Task name this user's install registered (sidecar), else the shared name. */
+export declare function installedWindowsTaskName(dir: string, deps?: {
+    existsSync?: typeof fs.existsSync;
+    readFileSync?: typeof fs.readFileSync;
+}): string;
+/** Recorded mesh task name for a home dir (`hq daemon migrate` legacy probe). */
+export declare function recordedWindowsMeshTaskName(home: string, env?: NodeJS.ProcessEnv): string;
 /** schtasks stores task XML as UTF-16 LE with BOM; match it so /XML parses. */
 export declare function encodeWindowsTaskXml(rendered: string): Buffer;
 /** Status column of `schtasks /Query /FO CSV /NH`: "TaskName","Next Run Time","Status". */

package/dist/lib/mesh/live/daemon/install.js

@@ -137,9 +137,14 @@ function migrateLegacyDaemonUnit(opts) {
         });
         return;
     }
+    const taskName = installedWindowsTaskName(path.dirname(unitPath), {
+        existsSync: opts.existsSync,
+        readFileSync: opts.readFileSync,
+    });
+    paths.windowsTaskName = taskName;
     const rendered = renderWindowsTaskXml(paths);
     replaceUnitFile(unitPath, encodeWindowsTaskXml(rendered), 0o600, () => {
-        const result = opts.run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", unitPath, "/F"]);
+        const result = opts.run("schtasks.exe", ["/Create", "/TN", taskName, "/XML", unitPath, "/F"]);
         if (result.status !== 0)
             throw new Error("schtasks /Create failed while repairing the mesh unit");
     });
@@ -230,9 +235,10 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
             const xml = path.join(dir, `${WINDOWS_TASK_NAME}.xml`);
             if (!existsSync(xml))
                 return { attempted: false, restarted: false };
-            run("schtasks.exe", ["/End", "/TN", WINDOWS_TASK_NAME]);
+            const taskName = installedWindowsTaskName(dir, { existsSync, readFileSync });
+            run("schtasks.exe", ["/End", "/TN", taskName]);
             stopWindowsDaemonProcess(dir, { existsSync, kill: opts.kill });
-            const result = run("schtasks.exe", ["/Run", "/TN", WINDOWS_TASK_NAME]);
+            const result = run("schtasks.exe", ["/Run", "/TN", taskName]);
             return { attempted: true, restarted: result.status === 0 };
         }
     }
@@ -692,7 +698,7 @@ export function renderWindowsTaskXml(paths) {
     return `<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
-    <URI>\\${WINDOWS_TASK_NAME}</URI>
+    <URI>\\${paths.windowsTaskName ?? WINDOWS_TASK_NAME}</URI>
     <Description>HQ Work Mesh Live daemon (spool drainer + MQTT presence)</Description>
   </RegistrationInfo>
   <Triggers>
@@ -740,6 +746,50 @@ export function renderWindowsTaskXml(paths) {
 `;
 }
 const WINDOWS_TASK_LOGON_TYPE = "InteractiveToken";
+/** Sidecar under the daemon dir naming the task this user registered. */
+export const WINDOWS_TASK_NAME_FILE = "windows-task-name";
+/**
+ * Per-user task name, e.g. `ai.getindigo.hq-mesh-daemon.alice`. Task names
+ * live in one machine-wide namespace: when the shared name already belongs to
+ * a task another account registered, a standard user cannot see, replace, or
+ * delete it, and `schtasks /Create /F` fails with "Access is denied". The
+ * per-user name avoids that collision.
+ */
+export function windowsPerUserTaskName(windowsUser) {
+    const account = windowsUser.split("\\").pop() ?? windowsUser;
+    const slug = account.toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+    return `${WINDOWS_TASK_NAME}.${slug || "user"}`;
+}
+function isValidWindowsTaskName(name) {
+    return name === WINDOWS_TASK_NAME || /^ai\.getindigo\.hq-mesh-daemon\.[a-z0-9_-]+$/.test(name);
+}
+/** Task name this user's install registered (sidecar), else the shared name. */
+export function installedWindowsTaskName(dir, deps = {}) {
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const readFileSync = deps.readFileSync ?? fs.readFileSync;
+    const file = path.join(dir, WINDOWS_TASK_NAME_FILE);
+    try {
+        if (!existsSync(file))
+            return WINDOWS_TASK_NAME;
+        const raw = readFileSync(file);
+        const name = (Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw)).trim();
+        return isValidWindowsTaskName(name) ? name : WINDOWS_TASK_NAME;
+    }
+    catch {
+        return WINDOWS_TASK_NAME;
+    }
+}
+/** Recorded mesh task name for a home dir (`hq daemon migrate` legacy probe). */
+export function recordedWindowsMeshTaskName(home, env = process.env) {
+    return installedWindowsTaskName(daemonDir(undefined, home, env));
+}
+function recordWindowsTaskName(dir, name) {
+    const file = path.join(dir, WINDOWS_TASK_NAME_FILE);
+    if (name === WINDOWS_TASK_NAME)
+        fs.rmSync(file, { force: true });
+    else
+        atomicWrite(file, `${name}\n`, { mode: 0o600 });
+}
 /** schtasks stores task XML as UTF-16 LE with BOM; match it so /XML parses. */
 export function encodeWindowsTaskXml(rendered) {
     return Buffer.from(`\uFEFF${rendered}`, "utf16le");
@@ -1015,21 +1065,52 @@ export function installDaemonService(opts) {
     }
     if (platform === "win32") {
         const schtasks = opts.schtasks ?? defaultSchtasks;
-        const rendered = renderWindowsTaskXml(paths);
-        replaceUnitFile(paths.windowsTaskXmlPath, encodeWindowsTaskXml(rendered), 0o600, () => {
-            const created = schtasks([
-                "/Create", "/TN", WINDOWS_TASK_NAME, "/XML", paths.windowsTaskXmlPath, "/F",
-            ]);
-            if (created.status !== 0) {
-                throw new Error(`schtasks /Create failed for ${WINDOWS_TASK_NAME} (exit ${created.status ?? "signal"}): ` +
-                    `${(created.stderr || created.stdout).trim()}`);
+        const create = (name) => {
+            const rendered = renderWindowsTaskXml({ ...paths, windowsTaskName: name });
+            let error = null;
+            try {
+                replaceUnitFile(paths.windowsTaskXmlPath, encodeWindowsTaskXml(rendered), 0o600, () => {
+                    const created = schtasks(["/Create", "/TN", name, "/XML", paths.windowsTaskXmlPath, "/F"]);
+                    if (created.status !== 0) {
+                        throw new Error(`schtasks /Create failed for ${name} (exit ${created.status ?? "signal"}): ` +
+                            `${(created.stderr || created.stdout).trim()}`);
+                    }
+                    recordWindowsTaskName(paths.daemonDir, name);
+                });
             }
-        });
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+            }
+            return { rendered, error };
+        };
+        // Try the name this user registered before (or the shared name). If the
+        // shared name fails and this user cannot even query it, the task belongs
+        // to another account, which a standard user cannot replace ("Access is
+        // denied"); register a per-user name instead. A shared task this user can
+        // query is their own, so its failure is reported rather than leaving two
+        // logon tasks behind. Both attempts use the same unprivileged XML (logon
+        // trigger and principal scoped to this user, InteractiveToken, LeastPrivilege).
+        const perUser = windowsPerUserTaskName(paths.windowsUser);
+        let taskName = paths.windowsTaskName ?? installedWindowsTaskName(paths.daemonDir);
+        let attempt = create(taskName);
+        const sharedHeldElsewhere = () => taskName === WINDOWS_TASK_NAME
+            && schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "CSV", "/NH"]).status !== 0;
+        if (attempt.error && taskName !== perUser && sharedHeldElsewhere()) {
+            const firstError = attempt.error;
+            taskName = perUser;
+            attempt = create(taskName);
+            if (attempt.error)
+                throw new Error(`${firstError}; per-user fallback: ${attempt.error}`);
+        }
+        else if (attempt.error) {
+            throw new Error(attempt.error);
+        }
+        const rendered = attempt.rendered;
         // /F replaced any previous registration without ending its instance; stop
         // the recorded daemon so the fresh task instance can take the pid lock.
-        schtasks(["/End", "/TN", WINDOWS_TASK_NAME]);
+        schtasks(["/End", "/TN", taskName]);
         stopWindowsDaemonProcess(paths.daemonDir, { kill: opts.kill });
-        const started = schtasks(["/Run", "/TN", WINDOWS_TASK_NAME]);
+        const started = schtasks(["/Run", "/TN", taskName]);
         const running = started.status === 0;
         const mode = describeWindowsLaunchMode(paths);
         const rootLine = paths.hqRoot
@@ -1038,13 +1119,13 @@ export function installDaemonService(opts) {
         return {
             platform,
             action: "install",
-            paths,
+            paths: { ...paths, windowsTaskName: taskName },
             rendered,
             dest: paths.windowsTaskXmlPath,
             running,
             message: running
-                ? `${rootLine}Installed Scheduled Task ${WINDOWS_TASK_NAME} → ${paths.windowsTaskXmlPath} (started; ${mode})${legacyNote}`
-                : `${rootLine}Installed Scheduled Task ${WINDOWS_TASK_NAME} → ${paths.windowsTaskXmlPath} (${mode}); ` +
+                ? `${rootLine}Installed Scheduled Task ${taskName} → ${paths.windowsTaskXmlPath} (started; ${mode})${legacyNote}`
+                : `${rootLine}Installed Scheduled Task ${taskName} → ${paths.windowsTaskXmlPath} (${mode}); ` +
                     `start failed: ${(started.stderr || started.stdout).trim()}. It starts at next logon.${legacyNote}`,
             notice: windowsLogonNotice(paths),
         };
@@ -1063,26 +1144,30 @@ export function uninstallDaemonService(opts) {
     const existsSync = opts.existsSync ?? fs.existsSync;
     if (platform === "win32") {
         const schtasks = opts.schtasks ?? defaultSchtasks;
-        const registered = schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "CSV", "/NH"]).status === 0;
+        const taskName = paths.windowsTaskName ?? installedWindowsTaskName(paths.daemonDir, { existsSync });
+        const registered = schtasks(["/Query", "/TN", taskName, "/FO", "CSV", "/NH"]).status === 0;
         if (registered) {
-            schtasks(["/End", "/TN", WINDOWS_TASK_NAME]);
+            schtasks(["/End", "/TN", taskName]);
             stopWindowsDaemonProcess(paths.daemonDir, { existsSync, kill: opts.kill });
-            const deleted = schtasks(["/Delete", "/TN", WINDOWS_TASK_NAME, "/F"]);
+            const deleted = schtasks(["/Delete", "/TN", taskName, "/F"]);
             if (deleted.status !== 0) {
-                throw new Error(`schtasks /Delete failed for ${WINDOWS_TASK_NAME} (exit ${deleted.status ?? "signal"}): ` +
+                throw new Error(`schtasks /Delete failed for ${taskName} (exit ${deleted.status ?? "signal"}): ` +
                     `${(deleted.stderr || deleted.stdout).trim()}`);
             }
         }
         if (existsSync(paths.windowsTaskXmlPath))
             unlinkSync(paths.windowsTaskXmlPath);
+        const nameFile = path.join(paths.daemonDir, WINDOWS_TASK_NAME_FILE);
+        if (existsSync(nameFile))
+            unlinkSync(nameFile);
         return {
             platform,
             action: "uninstall",
             paths,
             dest: paths.windowsTaskXmlPath,
             message: registered
-                ? `Removed Scheduled Task ${WINDOWS_TASK_NAME}`
-                : `Scheduled Task ${WINDOWS_TASK_NAME} was not registered; removed local task XML if present`,
+                ? `Removed Scheduled Task ${taskName}`
+                : `Scheduled Task ${taskName} was not registered; removed local task XML if present`,
         };
     }
     if (platform === "darwin") {
@@ -1156,7 +1241,9 @@ export function daemonServiceStatus(opts) {
         // localized ("Running" / "Wird ausgeführt" / ...), so the daemon pid lock
         // is the source of truth for "running"; the column is shown when it
         // happens to carry a value, as extra context only.
-        const query = schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/FO", "CSV", "/NH"]);
+        const taskName = paths.windowsTaskName
+            ?? installedWindowsTaskName(paths.daemonDir, { existsSync, readFileSync: opts.readFileSync });
+        const query = schtasks(["/Query", "/TN", taskName, "/FO", "CSV", "/NH"]);
         const installed = query.status === 0;
         const taskState = installed ? parseSchtasksCsvStatus(query.stdout) : null;
         // The verbose query carries "Last Result": a non-zero, non-informational
@@ -1164,7 +1251,7 @@ export function daemonServiceStatus(opts) {
         // --headless), which the pid lock alone would report as merely "not
         // running". Surface it so a failed start never looks like a clean idle.
         const verbose = installed
-            ? schtasks(["/Query", "/TN", WINDOWS_TASK_NAME, "/V", "/FO", "CSV"])
+            ? schtasks(["/Query", "/TN", taskName, "/V", "/FO", "CSV"])
             : null;
         const lastResult = verbose && verbose.status === 0 ? parseSchtasksLastResult(verbose.stdout) : null;
         const lastRunFailed = schtasksLastResultFailed(lastResult);
@@ -1186,14 +1273,14 @@ export function daemonServiceStatus(opts) {
         let message;
         if (!installed) {
             message = running
-                ? `Scheduled Task ${WINDOWS_TASK_NAME}: not installed (daemon running outside the task)`
-                : `Scheduled Task ${WINDOWS_TASK_NAME}: not installed`;
+                ? `Scheduled Task ${taskName}: not installed (daemon running outside the task)`
+                : `Scheduled Task ${taskName}: not installed`;
         }
         else if (running) {
-            message = `Scheduled Task ${WINDOWS_TASK_NAME}: running${detail}`;
+            message = `Scheduled Task ${taskName}: running${detail}`;
         }
         else {
-            message = `Scheduled Task ${WINDOWS_TASK_NAME}: installed (daemon not running${lock === "stale" ? ", stale pid lock" : ""})${detail}`;
+            message = `Scheduled Task ${taskName}: installed (daemon not running${lock === "stale" ? ", stale pid lock" : ""})${detail}`;
         }
         return {
             platform,

package/dist/lib/signals/adapters-catalog.d.ts

@@ -0,0 +1,77 @@
+export declare const SIGNALS_ADAPTERS_CATALOG_PATH = "core/settings/signals-adapters.yaml";
+export declare const FLAG_OFF_REASON = "flag-off";
+export interface SignalsAdapterCatalogEntry {
+    id: string;
+    enabled: boolean;
+    schedule?: string;
+    flag?: string;
+}
+export interface AdapterFlag {
+    /** hq-flags key. */
+    flag: string;
+    /**
+     * The registered row's `defaultValue`: the value used when the row is
+     * absent, archived or unreadable.
+     */
+    defaultValue: boolean;
+}
+/**
+ * hq-flags keys that gate built-in adapters, with their registered defaults.
+ *
+ * `hq.hot-channel-slack` and `hq.hot-channel-linear` are default-on kill
+ * switches (indigo-feature-flags-default-on-as-fail-safes; owner pick,
+ * 2026-11-01): on for every company, and setting the row to false turns the
+ * adapter off. An absent or unregistered row keeps the adapter on. An
+ * unreadable registry keeps the last value read on this machine, and the
+ * adapter on when the flag was never read here.
+ */
+export declare const ADAPTER_FLAGS: Readonly<Record<string, AdapterFlag>>;
+/**
+ * Reads one company flag. `defaultValue` is the answer when the registry has
+ * no opinion (absent or unregistered row), or cannot be read and no value was
+ * read on this machine before.
+ */
+export type AdapterFlagReader = (flag: string, defaultValue: boolean) => boolean | Promise<boolean>;
+/** Where the reader keeps the last values it read: one file per company. */
+export interface AdapterFlagState {
+    hqRoot: string;
+    /** Company slug: the state file is `workspace/signals/flags/{company}.json`. */
+    company: string;
+}
+export declare function adapterFlagStatePath(company: string): string;
+/**
+ * The shared hq-flags evaluator for one company, memoized per flag for the
+ * life of the reader (one reader per sync run). Each read is bounded by the
+ * evaluator's request timeout. With `state`, a successful read is saved. A
+ * failed or timed-out read of a kill switch (`defaultValue` true) answers the
+ * last value saved for that flag and company, else `defaultValue`. A failed
+ * read of a default-off gate answers `defaultValue` (off): it fails closed.
+ * Without `state`, a failed read answers `defaultValue`.
+ */
+export declare function companyAdapterFlagReader(companyUid: string, idToken: string, state?: AdapterFlagState): AdapterFlagReader;
+/**
+ * Reads the local catalog; null when the file is absent. Malformed entries are
+ * dropped. An unreadable file or invalid yaml prints one warning to stderr and
+ * also answers null (no yaml gating), so a bad local file cannot break a sync.
+ */
+export declare function readSignalsAdaptersCatalog(hqRoot: string): SignalsAdapterCatalogEntry[] | null;
+export interface AdapterGating {
+    /** Registered adapters to run. */
+    enabled: string[];
+    /** Adapter id -> skip reason. */
+    skips: Record<string, string>;
+    /** Adapter id -> the flag that turned it off (absent for a yaml `enabled: false`). */
+    offFlags: Record<string, string>;
+}
+/** The flag gating one adapter: the yaml's `flag`, else the built-in one. */
+export declare function adapterFlag(id: string, entry: SignalsAdapterCatalogEntry | undefined): AdapterFlag | undefined;
+/**
+ * Merge the local catalog with the registered adapter ids. An adapter with
+ * `enabled: false`, or whose flag `isFlagOn` reads as off, is skipped with
+ * reason `flag-off`. Registered adapters the yaml does not list stay enabled
+ * unless their built-in flag is off. Yaml entries naming an unregistered
+ * adapter are ignored. Without `isFlagOn`, flags are not evaluated here: the
+ * sync evaluates them (hq-pro also gates flagged channels server-side).
+ */
+export declare function gateAdapters(registeredIds: readonly string[], catalog: readonly SignalsAdapterCatalogEntry[] | null, isFlagOn?: AdapterFlagReader): Promise<AdapterGating>;
+//# sourceMappingURL=adapters-catalog.d.ts.map

package/dist/lib/signals/adapters-catalog.js

@@ -0,0 +1,194 @@
+/**
+ * Local adapter gating for hot-channel syncs (hot-signal-sync US-008, US-009).
+ *
+ * `core/settings/signals-adapters.yaml` (shipped by hq-core) mirrors the hq-pro
+ * hot-channel catalog for local gating. hq-pro stays canonical: this file can
+ * only turn a registered adapter off, never add one. When the file is absent
+ * every registered adapter is enabled.
+ *
+ * Company flags are hq-flags rows read through the shared evaluator
+ * (`readCompanyFlag`: person, company uid, company slug, default). There is
+ * no company list in code. `runCompanyHotChannelSync` applies the gate for
+ * every caller (`hq sources sync`, the bot job and `hq signals run`).
+ *
+ * Read failures (indigo-hq-flags-only-for-feature-gating, US-009 re-review):
+ * a default-on flag is an ingest kill switch, so a failed or timed-out read
+ * uses the last value successfully read on this machine for that flag and
+ * company, kept in `workspace/signals/flags/{company}.json`, and the switch's
+ * default (on) when it was never read here (owner pick, 2026-11-01: "On when
+ * never read"). A default-off gate such as hq.hot-channel-gmail (owner hold)
+ * fails closed: a failed read is off, whatever was read before.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { guardedWrite } from "./write-guard.js";
+export const SIGNALS_ADAPTERS_CATALOG_PATH = "core/settings/signals-adapters.yaml";
+export const FLAG_OFF_REASON = "flag-off";
+/**
+ * hq-flags keys that gate built-in adapters, with their registered defaults.
+ *
+ * `hq.hot-channel-slack` and `hq.hot-channel-linear` are default-on kill
+ * switches (indigo-feature-flags-default-on-as-fail-safes; owner pick,
+ * 2026-11-01): on for every company, and setting the row to false turns the
+ * adapter off. An absent or unregistered row keeps the adapter on. An
+ * unreadable registry keeps the last value read on this machine, and the
+ * adapter on when the flag was never read here.
+ */
+export const ADAPTER_FLAGS = {
+    slack: { flag: "hq.hot-channel-slack", defaultValue: true },
+    linear: { flag: "hq.hot-channel-linear", defaultValue: true },
+    // US-010: registered in hq-pro with defaultValue false under an explicit
+    // owner hold (Gmail waits for Google's gmail.readonly verification). Setting
+    // the row to true turns Gmail on; an absent or unreadable row keeps it off.
+    // The key matches GMAIL_FLAG in hot-channels/adapters/gmail.ts.
+    gmail: { flag: "hq.hot-channel-gmail", defaultValue: false },
+};
+export function adapterFlagStatePath(company) {
+    return `workspace/signals/flags/${company}.json`;
+}
+function readLastFlags(state, companyUid) {
+    let doc;
+    try {
+        doc = JSON.parse(fs.readFileSync(path.join(state.hqRoot, adapterFlagStatePath(state.company)), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const d = doc;
+    if (!d || d.companyUid !== companyUid || typeof d.flags !== "object" || d.flags === null)
+        return null;
+    return { version: 1, companyUid, flags: d.flags };
+}
+/** The last value read on this machine for this flag and company, if any. */
+function lastReadValue(state, companyUid, flag) {
+    const value = readLastFlags(state, companyUid)?.flags[flag]?.value;
+    return typeof value === "boolean" ? value : undefined;
+}
+/**
+ * Record a successfully read value. Read, merge and write are synchronous, so
+ * concurrent reads in one process cannot drop each other's values. The write
+ * is atomic (temp file, then rename, through the signals write guard).
+ */
+function rememberValue(state, companyUid, flag, value) {
+    const doc = readLastFlags(state, companyUid) ?? { version: 1, companyUid, flags: {} };
+    if (doc.flags[flag]?.value === value)
+        return;
+    doc.flags[flag] = { value, readAt: new Date().toISOString() };
+    try {
+        guardedWrite(state.hqRoot, adapterFlagStatePath(state.company), `${JSON.stringify(doc, null, 2)}\n`, {
+            company: state.company,
+        });
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        console.error(`hq: Could not save the last value of ${flag} (${errorClass}).`);
+    }
+}
+/**
+ * The shared hq-flags evaluator for one company, memoized per flag for the
+ * life of the reader (one reader per sync run). Each read is bounded by the
+ * evaluator's request timeout. With `state`, a successful read is saved. A
+ * failed or timed-out read of a kill switch (`defaultValue` true) answers the
+ * last value saved for that flag and company, else `defaultValue`. A failed
+ * read of a default-off gate answers `defaultValue` (off): it fails closed.
+ * Without `state`, a failed read answers `defaultValue`.
+ */
+export function companyAdapterFlagReader(companyUid, idToken, state) {
+    const memo = new Map();
+    return (flag, defaultValue) => {
+        const key = `${flag}\n${defaultValue}`;
+        let hit = memo.get(key);
+        if (!hit) {
+            // Loaded on first read: the registry module embeds its worker source.
+            hit = import("../flag-registry.js").then(async ({ readCompanyFlag }) => {
+                const read = await readCompanyFlag(companyUid, idToken, flag, { fallback: defaultValue });
+                if (read === null) {
+                    if (!defaultValue || !state)
+                        return defaultValue;
+                    return lastReadValue(state, companyUid, flag) ?? defaultValue;
+                }
+                // A process-local override is not a registry read: answer it, keep nothing.
+                if (state && read.source !== "local-override")
+                    rememberValue(state, companyUid, flag, read.value);
+                return read.value;
+            });
+            memo.set(key, hit);
+        }
+        return hit;
+    };
+}
+/**
+ * Reads the local catalog; null when the file is absent. Malformed entries are
+ * dropped. An unreadable file or invalid yaml prints one warning to stderr and
+ * also answers null (no yaml gating), so a bad local file cannot break a sync.
+ */
+export function readSignalsAdaptersCatalog(hqRoot) {
+    let doc;
+    try {
+        const text = fs.readFileSync(path.join(hqRoot, SIGNALS_ADAPTERS_CATALOG_PATH), "utf8");
+        doc = yaml.load(text, { schema: yaml.CORE_SCHEMA });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        const reason = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        process.stderr.write(`hq: warning: ignoring ${SIGNALS_ADAPTERS_CATALOG_PATH} (${reason}); running adapters without yaml gating\n`);
+        return null;
+    }
+    const list = Array.isArray(doc?.adapters) ? doc.adapters : [];
+    const out = [];
+    for (const raw of list) {
+        const e = raw;
+        if (!e || typeof e.id !== "string" || e.id.length === 0)
+            continue;
+        out.push({
+            id: e.id,
+            enabled: e.enabled !== false,
+            ...(typeof e.schedule === "string" ? { schedule: e.schedule } : {}),
+            ...(typeof e.flag === "string" && e.flag.length > 0 ? { flag: e.flag } : {}),
+        });
+    }
+    return out;
+}
+/** The flag gating one adapter: the yaml's `flag`, else the built-in one. */
+export function adapterFlag(id, entry) {
+    const builtin = ADAPTER_FLAGS[id];
+    if (entry?.flag === undefined)
+        return builtin;
+    // A yaml flag keeps the built-in default when it names the built-in key;
+    // any other key is read as a kill switch (on unless the row says off).
+    return { flag: entry.flag, defaultValue: builtin?.flag === entry.flag ? builtin.defaultValue : true };
+}
+/**
+ * Merge the local catalog with the registered adapter ids. An adapter with
+ * `enabled: false`, or whose flag `isFlagOn` reads as off, is skipped with
+ * reason `flag-off`. Registered adapters the yaml does not list stay enabled
+ * unless their built-in flag is off. Yaml entries naming an unregistered
+ * adapter are ignored. Without `isFlagOn`, flags are not evaluated here: the
+ * sync evaluates them (hq-pro also gates flagged channels server-side).
+ */
+export async function gateAdapters(registeredIds, catalog, isFlagOn) {
+    const byId = new Map((catalog ?? []).map((e) => [e.id, e]));
+    const decided = await Promise.all(registeredIds.map(async (id) => {
+        const entry = byId.get(id);
+        if (entry && !entry.enabled)
+            return { id, on: false, flag: undefined };
+        const flag = adapterFlag(id, entry);
+        if (!flag || !isFlagOn)
+            return { id, on: true, flag: undefined };
+        return { id, on: await isFlagOn(flag.flag, flag.defaultValue), flag: flag.flag };
+    }));
+    const gating = { enabled: [], skips: {}, offFlags: {} };
+    for (const { id, on, flag } of decided) {
+        if (on) {
+            gating.enabled.push(id);
+            continue;
+        }
+        gating.skips[id] = FLAG_OFF_REASON;
+        if (flag)
+            gating.offFlags[id] = flag;
+    }
+    return gating;
+}
+//# sourceMappingURL=adapters-catalog.js.map