@hominis/fireforge 0.44.4 → 0.46.0

package/dist/src/core/config-validate.js

@@ -8,6 +8,8 @@ import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { describeProductVersionIncompatibility, FIREFOX_PRODUCTS, isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
+import { parseBuildAuditConfig } from './config-validate-build-audit.js';
+import { parsePatchLintFileSizeThresholds } from './config-validate-file-size.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
 /**
@@ -53,7 +55,8 @@ function parseIdentityFields(rec) {
 /**
  * Parses and validates the required `firefox` block: version shape,
  * product allowlist, product/version cross-compatibility, and the
- * optional sha256 digest (normalized to lowercase).
+ * optional sha256 digest (normalized to lowercase), optional
+ * `allowUnverifiedDownload` opt-out, optional candidate directory.
  */
 function parseFirefoxBlock(rec) {
     let firefoxRec;
@@ -84,6 +87,10 @@ function parseFirefoxBlock(rec) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
+    const allowUnverifiedDownload = firefoxRec.raw('allowUnverifiedDownload');
+    if (allowUnverifiedDownload !== undefined && typeof allowUnverifiedDownload !== 'boolean') {
+        throw new ConfigError('Config field "firefox.allowUnverifiedDownload" must be a boolean');
+    }
     const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
     if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
         throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
@@ -92,6 +99,7 @@ function parseFirefoxBlock(rec) {
         version: firefoxVersion,
         product: firefoxProduct,
         ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
+        ...(allowUnverifiedDownload !== undefined ? { allowUnverifiedDownload } : {}),
         ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
     };
 }
@@ -154,6 +162,10 @@ export function validateConfig(data) {
     const firefox = parseFirefoxBlock(rec);
     const config = { ...identity, firefox };
     parseBuildBlock(rec, config);
+    const buildAuditRaw = rec.raw('buildAudit');
+    if (buildAuditRaw !== undefined) {
+        config.buildAudit = parseBuildAuditConfig(buildAuditRaw);
+    }
     parseTestBlock(rec, config);
     parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
@@ -323,6 +335,7 @@ function optionalPatchLintBoolean(rec, key) {
 }
 /** Severity-gate fields, each parsed and assigned identically. */
 const PATCH_LINT_SEVERITY_GATE_KEYS = [
+    'prettier',
     'jsdocClassMethods',
     'testAssertionFloor',
     'chromeScriptJsDoc',
@@ -359,6 +372,10 @@ function parsePatchLintBlock(rec) {
         }
         out.rawColorAllowlist = rawColorAllowlist;
     }
+    const fileSizeThresholds = rec.raw('fileSizeThresholds');
+    if (fileSizeThresholds !== undefined) {
+        out.fileSizeThresholds = parsePatchLintFileSizeThresholds(fileSizeThresholds);
+    }
     for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
         const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
         if (gate !== undefined)
@@ -419,10 +436,10 @@ function parseTypecheckBlock(rec) {
     for (let i = 0; i < projectsRaw.length; i++) {
         const entry = projectsRaw[i];
         if (typeof entry !== 'string' || entry.trim() === '') {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a non-empty string`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a non-empty string`);
         }
         if (!isContainedRelativePath(entry)) {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a project-relative path`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a project-relative path`);
         }
         projects.push(entry);
     }

package/dist/src/core/config.d.ts

@@ -10,8 +10,8 @@
 import type { FireForgeConfig } from '../types/config.js';
 import type { JsonObject } from '../types/json.js';
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 /**
  * Checks if a fireforge.json exists in the given directory.

package/dist/src/core/config.js

@@ -18,20 +18,10 @@ import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
-/**
- * Config-file existence probe.
- *
- * Uses {@link pathExistsStrict} deliberately: a permission error probing
- * `fireforge.json` must propagate rather than read as "no config here",
- * which is what plain `pathExists` would report.
- */
-async function configPathExists(path) {
-    return fsUtils.pathExistsStrict(path);
-}
 /**
  * Checks if a fireforge.json exists in the given directory.
  * @param root - Root directory to check
@@ -39,7 +29,9 @@ async function configPathExists(path) {
  */
 export async function configExists(root) {
     const paths = getProjectPaths(root);
-    return configPathExists(paths.config);
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    return fsUtils.pathExistsStrict(paths.config);
 }
 /**
  * Loads and validates the fireforge.json configuration.
@@ -49,7 +41,9 @@ export async function configExists(root) {
  */
 export async function loadConfig(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
@@ -81,7 +75,9 @@ export async function loadConfig(root) {
  */
 export async function loadRawConfigDocument(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {

package/dist/src/core/coverage-extend.js

@@ -34,10 +34,10 @@
  * staging stale while extend still vouches for it. Plain REPLACE has no such
  * window, because the earlier scope simply stops being covered.
  */
-import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
 import { getHead, isMissingHeadError } from './git.js';
@@ -144,7 +144,7 @@ export function formatExtendCoverageRefusal(result) {
                 `longer anchored. ${remedy}`);
         case 'fingerprint-diverged':
             return ('--extend-coverage refused: ' +
-                `${String(result.detail.length)} packageable file(s) the recorded build staged have changed ` +
+                `${result.detail.length} packageable file(s) the recorded build staged have changed ` +
                 `since (${formatDivergedPaths(result.detail)}). Extending would vouch for the earlier scope ` +
                 `while obj-*/_tests/ still holds its stale staging. ${remedy}`);
         case 'mozconfig-changed':
@@ -156,7 +156,7 @@ export function formatExtendCoverageRefusal(result) {
 function formatDivergedPaths(paths) {
     const head = paths.slice(0, MAX_DIVERGED_REPORTED).join(', ');
     const extra = paths.length - Math.min(paths.length, MAX_DIVERGED_REPORTED);
-    return extra > 0 ? `${head}, … (+${String(extra)} more)` : head;
+    return extra > 0 ? `${head}, … (+${extra} more)` : head;
 }
 /**
  * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
@@ -168,7 +168,7 @@ function formatDivergedPaths(paths) {
 export async function hashEngineFile(engineDir, relPath) {
     try {
         const buffer = await readFile(join(engineDir, relPath));
-        return createHash('sha256').update(buffer).digest('hex');
+        return sha256Hex(buffer);
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT') {

package/dist/src/core/discard-baseline.js

@@ -226,22 +226,22 @@ export function summarizeDiscardBaselines(plans, succeeded) {
     const deleted = plans.filter((p) => p.kind === 'patch-deleted').length;
     const unmanaged = plans.filter((p) => p.kind === 'unmanaged').length;
     if (patchBacked + created + deleted === 0) {
-        return `${String(succeeded)} file(s) restored to upstream state`;
+        return `${succeeded} file(s) restored to upstream state`;
     }
     const parts = [];
     if (patchBacked > 0)
-        parts.push(`${String(patchBacked)} to patch baseline`);
+        parts.push(`${patchBacked} to patch baseline`);
     if (created > 0)
-        parts.push(`${String(created)} re-materialized`);
+        parts.push(`${created} re-materialized`);
     if (deleted > 0)
-        parts.push(`${String(deleted)} removed per patch baseline`);
+        parts.push(`${deleted} removed per patch baseline`);
     if (unmanaged > 0)
-        parts.push(`${String(unmanaged)} to upstream state`);
-    return `${String(succeeded)} file(s) restored: ${parts.join(', ')}`;
+        parts.push(`${unmanaged} to upstream state`);
+    return `${succeeded} file(s) restored: ${parts.join(', ')}`;
 }
 /** Warn text for a multi-owner (conflicted) restore. */
 export function describeConflictWarning(plan) {
-    return (`${plan.entry.file} is claimed by ${String(plan.owners.length)} patches ` +
+    return (`${plan.entry.file} is claimed by ${plan.owners.length} patches ` +
         `(${plan.owners.join(', ')}). Restored the cumulative baseline; run ` +
         '"fireforge status --ownership" to resolve ownership.');
 }

package/dist/src/core/engine-precondition.d.ts

@@ -19,13 +19,6 @@ export interface EngineGitReadyOptions {
      */
     unbornHeadSuffix?: string;
 }
-/**
- * Error factory for callers whose domain uses a class other than
- * `GeneralError`. The furnace family raises `FurnaceError`, which carries
- * its own `userMessage` and exit code 9, so a helper hardcoding
- * `GeneralError` would silently change both.
- */
-export type PreconditionErrorFactory = (message: string) => Error;
 /**
  * Asserts only that the engine checkout EXISTS.
  *
@@ -36,9 +29,8 @@ export type PreconditionErrorFactory = (message: string) => Error;
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export declare function assertEngineExists(engineDir: string, errorFactory?: PreconditionErrorFactory): Promise<void>;
+export declare function assertEngineExists(engineDir: string): Promise<void>;
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
  * commit — in that order, so the operator gets the most specific applicable

package/dist/src/core/engine-precondition.js

@@ -20,8 +20,6 @@ const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet
     // No terminating period: the suffix below supplies its own punctuation, and
     // hardcoding one here rendered as "…cleanly., then retry the rebase."
     'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
-/** Default factory: the message every non-furnace command already used. */
-const defaultErrorFactory = (message) => new GeneralError(message);
 /**
  * Asserts only that the engine checkout EXISTS.
  *
@@ -32,11 +30,10 @@ const defaultErrorFactory = (message) => new GeneralError(message);
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export async function assertEngineExists(engineDir, errorFactory = defaultErrorFactory) {
+export async function assertEngineExists(engineDir) {
     if (!(await pathExists(engineDir))) {
-        throw errorFactory('Firefox source not found. Run "fireforge download" first.');
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
 }
 /**
@@ -48,9 +45,7 @@ export async function assertEngineExists(engineDir, errorFactory = defaultErrorF
  * @param options - Optional per-command message tailoring
  */
 export async function assertEngineGitReady(engineDir, options = {}) {
-    if (!(await pathExists(engineDir))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
+    await assertEngineExists(engineDir);
     if (!(await isGitRepository(engineDir))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }

package/dist/src/core/engine-session-lock.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { InconclusiveVerdictError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
 import { readLockStatus, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
@@ -21,19 +22,19 @@ const MAX_WAIT_LOCK_MS = 3600 * 1000;
  * owner file degrades to the anonymous form.
  */
 function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
-    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
     // Queue position: under several concurrent sessions the wait
     // line alone left operators inferring their place from `ps`.
     const position = queue === undefined || queue.depth === 0
         ? ''
         : queue.ahead === 0
-            ? ` You are next in a queue of ${String(queue.depth)}.`
-            : ` ${String(queue.ahead)} ahead of you (queue of ${String(queue.depth)}).`;
+            ? ` You are next in a queue of ${queue.depth}.`
+            : ` ${queue.ahead} ahead of you (queue of ${queue.depth}).`;
     if (holder === undefined) {
         return `Waiting for the FireForge engine lock — ${progress}.${position}`;
     }
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.${position}`;
+    return `Waiting for the FireForge engine lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
 }
 /**
  * Formats the notice printed when the wait budget is EXTENDED because the
@@ -45,10 +46,10 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
  * number they typed would otherwise conclude the timeout is broken.
  */
 export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
-    const position = ahead === 0 ? 'you are now next' : `${String(ahead)} still ahead of you`;
+    const position = ahead === 0 ? 'you are now next' : `${ahead} still ahead of you`;
     return (`The queue advanced (${position}), so the engine-lock wait was extended to ` +
-        `${String(Math.round(budgetMs / 1000))}s total (you asked for ` +
-        `${String(Math.round(requestedMs / 1000))}s). A queue that stops moving still ` +
+        `${Math.round(budgetMs / 1000)}s total (you asked for ` +
+        `${Math.round(requestedMs / 1000)}s). A queue that stops moving still ` +
         `gives up on the budget you asked for.`);
 }
 /**
@@ -128,15 +129,15 @@ export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
     }
     const elapsed = snapshot.heldForMs === undefined
         ? 'unknown duration'
-        : `${String(Math.round(snapshot.heldForMs / 1000))}s`;
+        : `${Math.round(snapshot.heldForMs / 1000)}s`;
     const holder = snapshot.holder;
     const identity = holder === undefined
         ? 'held by an unidentified process (no readable owner record)'
-        : `held by PID ${String(holder.pid)}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
+        : `held by PID ${holder.pid}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
             (holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '');
     const lines = [
         `Engine session lock: ${identity}, for ${elapsed}.`,
-        `Queue depth: ${String(snapshot.queueDepth)} waiter(s).`,
+        `Queue depth: ${snapshot.queueDepth} waiter(s).`,
     ];
     // Liveness answers "does the process exist"; it does not answer "is it
     // getting anywhere". A holder alive for minutes having used a fraction of
@@ -182,7 +183,7 @@ export async function snapshotEngineGeneration(engineDir) {
             // and is reported immediately.
             if (!isIndexLockError(error) || attempt === GENERATION_PROBE_ATTEMPTS - 1)
                 break;
-            await delay(GENERATION_PROBE_RETRY_MS);
+            await sleep(GENERATION_PROBE_RETRY_MS);
         }
     }
     return `${UNAVAILABLE_PREFIX}${toError(lastError).message}`;
@@ -191,11 +192,6 @@ export async function snapshotEngineGeneration(engineDir) {
 const GENERATION_PROBE_ATTEMPTS = 3;
 /** Pause between generation-probe attempts. */
 const GENERATION_PROBE_RETRY_MS = 250;
-function delay(ms) {
-    return new Promise((resolveDelay) => {
-        setTimeout(resolveDelay, ms);
-    });
-}
 /**
  * True when a git failure is the transient index-lock contention shape
  * (`Unable to create '…/.git/index.lock': File exists`) rather than a
@@ -290,7 +286,7 @@ export function describeEngineGenerationDelta(before, after) {
             return;
         const head = records.slice(0, DELTA_ENTRY_LIMIT);
         const truncated = records.length - head.length;
-        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${String(truncated)} more)` : ''}`);
+        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${truncated} more)` : ''}`);
     };
     render('Working-tree entries that appeared', appeared);
     render('Working-tree entries that went away', disappeared);

package/dist/src/core/export-moved-code-shape.js

@@ -114,14 +114,14 @@ export function formatAdoptThenSplitRemedy(overlaps, newPatchName, insertionOrde
     const suggestedName = newPatchName.replace(/^\d+-/, '').replace(/\.patch$/, '');
     return [
         '',
-        `This looks like a new-file + moved-code slice: ${String(strongest.sharedLines)} substantive ` +
+        `This looks like a new-file + moved-code slice: ${strongest.sharedLines} substantive ` +
             `line(s) the new file(s) would add are still carried by ${strongest.sourcePatch}. ` +
             'Exporting them as their own patch cannot pass cross-patch lint while the source patch ' +
             'still owns the same code, and re-exporting cannot adopt them while they are unmanaged — ' +
             'each guard is right, and together they dead-end.',
         'Working sequence (adopt, then split):',
         `  1. fireforge re-export ${strongest.sourcePatch} --scan ${fileArgs}`,
-        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${String(insertionOrder)} ${moveArgs}`,
+        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${insertionOrder} ${moveArgs}`,
         'Step 1 adopts the new files into the patch that already owns the moved lines; step 2 ' +
             'splits them back out as one transaction, so the queue is never in a state where two ' +
             'patches own the same code.',

package/dist/src/core/file-lock-owner.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Filename of a lock directory's owner record, relative to the lock dir.
+ *
+ * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
+ * the constant instead of re-spelling `'pid'`; the file *format* is
+ * documented on {@link readLockOwner}.
+ */
+export declare const LOCK_PID_FILE = "pid";
+/**
+ * Owner record read back from a lock directory's PID file.
+ *
+ * `token` is the per-acquisition UUID written on line 2 of the PID file,
+ * `acquiredAtMs` the wall-clock time the record was written (diagnostic),
+ * and `startTick` the writer's boot-relative start tick (liveness). Records
+ * from releases before a field was introduced parse with it `undefined`;
+ * readers must treat that as "unknown", never as a mismatch.
+ */
+export type LockOwner = {
+    present: false;
+} | {
+    present: true;
+    pid: number;
+    token?: string;
+    acquiredAtMs?: number;
+    startTick?: number;
+    metadata: string[];
+};
+/**
+ * Reads the owner PID (line 1), acquisition token (line 2), the mechanical
+ * `acquired-at-ms=` / `start-tick=` lines (when present), and diagnostic
+ * metadata (the remaining lines 3+) from a lock directory's PID file.
+ * Returns `{ present: false }` when the PID file is missing, unreadable, or
+ * the PID does not parse as a finite integer (caller falls back to the
+ * age-only staleness heuristic).
+ *
+ * File format note: external readers do `parseInt(content.trim(), 10)`,
+ * which parses the leading digits of a multi-line file — so the token and
+ * mechanical lines stay compatible.
+ *
+ * @param lockPath - Lock directory whose owner record to read
+ * @returns The parsed owner record, or `{ present: false }`
+ */
+export declare function readLockOwner(lockPath: string): Promise<LockOwner>;
+/**
+ * Stamps this process's ownership (PID, per-acquisition token, acquisition
+ * time, own start tick, diagnostic metadata) into a lock directory it has
+ * just created, and reads the record back to prove it landed.
+ *
+ * The write is FATAL. It used to be best-effort, on the theory that stale
+ * recovery would fall back to the age heuristic — but that heuristic reaps
+ * any owner-less lock after five minutes, and the build lock legitimately
+ * holds for hours. A holder whose record failed to write was therefore
+ * reaped mid-build and a second process entered the critical section. On
+ * failure the just-created lock directory is removed (nothing else can own
+ * it yet) and a {@link GeneralError} names the cause.
+ *
+ * @param lockPath - Lock directory this process has just `mkdir`'d
+ * @param token - Per-acquisition UUID, later checked by release
+ * @param ownerMetadata - Extra human-diagnostic lines (see `FileLockOptions.ownerMetadata`)
+ * @throws {GeneralError} When the record cannot be written or does not read back as written
+ */
+export declare function writeLockOwner(lockPath: string, token: string, ownerMetadata: readonly string[] | undefined): Promise<void>;
+/**
+ * Boot-relative start tick of a process, where the platform exposes it
+ * cheaply.
+ *
+ * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
+ * Elsewhere (macOS, Windows) obtaining a start time means spawning
+ * `ps`/`wmic` per probe, which is not worth paying on every poll of a
+ * contended lock — those platforms return `undefined` and liveness stays
+ * PID-only.
+ *
+ * Deliberately NOT converted to wall-clock time via `/proc/stat` `btime`:
+ * on current kernels `btime` is derived from the realtime clock and moves
+ * with every clock step, so a wall-clock comparison against a recorded
+ * acquisition time misjudges a live holder as a reused PID after NTP steps
+ * the clock forward — and reaps a lock that is in use.
+ *
+ * @param pid - Process to look up
+ * @param procRoot - procfs mount, overridable for tests
+ * @returns Start tick, or `undefined` when unobtainable
+ */
+export declare function readProcessStartTick(pid: number, procRoot?: string): number | undefined;
+/**
+ * Whether the process named by a lock's owner record is the SAME process
+ * that acquired the lock, not merely a live process wearing its PID.
+ *
+ * `isProcessAlive` answers "does this PID exist"; after a holder crashes,
+ * the kernel may hand its PID to a long-lived daemon, and a PID-only check
+ * then honours the dead lock until the waiter's timeout. Where the record
+ * carries the writer's start tick and the candidate's own tick is cheaply
+ * obtainable (see {@link readProcessStartTick}), the two must be equal: a
+ * different tick is a different process. Records without a start tick, and
+ * platforms without one, keep the PID-only answer.
+ *
+ * @param owner - Owner record fields that identify the holder
+ * @param procRoot - procfs mount, overridable for tests
+ * @returns True when the original holder is still running (or cannot be proven gone)
+ */
+export declare function isLockOwnerAlive(owner: {
+    pid: number;
+    startTick?: number | undefined;
+}, procRoot?: string): boolean;