@indigoai-us/hq-cli 5.345.178 → 5.345.180

package/dist/lib/hot-channels/signals-pass.js

@@ -0,0 +1,581 @@
+/**
+ * The local signals pass (US-011). After a hot-channel run lands sources, the
+ * pass takes the run's landed documents through the ontology worklist, asks
+ * `claude -p` for signals one document at a time, and writes those signals to
+ * `companies/{co}/signals/`. It returns the count for the run ledger.
+ *
+ * A landed document with both `payload_ref` and `raw_ref` is a pointer (the
+ * meetings, Slack and Attio adapters land these). For it, claude gets the
+ * pointer followed by the document `payload_ref` names, capped at
+ * MAX_PAYLOAD_BYTES. A payload outside `sources/`, missing or unreadable falls
+ * back to the pointer alone, and the reason is warned and kept on the signal.
+ *
+ * Billing: policy hq-no-headless-print-subscription-billing forbids headless
+ * `claude -p` in general. This is its allowed case, per the owner decision of
+ * 2026-10-21: the owner's own `claude` login, on their own machine, in a
+ * bounded single-turn call. Cloud Claude is not the bot brain, and no model is
+ * called from the poller itself. Do not reuse this pass for a shared, fleet or
+ * hosted identity.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as yaml from "js-yaml";
+import { audienceKey, COMPANY_AUDIENCE_KEY } from "./audience.js";
+import { assertPayloadRef, assertSafeSegment, writeFileAtomic } from "./landing.js";
+/**
+ * A pass failure the run ledger records as `status: failed` with `error` set
+ * to the code. Any other error thrown from the pass is a crash.
+ */
+export class SignalsPassError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SignalsPassError";
+        this.code = code;
+    }
+}
+/** Signal types the pass accepts; the same type folders existing signals use. */
+export const SIGNAL_TYPES = [
+    "action_item",
+    "commitment",
+    "decision",
+    "key_point",
+    "participant_contribution",
+    "question",
+    "risk",
+    "summary",
+];
+/**
+ * Flags that cut the signals call off from everything but the model: no
+ * built-in tools, no MCP servers, and no user, project or local settings (so
+ * user hooks and permission rules do not apply). The documents are untrusted
+ * provider content, so a prompt injection must have nothing to call.
+ * `--safe-mode` also stops CLAUDE.md and user memory from loading, so private
+ * context never reaches a prompt the documents can steer. `--bare` would do the
+ * same but reads only ANTHROPIC_API_KEY, which breaks subscription (OAuth)
+ * sign-in; `--safe-mode` keeps auth working (checked on Claude Code 2.1.308).
+ */
+export const CLAUDE_ISOLATION_ARGS = [
+    "--safe-mode",
+    "--tools",
+    "",
+    "--strict-mcp-config",
+    "--mcp-config",
+    '{"mcpServers":{}}',
+    "--setting-sources",
+    "",
+];
+/** Per-document `claude -p` budget (policy indigo-executors-bound-all-waits). */
+export const DEFAULT_SIGNALS_TIMEOUT_MS = 120_000;
+/** Budget for the `claude auth status` preflight. */
+export const AUTH_PREFLIGHT_TIMEOUT_MS = 10_000;
+/** Budget for one worklist script call. */
+export const WORKLIST_TIMEOUT_MS = 60_000;
+/** Documents one pass sends to claude across all adapters of a run. */
+export const DEFAULT_MAX_SIGNAL_DOCS = 20;
+/** Payload bytes sent to claude per document (200 KB). A longer payload is cut with a marker. */
+export const MAX_PAYLOAD_BYTES = 200 * 1024;
+/** Items the worklist lists per channel; landed documents must fall inside it. */
+const WORKLIST_LIMIT = 500;
+/** Output kept per child stream. A longer reply is bad output. */
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** Signals kept per document. */
+const MAX_SIGNALS_PER_DOC = 12;
+const KILL_GRACE_MS = 2_000;
+const SIGNAL_ORIGIN = "hot-signal-sync";
+/**
+ * Run a command with a hard timeout. The child leads its own process group;
+ * on timeout the whole group gets SIGTERM, then SIGKILL after a short grace
+ * (policy indigo-subprocess-wrapping-qmd-use-killpg-on-timeout), so a node
+ * child of `claude` cannot outlive the call.
+ */
+export function runBounded(command, args, options) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd: options.cwd,
+                env: options.env ?? process.env,
+                detached: true,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            resolve({ code: null, stdout: "", stderr: "", timedOut: false, spawnError: String(err) });
+            return;
+        }
+        const out = [];
+        const errOut = [];
+        let outBytes = 0;
+        let errBytes = 0;
+        let timedOut = false;
+        let spawnError;
+        let settled = false;
+        const killGroup = (signal) => {
+            if (child.pid === undefined)
+                return;
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch {
+                // The group is already gone.
+            }
+        };
+        let graceTimer;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup("SIGTERM");
+            graceTimer = setTimeout(() => killGroup("SIGKILL"), KILL_GRACE_MS);
+            graceTimer.unref();
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            outBytes += chunk.length;
+            if (outBytes <= MAX_OUTPUT_BYTES)
+                out.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            errBytes += chunk.length;
+            if (errBytes <= MAX_OUTPUT_BYTES)
+                errOut.push(chunk);
+        });
+        child.stdin.on("error", () => {
+            // The child exited before reading stdin; its exit code tells the story.
+        });
+        child.on("error", (err) => {
+            spawnError = err.message;
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            // Reap anything the child left behind in its group.
+            killGroup("SIGKILL");
+            resolve({
+                code,
+                stdout: outBytes > MAX_OUTPUT_BYTES ? "" : Buffer.concat(out).toString("utf8"),
+                stderr: Buffer.concat(errOut).toString("utf8"),
+                timedOut,
+                ...(spawnError !== undefined ? { spawnError } : {}),
+            });
+        });
+        child.stdin.end(options.input ?? "");
+    });
+}
+export function defaultPromptFile() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "prompts", "signals-pass.md");
+}
+const LOGGED_OUT = /not logged in|log ?in|\/login|invalid api key|authenticat|oauth token/i;
+function channelOf(key) {
+    const parts = key.split("/");
+    if (parts.length !== 3 || parts[0] !== "sources" || !parts[2].endsWith(".md"))
+        return null;
+    try {
+        assertSafeSegment(parts[1], "channel");
+        assertSafeSegment(parts[2], "document");
+    }
+    catch {
+        return null;
+    }
+    return parts[1];
+}
+function splitFrontmatter(text) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+    if (!match)
+        return { frontmatter: {}, body: text };
+    const parsed = yaml.load(match[1]);
+    return {
+        frontmatter: parsed && typeof parsed === "object" ? parsed : {},
+        body: match[2],
+    };
+}
+function isMissing(err) {
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** Read at most MAX_PAYLOAD_BYTES of a file, cut on a UTF-8 boundary, with a marker when cut. */
+async function readCapped(file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`${file} is not a regular file`);
+        const buf = Buffer.alloc(MAX_PAYLOAD_BYTES + 1);
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        if (bytesRead <= MAX_PAYLOAD_BYTES)
+            return buf.subarray(0, bytesRead).toString("utf8");
+        let end = MAX_PAYLOAD_BYTES;
+        // Step back over UTF-8 continuation bytes so no character is split.
+        while (end > 0 && (buf[end] & 0xc0) === 0x80)
+            end -= 1;
+        const total = Math.max(stat.size, bytesRead);
+        return `${buf.subarray(0, end).toString("utf8")}\n[payload truncated at ${MAX_PAYLOAD_BYTES} bytes of ${total}]\n`;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * The text claude gets for one landed document. A pointer (both `payload_ref`
+ * and `raw_ref` set) gets its payload appended after a separator line. Any
+ * other document is sent as landed: without `raw_ref`, `payload_ref` names the
+ * document's own `.raw.json` sidecar and the body is the content.
+ */
+export async function buildSignalsInput(vaultRoot, file) {
+    const pointer = await fs.readFile(path.join(vaultRoot, file), "utf8");
+    const { frontmatter } = splitFrontmatter(pointer);
+    const ref = frontmatter.payload_ref;
+    if (frontmatter.raw_ref === undefined || frontmatter.raw_ref === null || ref === undefined || ref === null) {
+        return { text: pointer };
+    }
+    const fallback = (reason) => ({
+        text: pointer,
+        fallback: reason,
+        fallbackRef: String(ref),
+    });
+    if (typeof ref !== "string" || path.isAbsolute(ref))
+        return fallback("payload-out-of-bounds");
+    try {
+        assertPayloadRef(ref);
+    }
+    catch {
+        return fallback("payload-out-of-bounds");
+    }
+    const sourcesRoot = path.resolve(vaultRoot, "sources");
+    const target = path.resolve(vaultRoot, ref);
+    if (!target.startsWith(`${sourcesRoot}${path.sep}`))
+        return fallback("payload-out-of-bounds");
+    let payload;
+    try {
+        // A symlink inside sources/ must not lead outside it.
+        const [realSources, realTarget] = await Promise.all([fs.realpath(sourcesRoot), fs.realpath(target)]);
+        if (!realTarget.startsWith(`${realSources}${path.sep}`))
+            return fallback("payload-out-of-bounds");
+        payload = await readCapped(realTarget);
+    }
+    catch (err) {
+        return fallback(isMissing(err) ? "payload-missing" : "payload-unreadable");
+    }
+    const head = pointer.endsWith("\n") ? pointer : `${pointer}\n`;
+    return { text: `${head}--- payload: ${ref} ---\n${payload}`, payloadRef: ref };
+}
+/**
+ * Parse `claude -p --output-format json` output into signals. The envelope's
+ * `result` must itself be one JSON object, optionally inside a single code
+ * fence; nothing is scraped out of prose.
+ */
+export function parseClaudeSignals(stdout) {
+    let envelope;
+    try {
+        envelope = JSON.parse(stdout);
+    }
+    catch {
+        throw new SignalsPassError("claude-bad-output", "claude did not print a JSON envelope");
+    }
+    if (!envelope || typeof envelope !== "object") {
+        throw new SignalsPassError("claude-bad-output", "claude printed a JSON value that is not an envelope");
+    }
+    const env = envelope;
+    if (env.is_error === true) {
+        const text = typeof env.result === "string" ? env.result : "";
+        if (LOGGED_OUT.test(text))
+            throw new SignalsPassError("claude-logged-out", "claude reported it is not logged in");
+        throw new SignalsPassError("claude-bad-output", "claude returned an error result");
+    }
+    if (typeof env.result !== "string") {
+        throw new SignalsPassError("claude-bad-output", "claude envelope has no result text");
+    }
+    let text = env.result.trim();
+    const fence = /^```(?:json)?\n([\s\S]*)\n```$/.exec(text);
+    if (fence)
+        text = fence[1].trim();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new SignalsPassError("claude-bad-output", "claude result is not JSON");
+    }
+    const signals = body?.signals;
+    if (!Array.isArray(signals)) {
+        throw new SignalsPassError("claude-bad-output", "claude result has no signals list");
+    }
+    return signals.slice(0, MAX_SIGNALS_PER_DOC).map((raw, i) => {
+        const s = raw;
+        if (!s ||
+            typeof s !== "object" ||
+            !SIGNAL_TYPES.includes(s.type) ||
+            typeof s.title !== "string" ||
+            s.title.trim().length === 0 ||
+            typeof s.body !== "string") {
+            throw new SignalsPassError("claude-bad-output", `claude signal ${i} has the wrong shape`);
+        }
+        return { type: s.type, title: s.title.trim(), body: s.body.trim() };
+    });
+}
+/** `sha256(source_ref \n type \n title)`: the same signal from the same source keeps its id. */
+export function signalId(sourceRef, type, title) {
+    return createHash("sha256").update(`${sourceRef}\n${type}\n${title}`).digest("hex");
+}
+/**
+ * Vault-relative directory for one signal type. Company-wide signals keep the
+ * existing `signals/{type}/` layout; person-scoped signals live under
+ * `signals/@{audienceKey}/{type}/`.
+ */
+export function signalTypeDir(key, type) {
+    if (key === COMPANY_AUDIENCE_KEY)
+        return `signals/${type}`;
+    assertSafeSegment(key, "audience key");
+    return `signals/@${key}/${type}`;
+}
+function heading(type) {
+    const words = type.split("_").join(" ");
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+async function exists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write `signals/@{key}/_audience.yaml` once, when the partition is first created. */
+export async function ensureAudienceFile(vaultRoot, item) {
+    if (item.audienceKey === COMPANY_AUDIENCE_KEY)
+        return;
+    assertSafeSegment(item.audienceKey, "audience key");
+    const file = path.join(vaultRoot, "signals", `@${item.audienceKey}`, "_audience.yaml");
+    if (await exists(file))
+        return;
+    const principals = [...new Set(item.principals.map((p) => p.trim()).filter((p) => p.length > 0))].sort();
+    const text = yaml.dump({ principals, audience_source: item.audienceSource }, { lineWidth: -1 });
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    try {
+        await fs.writeFile(file, text, { encoding: "utf8", flag: "wx" });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+}
+async function appendSignalIndex(vaultRoot, day, rows) {
+    if (rows.length === 0)
+        return;
+    const file = path.join(vaultRoot, "signals", "_index", `${day}.json`);
+    let existing = [];
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        if (Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const seen = new Set(existing.map((row) => row.signal_id));
+    const added = rows.filter((row) => !seen.has(row.signal_id));
+    if (added.length === 0)
+        return;
+    await writeFileAtomic(file, `${JSON.stringify([...existing, ...added], null, 2)}\n`);
+}
+/**
+ * Build the claude signals pass for one company. The pass keeps state for one
+ * run: the auth preflight runs once, and the document cap counts across every
+ * adapter of the run, so create a new pass per run.
+ */
+export function createClaudeSignalsPass(options) {
+    assertSafeSegment(options.company, "company");
+    const claude = options.claudeBin ?? "claude";
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SIGNALS_TIMEOUT_MS;
+    const authTimeoutMs = options.authTimeoutMs ?? AUTH_PREFLIGHT_TIMEOUT_MS;
+    const maxDocs = Math.max(0, options.maxDocs ?? DEFAULT_MAX_SIGNAL_DOCS);
+    const worklist = options.worklistScript ?? path.join(options.hqRoot, "core", "scripts", "ontology-source-worklist.sh");
+    const promptFile = options.promptFile ?? defaultPromptFile();
+    const now = options.now ?? (() => new Date());
+    const env = options.env ?? process.env;
+    const warn = options.warn ?? ((message) => void process.stderr.write(`${message}\n`));
+    const vaultRoot = path.join(options.hqRoot, "companies", options.company);
+    // claude runs outside the HQ tree so it loads no HQ project context or hooks.
+    const claudeCwd = os.tmpdir();
+    let preflight;
+    let prompt;
+    let docsSent = 0;
+    const checkLogin = async () => {
+        const run = await runBounded(claude, ["auth", "status"], { timeoutMs: authTimeoutMs, cwd: claudeCwd, env });
+        if (run.timedOut)
+            throw new SignalsPassError("claude-timeout", "claude auth status timed out");
+        if (run.spawnError !== undefined || run.code !== 0) {
+            throw new SignalsPassError("claude-logged-out", "claude is not logged in (claude auth status failed)");
+        }
+        try {
+            const status = JSON.parse(run.stdout);
+            if (status.loggedIn === false)
+                throw new SignalsPassError("claude-logged-out", "claude is not logged in");
+        }
+        catch (err) {
+            if (err instanceof SignalsPassError)
+                throw err;
+            // A plain-text status with exit 0 means logged in.
+        }
+    };
+    const runWorklist = async (args) => runBounded("bash", [worklist, ...args], {
+        timeoutMs: WORKLIST_TIMEOUT_MS,
+        cwd: options.hqRoot,
+        env: { ...env, HQ_ROOT: options.hqRoot },
+    });
+    /** Work items for the landed documents of one channel. */
+    const itemsFor = async (channel, files) => {
+        const wanted = new Set(files);
+        const run = await runWorklist(["--company", options.company, "--channel", channel, "--limit", String(WORKLIST_LIMIT)]);
+        if (run.timedOut)
+            throw new Error(`ontology worklist timed out for channel ${channel}`);
+        // Exit 4: the source is assigned to the cloud agent. Its documents are not this pass's to process.
+        if (run.code === 4)
+            return [];
+        if (run.code === 0) {
+            const items = [];
+            for (const line of run.stdout.split("\n")) {
+                if (line.trim().length === 0)
+                    continue;
+                let row;
+                try {
+                    row = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (typeof row.file !== "string" || !wanted.has(row.file) || row.skip !== undefined)
+                    continue;
+                if (typeof row.audience_key !== "string" || !Array.isArray(row.audience))
+                    continue;
+                items.push({
+                    file: row.file,
+                    channel,
+                    principals: row.audience.filter((a) => typeof a === "string"),
+                    audienceKey: row.audience_key,
+                    audienceSource: "worklist",
+                    fromWorklist: true,
+                });
+            }
+            return items;
+        }
+        // Any other exit (usually 2: the channel has no source.yaml yet, which is
+        // normal for a hot channel) falls back to the landed document's own
+        // audience frontmatter, which landing always writes.
+        const items = [];
+        for (const file of files) {
+            const { frontmatter } = splitFrontmatter(await fs.readFile(path.join(vaultRoot, file), "utf8"));
+            const audience = Array.isArray(frontmatter.audience)
+                ? frontmatter.audience.filter((a) => typeof a === "string" && a.trim().length > 0)
+                : [];
+            // No audience: skipped, never widened to company.
+            if (audience.length === 0)
+                continue;
+            items.push({
+                file,
+                channel,
+                principals: audience,
+                audienceKey: audienceKey(audience),
+                audienceSource: typeof frontmatter.audience_source === "string" ? frontmatter.audience_source : "frontmatter",
+                fromWorklist: false,
+            });
+        }
+        return items;
+    };
+    const extract = async (item, input) => {
+        prompt ??= fs.readFile(promptFile, "utf8");
+        const run = await runBounded(claude, ["-p", await prompt, ...CLAUDE_ISOLATION_ARGS, "--output-format", "json", "--max-turns", "1"], {
+            timeoutMs,
+            input: input.text,
+            cwd: claudeCwd,
+            env,
+        });
+        if (run.timedOut)
+            throw new SignalsPassError("claude-timeout", `claude timed out after ${timeoutMs}ms on ${item.file}`);
+        if (run.spawnError !== undefined)
+            throw new SignalsPassError("claude-logged-out", `claude could not start: ${run.spawnError}`);
+        if (run.code !== 0 && LOGGED_OUT.test(`${run.stderr}\n${run.stdout}`) && !run.stdout.trim().startsWith("{")) {
+            throw new SignalsPassError("claude-logged-out", "claude reported it is not logged in");
+        }
+        return parseClaudeSignals(run.stdout);
+    };
+    const write = async (item, input, signals, beforeWrite) => {
+        const at = now().toISOString();
+        const rows = [];
+        let written = 0;
+        if (signals.length > 0) {
+            await beforeWrite();
+            await ensureAudienceFile(vaultRoot, item);
+        }
+        for (const signal of signals) {
+            const id = signalId(item.file, signal.type, signal.title);
+            const key = `${signalTypeDir(item.audienceKey, signal.type)}/${id}.md`;
+            rows.push({ signal_id: id, type: signal.type, source_ref: item.file, key, written_at: at });
+            const file = path.join(vaultRoot, key);
+            if (await exists(file))
+                continue;
+            const frontmatter = {
+                signal_id: id,
+                type: signal.type,
+                source_ref: item.file,
+                canonical_content: signal.title,
+                audience_key: item.audienceKey,
+                origin: SIGNAL_ORIGIN,
+                written_at: at,
+            };
+            if (input.payloadRef !== undefined)
+                frontmatter.payload_ref = input.payloadRef;
+            if (input.fallback !== undefined)
+                frontmatter.payload_fallback = input.fallback;
+            const text = `---\n${yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trimEnd()}\n---\n## ${heading(signal.type)}\n\n${signal.body || signal.title}\n`;
+            await beforeWrite();
+            await writeFileAtomic(file, text);
+            written += 1;
+        }
+        await beforeWrite();
+        await appendSignalIndex(vaultRoot, at.slice(0, 10), rows);
+        return written;
+    };
+    return async (result, guard) => {
+        const beforeWrite = guard?.beforeWrite ?? (async () => undefined);
+        const byChannel = new Map();
+        for (const key of result.landedKeys ?? []) {
+            const channel = channelOf(key);
+            if (!channel)
+                continue;
+            byChannel.set(channel, [...(byChannel.get(channel) ?? []), key]);
+        }
+        // Nothing landed: there is no pass to run, so claude is not called.
+        if (byChannel.size === 0)
+            return 0;
+        preflight ??= checkLogin();
+        await preflight;
+        let total = 0;
+        for (const [channel, files] of byChannel) {
+            for (const item of await itemsFor(channel, files)) {
+                // Documents over the cap stay unmarked in the worklist for a later pass.
+                if (docsSent >= maxDocs)
+                    return total;
+                docsSent += 1;
+                const input = await buildSignalsInput(vaultRoot, item.file);
+                if (input.fallback !== undefined) {
+                    warn(`signals pass: ${item.file}: ${input.fallback} for payload_ref ${JSON.stringify(input.fallbackRef)}; sent the pointer only`);
+                }
+                total += await write(item, input, await extract(item, input), beforeWrite);
+                if (item.fromWorklist) {
+                    await runWorklist(["--company", options.company, "--channel", channel, "--mark-done", item.file]);
+                }
+            }
+        }
+        return total;
+    };
+}
+//# sourceMappingURL=signals-pass.js.map

package/dist/lib/hot-channels/sync-lock.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One hot-channel sync at a time per person per company. The bot's scheduled
+ * run and a manual `hq sources sync` can fire together; the index files are
+ * read-modify-write, so two runs at once can lose rows and process the same
+ * event twice. The lock is `sources/_runs/@{personKey}/.lock`, created with
+ * O_EXCL and holding the pid, host, start time and last heartbeat.
+ *
+ * A lock is stale when its holder on this host is no longer alive, or when its
+ * last heartbeat is older than `SYNC_LOCK_STALE_MS`. The holder heartbeats the
+ * lock while it runs, so a long signals pass is never taken over mid-write.
+ * Takeover runs under an O_EXCL `.takeover` guard: the guard holder renames the
+ * stale file to a unique name, checks it moved the file it judged stale, and
+ * every contender then competes on the O_EXCL create of a fresh lock.
+ * Release removes the file only while it still names this holder.
+ */
+/** A lock whose last heartbeat is older than this is stale. */
+export declare const SYNC_LOCK_STALE_MS: number;
+/** How often a held lock is refreshed; well under the stale limit. */
+export declare const SYNC_LOCK_HEARTBEAT_MS: number;
+export declare const SYNC_LOCK_BUSY_REASON = "another sync is running";
+/**
+ * The run no longer holds its sync lock (another run took it over, for example
+ * after this machine slept past the stale limit). The run stops before its
+ * next write.
+ */
+export declare class SyncLockLostError extends Error {
+    constructor();
+}
+export interface SyncLock {
+    file: string;
+    /** Throw `SyncLockLostError` when the lock no longer names this holder. Call before each write. */
+    assertHeld: () => Promise<void>;
+    /** Refresh the heartbeat. A no-op when the lock no longer names this holder. */
+    heartbeat: () => Promise<void>;
+    /** Stop the heartbeat and remove the lock if it still names this holder. */
+    release: () => Promise<void>;
+}
+export declare function syncLockPath(vaultRoot: string, personKey: string): string;
+/** True when `pid` names a live process on this host. EPERM means it exists. */
+export declare function pidAlive(pid: number): boolean;
+/**
+ * Take the sync lock, or return null when a live run holds it. A stale lock is
+ * moved aside and taken over once; a race lost during takeover returns null.
+ */
+export declare function acquireSyncLock(vaultRoot: string, personKey: string, options?: {
+    now?: () => Date;
+    staleMs?: number;
+    heartbeatMs?: number;
+    pidAlive?: (pid: number) => boolean;
+}): Promise<SyncLock | null>;
+//# sourceMappingURL=sync-lock.d.ts.map