@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/search-index/background.js

@@ -3,7 +3,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
-const LOCK_NAME = 'qmd-reindex-bg.lock';
+import { applyIndexSizeLimit as defaultApplyIndexSizeLimit } from './max-doc-bytes.js';
+import { acquireEmbedLock as acquireLock, installEmbedLockCleanup, lockPath, lockRoot, lockState, releaseEmbedLock as releaseLock, } from './embed-lock.js';
+import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from './load-gate.js';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
 function errnoInfo(error) {
     const e = error;
@@ -90,6 +92,7 @@ export function defaultSpawnWorker({ logPath, fallbackLogPath }, io = defaultSpa
         : ['ignore', opened.fd, opened.fd];
     const child = io.spawn(process.execPath, [entry, 'index', 'background', '--worker', ...logArgs], {
         detached: true,
+        windowsHide: true,
         stdio,
     });
     if (opened.fd !== null)
@@ -119,8 +122,10 @@ export function defaultBackgroundDependencies(hqRoot) {
         isProcessAlive: alive,
         resolveQmdBin: defaultResolveQmdBin,
         reconcileCollections: defaultReconcileCollections,
+        applyIndexSizeLimit: defaultApplyIndexSizeLimit,
         runQmd: defaultRunQmd,
         spawnWorker: defaultSpawnWorker,
+        writeStderr: (text) => process.stderr.write(text),
     };
 }
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
@@ -143,12 +148,6 @@ export function isHostedAgent(env = process.env) {
         || fs.existsSync('/etc/systemd/system/hq-agent-qmd-index.service')
         || fs.existsSync('/var/lib/hq-agent');
 }
-function lockRoot(home) {
-    return path.join(home, '.hq', 'locks');
-}
-function lockPath(home) {
-    return path.join(lockRoot(home), LOCK_NAME);
-}
 function completionPath(home) {
     return path.join(lockRoot(home), COMPLETE_NAME);
 }
@@ -163,16 +162,6 @@ function parseFields(file) {
         return undefined;
     }
 }
-function readOwner(directory) {
-    const fields = parseFields(path.join(directory, 'owner'));
-    if (!fields || !/^\d+$/.test(fields.pid ?? '') || !/^\d+$/.test(fields.ts ?? '') || !/^[A-Za-z0-9._-]+$/.test(fields.nonce ?? ''))
-        return undefined;
-    return { pid: Number(fields.pid), ts: Number(fields.ts), nonce: fields.nonce };
-}
-function graceSeconds(dependencies) {
-    const value = dependencies.env.QMD_HANDOFF_LOCK_GRACE_SEC;
-    return value && /^\d+$/.test(value) ? Number(value) : 5;
-}
 function dedupeSeconds(dependencies) {
     const value = dependencies.env.QMD_HANDOFF_DEDUPE_SEC;
     return value && /^\d+$/.test(value) ? Number(value) : 90;
@@ -195,187 +184,7 @@ function writeCompletion(home, dependencies) {
         // Completion is a best-effort dedupe hint, never a worker failure.
     }
 }
-function isOwnerlessLockWithinGrace(directory, dependencies) {
-    try {
-        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
-        return age < graceSeconds(dependencies);
-    }
-    catch {
-        return true;
-    }
-}
-function lockState(directory, dependencies) {
-    if (!fs.existsSync(directory))
-        return 'free';
-    const owner = readOwner(directory);
-    if (owner)
-        return dependencies.isProcessAlive(owner.pid) ? 'held' : 'stale';
-    return isOwnerlessLockWithinGrace(directory, dependencies) ? 'held' : 'stale';
-}
-function generation(directory) {
-    const owner = readOwner(directory);
-    if (owner)
-        return owner.nonce;
-    if (!fs.existsSync(directory))
-        return undefined;
-    return 'empty';
-}
-function removeDirectoryIfEmpty(directory) {
-    try {
-        fs.rmdirSync(directory);
-    }
-    catch { /* another claimant owns it, or it is already gone */ }
-}
-function claimWithinGrace(directory, dependencies) {
-    try {
-        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
-        return age < Math.max(5, graceSeconds(dependencies));
-    }
-    catch {
-        return true;
-    }
-}
-function acquireClaim(home, observedGeneration, dependencies) {
-    const claim = path.join(lockRoot(home), `qmd-reindex-bg.claim.${observedGeneration}`);
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            fs.mkdirSync(claim);
-        }
-        catch {
-            if (attempt === 1 || !recoverAbandonedClaim(claim, dependencies))
-                return undefined;
-            continue;
-        }
-        const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
-        try {
-            fs.mkdirSync(claimant);
-            // Test-only deterministic failure inject (unset in production) — shell
-            // parity with the script's claimant write_owner_record injection.
-            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
-                throw new Error('forced claimant write failure');
-            fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
-            return { claim, claimant };
-        }
-        catch {
-            fs.rmSync(claimant, { recursive: true, force: true });
-            removeDirectoryIfEmpty(claim);
-            return undefined;
-        }
-    }
-    return undefined;
-}
-/**
- * Reclaim only exact dead claimant names, then remove the claim directory if
- * empty. This mirrors the shell's no-fixed-path-reclaim rule: a peer that has
- * recreated claim.G with a new marker makes rmdir fail and wins the race.
- */
-function recoverAbandonedClaim(claim, dependencies) {
-    let entries;
-    try {
-        entries = fs.readdirSync(claim, { withFileTypes: true });
-    }
-    catch {
-        return true;
-    }
-    for (const entry of entries.filter((entry) => entry.name.startsWith('c.'))) {
-        const marker = path.join(claim, entry.name);
-        const fields = parseFields(path.join(marker, 'owner'));
-        const pid = fields && /^\d+$/.test(fields.pid ?? '') ? Number(fields.pid) : undefined;
-        if (pid !== undefined && dependencies.isProcessAlive(pid))
-            return false;
-        if (pid === undefined && claimWithinGrace(claim, dependencies))
-            return false;
-        const abandoned = `${claim}.stale-claim.${dependencies.pid}.${dependencies.random()}`;
-        try {
-            fs.renameSync(marker, abandoned);
-            fs.rmSync(abandoned, { recursive: true, force: true });
-        }
-        catch {
-            return false;
-        }
-    }
-    if (entries.length === 0 && claimWithinGrace(claim, dependencies))
-        return false;
-    removeDirectoryIfEmpty(claim);
-    return !fs.existsSync(claim);
-}
-function createAndPublishLock(home, dependencies) {
-    const directory = lockPath(home);
-    try {
-        fs.mkdirSync(directory);
-    }
-    catch {
-        return false;
-    }
-    const marker = path.join(directory, `acq.${dependencies.pid}.${dependencies.random()}`);
-    try {
-        fs.mkdirSync(marker);
-    }
-    catch {
-        removeDirectoryIfEmpty(directory);
-        return false;
-    }
-    const nonce = `${dependencies.pid}.${dependencies.random()}`;
-    const ownerFile = path.join(directory, 'owner');
-    const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
-    try {
-        // Test-only deterministic failure inject (unset in production) — shell
-        // parity: the script's write_owner_record honored the same variable.
-        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
-            throw new Error('forced owner write failure');
-        fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
-        fs.renameSync(temporary, ownerFile);
-        dependencies.afterOwnerPublish?.(ownerFile);
-        const verified = readOwner(directory);
-        if (!verified || verified.pid !== dependencies.pid || verified.nonce !== nonce)
-            throw new Error('owner publish verification failed');
-        fs.rmSync(marker, { recursive: true, force: true });
-        return true;
-    }
-    catch {
-        // The marker identifies only the directory this process created.  Do not
-        // recursively remove the fixed lock path after a failed publication.
-        fs.rmSync(marker, { recursive: true, force: true });
-        removeDirectoryIfEmpty(directory);
-        return false;
-    }
-}
-function claimAndReclaim(home, dependencies) {
-    const directory = lockPath(home);
-    const observedGeneration = generation(directory);
-    if (!observedGeneration || lockState(directory, dependencies) !== 'stale')
-        return false;
-    const acquired = acquireClaim(home, observedGeneration, dependencies);
-    if (!acquired)
-        return false;
-    try {
-        // Generation fencing: only move exactly the stale generation we observed.
-        if (generation(directory) !== observedGeneration || lockState(directory, dependencies) !== 'stale')
-            return false;
-        const abandoned = `${directory}.stale.${dependencies.pid}.${dependencies.random()}`;
-        fs.renameSync(directory, abandoned);
-        fs.rmSync(abandoned, { recursive: true, force: true });
-        return createAndPublishLock(home, dependencies);
-    }
-    catch {
-        return false;
-    }
-    finally {
-        fs.rmSync(acquired.claimant, { recursive: true, force: true });
-        removeDirectoryIfEmpty(acquired.claim);
-    }
-}
-function acquireLock(home, dependencies) {
-    fs.mkdirSync(lockRoot(home), { recursive: true });
-    return createAndPublishLock(home, dependencies) || claimAndReclaim(home, dependencies);
-}
-function releaseLock(home, dependencies) {
-    const directory = lockPath(home);
-    if (readOwner(directory)?.pid === dependencies.pid)
-        fs.rmSync(directory, { recursive: true, force: true });
-}
 export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
-    processEvents.once('exit', cleanup);
     // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
     // catchable cleanup. SIGINT/SIGTERM/SIGHUP are registered here (the shell
     // worker trapped `INT TERM HUP`; a detached worker's controlling terminal
@@ -383,9 +192,7 @@ export function installWorkerCleanup(cleanup, processEvents = process, exit = ()
     // process without releasing the lock) and the CLI's normal process exit then
     // runs the same idempotent owner release. Exiting prevents a synchronous
     // pipeline from continuing after it has released ownership.
-    processEvents.once('SIGINT', () => { cleanup(); exit(0); });
-    processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
-    processEvents.once('SIGHUP', () => { cleanup(); exit(0); });
+    installEmbedLockCleanup(cleanup, processEvents, exit);
 }
 function workerLogPath(env) {
     return env.QMD_REINDEX_LOG
@@ -420,6 +227,21 @@ function capWorkerLog(logPath, env) {
 function stepOutput(result) {
     return `${result.stdout ?? ''}${result.stderr ?? ''}`;
 }
+/**
+ * One worker-log line summarising the size cap, so an operator reading the log
+ * can see WHY a file stopped being indexed. Shaped defensively because the
+ * dependency is typed `unknown` at the seam.
+ */
+function sizeLimitOutput(result) {
+    const r = result;
+    if (typeof r?.maxBytes !== 'number')
+        return '';
+    if (r.maxBytes === 0)
+        return '[qmd-reindex-bg] size cap disabled\n';
+    const collections = r.collections ?? [];
+    const files = collections.reduce((total, collection) => total + collection.ignored.length, 0);
+    return `[qmd-reindex-bg] size cap ${r.maxBytes}B — ${files} file(s) skipped across ${collections.length} collection(s)\n`;
+}
 function errorOutput(error) {
     const e = error;
     return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
@@ -500,6 +322,17 @@ export async function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        // The size cap rewrites qmd's ignore lists, so it MUST land before the
+        // update below — an oversized file is skipped at glob time or not at all.
+        // Best-effort for the same reason as reconciliation: a capping failure must
+        // not suppress an otherwise healthy index update.
+        try {
+            const capped = dependencies.applyIndexSizeLimit(dependencies.hqRoot);
+            appendWorkerLog(logPath, sizeLimitOutput(capped));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+        }
         if (await signalWindow())
             return { state: 'terminated' };
         try {
@@ -520,8 +353,30 @@ export async function runBackgroundWorker(dependencies) {
         }
         if (await signalWindow())
             return { state: 'terminated' };
+        const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(dependencies.env);
+        let loadDecision;
+        try {
+            loadDecision = checkEmbedLoad(home, loadGateDependencies);
+        }
+        catch (error) {
+            if (error instanceof LoadGateConfigurationError) {
+                (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(`hq: ${error.message}\n`);
+                cleanup();
+                return { state: 'deferred' };
+            }
+            throw error;
+        }
+        if (loadDecision.action === 'skip') {
+            (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(loadDecision.notice);
+            writeCompletion(home, dependencies);
+            cleanup();
+            return { state: 'deferred' };
+        }
+        if (loadDecision.forced)
+            (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(loadDecision.notice);
         try {
             appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+            recordSuccessfulEmbed(home, loadGateDependencies);
         }
         catch (error) {
             appendWorkerLog(logPath, errorOutput(error)); // a completed embed attempt still permits the stamp

package/dist/lib/search-index/collection-path-repair-flag.d.ts

@@ -0,0 +1,4 @@
+export declare const QMD_COLLECTION_PATH_REPAIR_FLAG = "qmd.collection-path-repair";
+/** Keep collection-path repair off unless the hq-flags registry enables a canary. */
+export declare function qmdCollectionPathRepairEnabled(): boolean;
+//# sourceMappingURL=collection-path-repair-flag.d.ts.map

package/dist/lib/search-index/collection-path-repair-flag.js

@@ -0,0 +1,7 @@
+import { resolveProcessFlagGate } from '../flag-registry.js';
+export const QMD_COLLECTION_PATH_REPAIR_FLAG = 'qmd.collection-path-repair';
+/** Keep collection-path repair off unless the hq-flags registry enables a canary. */
+export function qmdCollectionPathRepairEnabled() {
+    return resolveProcessFlagGate(QMD_COLLECTION_PATH_REPAIR_FLAG, { fallback: false }, () => false);
+}
+//# sourceMappingURL=collection-path-repair-flag.js.map

package/dist/lib/search-index/embed-lock.d.ts

@@ -0,0 +1,34 @@
+export type EmbedLockDependencies = {
+    env: NodeJS.ProcessEnv;
+    now: () => number;
+    pid: number;
+    random: () => string;
+    isProcessAlive: (pid: number) => boolean;
+    /** Test seam for a contender arriving after mkdir and before owner publication. */
+    beforeOwnerPublish?: (ownerFile: string) => void;
+    /** Test seam for simulating a competing owner replacing the atomic record. */
+    afterOwnerPublish?: (ownerFile: string) => void;
+};
+export type EmbedLockProcessEvents = Pick<NodeJS.Process, 'once'> & {
+    removeListener?: NodeJS.Process['removeListener'];
+};
+export type EmbedLockRunResult = 'ran' | 'skipped' | 'busy' | 'unavailable';
+export declare function defaultEmbedLockDependencies(env?: NodeJS.ProcessEnv): EmbedLockDependencies;
+export declare function lockRoot(home: string): string;
+export declare function lockPath(home: string): string;
+export declare function lockState(directory: string, dependencies: EmbedLockDependencies): 'held' | 'stale' | 'free';
+export declare function acquireEmbedLock(home: string, dependencies: EmbedLockDependencies): boolean;
+export declare function releaseEmbedLock(home: string, dependencies: EmbedLockDependencies): void;
+/** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
+export declare function installEmbedLockCleanup(cleanup: () => void, processEvents?: EmbedLockProcessEvents, exit?: (code: number) => void): () => void;
+/**
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
+ *
+ * This deliberately does not install signal handlers. `run` is a synchronous
+ * qmd child, so JavaScript cannot execute a cleanup handler until it returns;
+ * registering SIGINT/SIGTERM would therefore suppress Node's immediate default
+ * termination. An interrupted owner is safely reclaimed through the lock's
+ * existing staleness and owner-grace protocol.
+ */
+export declare function runWithEmbedLock(home: string, dependencies: EmbedLockDependencies, run: () => 'skipped' | void): EmbedLockRunResult;
+//# sourceMappingURL=embed-lock.d.ts.map

package/dist/lib/search-index/embed-lock.js

@@ -0,0 +1,295 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
+ * update` / `qmd embed` (or another tool that does not call this module) cannot
+ * participate, because qmd is a third-party package and does not know about
+ * HQ's lock protocol.
+ */
+const EMBED_LOCK_NAME = 'qmd-reindex-bg.lock';
+export function defaultEmbedLockDependencies(env = process.env) {
+    return {
+        env,
+        now: () => Math.floor(Date.now() / 1_000),
+        pid: process.pid,
+        random: () => Math.random().toString(36).slice(2),
+        isProcessAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export function lockRoot(home) {
+    return path.join(home, '.hq', 'locks');
+}
+export function lockPath(home) {
+    return path.join(lockRoot(home), EMBED_LOCK_NAME);
+}
+function parseFields(file) {
+    try {
+        return Object.fromEntries(fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
+            const index = line.indexOf('=');
+            return index === -1 ? [] : [[line.slice(0, index), line.slice(index + 1)]];
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readOwner(directory) {
+    const fields = parseFields(path.join(directory, 'owner'));
+    if (!fields || !/^\d+$/.test(fields.pid ?? '') || !/^\d+$/.test(fields.ts ?? '') || !/^[A-Za-z0-9._-]+$/.test(fields.nonce ?? ''))
+        return undefined;
+    return { pid: Number(fields.pid), ts: Number(fields.ts), nonce: fields.nonce };
+}
+function graceSeconds(dependencies) {
+    const value = dependencies.env.QMD_HANDOFF_LOCK_GRACE_SEC;
+    return value && /^\d+$/.test(value) ? Number(value) : 5;
+}
+function isOwnerlessLockWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < graceSeconds(dependencies);
+    }
+    catch {
+        return true;
+    }
+}
+export function lockState(directory, dependencies) {
+    if (!fs.existsSync(directory))
+        return 'free';
+    const owner = readOwner(directory);
+    if (owner)
+        return dependencies.isProcessAlive(owner.pid) ? 'held' : 'stale';
+    return isOwnerlessLockWithinGrace(directory, dependencies) ? 'held' : 'stale';
+}
+function generation(directory) {
+    const owner = readOwner(directory);
+    if (owner)
+        return owner.nonce;
+    if (!fs.existsSync(directory))
+        return undefined;
+    return 'empty';
+}
+function removeDirectoryIfEmpty(directory) {
+    try {
+        fs.rmdirSync(directory);
+    }
+    catch { /* another claimant owns it, or it is already gone */ }
+}
+function claimWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < Math.max(5, graceSeconds(dependencies));
+    }
+    catch {
+        return true;
+    }
+}
+function acquireClaim(home, observedGeneration, dependencies) {
+    const claim = path.join(lockRoot(home), `qmd-reindex-bg.claim.${observedGeneration}`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.mkdirSync(claim);
+        }
+        catch {
+            if (attempt === 1 || !recoverAbandonedClaim(claim, dependencies))
+                return undefined;
+            continue;
+        }
+        const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
+        try {
+            fs.mkdirSync(claimant);
+            // Test-only deterministic failure inject (unset in production) — shell
+            // parity with the script's claimant write_owner_record injection.
+            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
+                throw new Error('forced claimant write failure');
+            fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
+            return { claim, claimant };
+        }
+        catch {
+            fs.rmSync(claimant, { recursive: true, force: true });
+            removeDirectoryIfEmpty(claim);
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reclaim only exact dead claimant names, then remove the claim directory if
+ * empty. This mirrors the shell's no-fixed-path-reclaim rule: a peer that has
+ * recreated claim.G with a new marker makes rmdir fail and wins the race.
+ *
+ * A process killed after the identity-safe rename and before its rmSync leaves
+ * a `*.stale-claim.*` directory behind. That name is intentionally forensic:
+ * it is no longer an active claim and records the interrupted reclaim for the
+ * feedback bundle, so no later acquirer should sweep it by a fixed path.
+ */
+function recoverAbandonedClaim(claim, dependencies) {
+    let entries;
+    try {
+        entries = fs.readdirSync(claim, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries.filter((entry) => entry.name.startsWith('c.'))) {
+        const marker = path.join(claim, entry.name);
+        const fields = parseFields(path.join(marker, 'owner'));
+        const pid = fields && /^\d+$/.test(fields.pid ?? '') ? Number(fields.pid) : undefined;
+        if (pid !== undefined && dependencies.isProcessAlive(pid))
+            return false;
+        if (pid === undefined && claimWithinGrace(claim, dependencies))
+            return false;
+        const abandoned = `${claim}.stale-claim.${dependencies.pid}.${dependencies.random()}`;
+        try {
+            fs.renameSync(marker, abandoned);
+            fs.rmSync(abandoned, { recursive: true, force: true });
+        }
+        catch {
+            return false;
+        }
+    }
+    if (entries.length === 0 && claimWithinGrace(claim, dependencies))
+        return false;
+    removeDirectoryIfEmpty(claim);
+    return !fs.existsSync(claim);
+}
+function createAndPublishLock(home, dependencies) {
+    const directory = lockPath(home);
+    try {
+        fs.mkdirSync(directory);
+    }
+    catch {
+        return false;
+    }
+    const marker = path.join(directory, `acq.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        fs.mkdirSync(marker);
+    }
+    catch {
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+    const nonce = `${dependencies.pid}.${dependencies.random()}`;
+    const ownerFile = path.join(directory, 'owner');
+    const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        // Test-only deterministic failure inject (unset in production) — shell
+        // parity: the script's write_owner_record honored the same variable.
+        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
+            throw new Error('forced owner write failure');
+        dependencies.beforeOwnerPublish?.(ownerFile);
+        fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
+        // renameSync replaces an existing owner on POSIX. A stale reclaim can
+        // replace this ownerless directory while this publisher is paused, so
+        // publish only if this exact generation still has no owner.
+        fs.linkSync(temporary, ownerFile);
+        fs.unlinkSync(temporary);
+        dependencies.afterOwnerPublish?.(ownerFile);
+        const verified = readOwner(directory);
+        if (!verified || verified.pid !== dependencies.pid || verified.nonce !== nonce)
+            throw new Error('owner publish verification failed');
+        fs.rmSync(marker, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        // The marker identifies only the directory this process created. Do not
+        // recursively remove the fixed lock path after a failed publication.
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* absent after link or moved with a stale generation */ }
+        fs.rmSync(marker, { recursive: true, force: true });
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+}
+function claimAndReclaim(home, dependencies) {
+    const directory = lockPath(home);
+    const observedGeneration = generation(directory);
+    if (!observedGeneration || lockState(directory, dependencies) !== 'stale')
+        return false;
+    const acquired = acquireClaim(home, observedGeneration, dependencies);
+    if (!acquired)
+        return false;
+    try {
+        // Generation fencing: only move exactly the stale generation we observed.
+        if (generation(directory) !== observedGeneration || lockState(directory, dependencies) !== 'stale')
+            return false;
+        const abandoned = `${directory}.stale.${dependencies.pid}.${dependencies.random()}`;
+        fs.renameSync(directory, abandoned);
+        fs.rmSync(abandoned, { recursive: true, force: true });
+        return createAndPublishLock(home, dependencies);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.rmSync(acquired.claimant, { recursive: true, force: true });
+        removeDirectoryIfEmpty(acquired.claim);
+    }
+}
+function tryAcquireEmbedLock(home, dependencies) {
+    try {
+        fs.mkdirSync(lockRoot(home), { recursive: true });
+        fs.accessSync(lockRoot(home), fs.constants.W_OK | fs.constants.X_OK);
+    }
+    catch {
+        return 'unavailable';
+    }
+    return createAndPublishLock(home, dependencies) || claimAndReclaim(home, dependencies)
+        ? 'acquired'
+        : 'busy';
+}
+export function acquireEmbedLock(home, dependencies) {
+    return tryAcquireEmbedLock(home, dependencies) === 'acquired';
+}
+export function releaseEmbedLock(home, dependencies) {
+    const directory = lockPath(home);
+    if (readOwner(directory)?.pid === dependencies.pid)
+        fs.rmSync(directory, { recursive: true, force: true });
+}
+/** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
+export function installEmbedLockCleanup(cleanup, processEvents = process, exit = (code) => process.exit(code)) {
+    const onExit = cleanup;
+    const onSignal = () => { cleanup(); exit(0); };
+    processEvents.once('exit', onExit);
+    processEvents.once('SIGINT', onSignal);
+    processEvents.once('SIGTERM', onSignal);
+    processEvents.once('SIGHUP', onSignal);
+    return () => {
+        processEvents.removeListener?.('exit', onExit);
+        processEvents.removeListener?.('SIGINT', onSignal);
+        processEvents.removeListener?.('SIGTERM', onSignal);
+        processEvents.removeListener?.('SIGHUP', onSignal);
+    };
+}
+/**
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
+ *
+ * This deliberately does not install signal handlers. `run` is a synchronous
+ * qmd child, so JavaScript cannot execute a cleanup handler until it returns;
+ * registering SIGINT/SIGTERM would therefore suppress Node's immediate default
+ * termination. An interrupted owner is safely reclaimed through the lock's
+ * existing staleness and owner-grace protocol.
+ */
+export function runWithEmbedLock(home, dependencies, run) {
+    const acquired = tryAcquireEmbedLock(home, dependencies);
+    if (acquired === 'unavailable')
+        return 'unavailable';
+    if (acquired === 'busy')
+        return 'busy';
+    try {
+        return run() === 'skipped' ? 'skipped' : 'ran';
+    }
+    finally {
+        releaseEmbedLock(home, dependencies);
+    }
+}
+//# sourceMappingURL=embed-lock.js.map