@hominis/fireforge 0.40.0 → 0.42.0

package/dist/src/core/wire-subscript.js

@@ -7,7 +7,7 @@ import MagicString from 'magic-string';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
@@ -28,7 +28,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     walkAST(ast, {
         enter(node) {
             if (node.type === 'TryStatement') {
-                const n = node;
+                const n = asEstree(node);
                 const src = getNodeSource(content, n);
                 if (src.includes('loadSubScript')) {
                     tryNodes.push(n);
@@ -137,7 +137,15 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
     }

package/dist/src/core/wire-utils.js

@@ -1,5 +1,5 @@
 import { GeneralError, ParserFallbackError } from '../errors/base.js';
-import { walkAST } from './ast-utils.js';
+import { asEstree, walkAST } from './ast-utils.js';
 /**
  * Validates a name for safe interpolation into generated JavaScript string literals.
  * Rejects strings containing characters that could break out of JS strings or inject code.
@@ -336,13 +336,13 @@ export function findMethodBody(ast, methodName) {
             if (found)
                 return;
             if (node.type === 'Property') {
-                const prop = node;
+                const prop = asEstree(node);
                 if (prop.key.type === 'Identifier' &&
                     names.includes(prop.key.name) &&
                     (prop.value.type === 'FunctionExpression' ||
                         prop.value.type === 'ArrowFunctionExpression')) {
-                    const fn = prop.value;
-                    found = fn.body;
+                    const fn = asEstree(prop.value);
+                    found = asEstree(fn.body);
                 }
             }
         },

package/dist/src/core/xpcshell-appdir.js

@@ -203,6 +203,7 @@ export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
             entries = await readdir(distDir);
         }
         catch {
+            // No readable dist directory means no appdir candidate can be resolved.
             return null;
         }
         for (const entry of entries) {
@@ -254,6 +255,8 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
             body = await readText(manifestPath);
         }
         catch {
+            // An unreadable manifest cannot declare an appdir; skip it and keep
+            // walking the remaining candidates.
             continue;
         }
         // Operator already migrated — harness will read the appname-keyed

package/dist/src/errors/base.d.ts

@@ -83,6 +83,19 @@ export declare class ExecTimeoutError extends FireForgeError {
     timeoutMs: number, cause?: unknown);
     get userMessage(): string;
 }
+/**
+ * Error thrown when a file-lock wait times out because another process
+ * holds the lock (FORGE H5).
+ *
+ * Dedicated subclass so the CLI boundary renders lock contention as the
+ * one-line reason-first/remedy-second refusal it is — before this, the
+ * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
+ * as an internal failure and prints with a five-frame stack. The refusal
+ * was always correct; the presentation made it look like a crash.
+ */
+export declare class LockContentionError extends FireForgeError {
+    readonly code: 1;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/base.js

@@ -113,6 +113,19 @@ export class ExecTimeoutError extends FireForgeError {
             'If the host is just slow or loaded, re-running may succeed.');
     }
 }
+/**
+ * Error thrown when a file-lock wait times out because another process
+ * holds the lock (FORGE H5).
+ *
+ * Dedicated subclass so the CLI boundary renders lock contention as the
+ * one-line reason-first/remedy-second refusal it is — before this, the
+ * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
+ * as an internal failure and prints with a five-frame stack. The refusal
+ * was always correct; the presentation made it look like a crash.
+ */
+export class LockContentionError extends FireForgeError {
+    code = ExitCode.GENERAL_ERROR;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/rebase.d.ts

@@ -18,3 +18,16 @@ export declare class RebaseSessionExistsError extends RebaseError {
 export declare class NoRebaseSessionError extends RebaseError {
     constructor();
 }
+/**
+ * Thrown when the session file exists but cannot be used.
+ *
+ * This case had no error of its own before 0.41.0 and was reported as
+ * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
+ * reported {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command pointed at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` now clears a corrupt session rather than
+ * refusing to run against one.
+ */
+export declare class CorruptRebaseSessionError extends RebaseError {
+    constructor(sessionPath: string, reason: string);
+}

package/dist/src/errors/rebase.js

@@ -32,3 +32,20 @@ export class NoRebaseSessionError extends RebaseError {
         super('No rebase session in progress. Start one with "fireforge rebase".');
     }
 }
+/**
+ * Thrown when the session file exists but cannot be used.
+ *
+ * This case had no error of its own before 0.41.0 and was reported as
+ * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
+ * reported {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command pointed at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` now clears a corrupt session rather than
+ * refusing to run against one.
+ */
+export class CorruptRebaseSessionError extends RebaseError {
+    constructor(sessionPath, reason) {
+        super(`The rebase session at ${sessionPath} cannot be read (${reason}).\n` +
+            'Run "fireforge rebase --abort" to discard it and restore the engine, ' +
+            'or delete the file to start over.');
+    }
+}

package/dist/src/types/commands/options.d.ts

@@ -289,6 +289,31 @@ export interface ReExportOptions {
      * explicitly.
      */
     refuseAdjacentUnmanaged?: boolean;
+    /**
+     * Bypass per-patch lint result cache reads AND writes for this
+     * invocation (`--no-cache`). The cache is what makes a repeat
+     * re-export of an unchanged patch skip the checkJs program build
+     * entirely (FORGE J1).
+     */
+    noCache?: boolean;
+    /**
+     * Refuse (non-zero exit, patch not written) a re-export whose refreshed
+     * body would absorb engine lines not present in the old patch body —
+     * the multi-session guard against silently capturing another session's
+     * uncommitted edits in files the patch already owns. The drift preview
+     * always prints; this flag turns it into a hard stop. Mutually
+     * exclusive with `--scan` and `--files`.
+     */
+    refuseForeignDrift?: boolean;
+    /**
+     * Engine-relative files whose drift is EXPECTED (`--expect`, repeatable;
+     * requires `--refuse-foreign-drift`). The content-based drift detector
+     * cannot tell the exporting session's own slice edits from another
+     * session's (FORGE L6), so a real slice export under the refusal flag
+     * names its intended files here: drift confined to expected files
+     * proceeds, drift anywhere else still refuses.
+     */
+    expect?: string[];
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -386,6 +411,8 @@ export interface PatchSplitOptions {
     forceUnsafe?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -413,6 +440,8 @@ export interface PatchMoveFilesOptions {
     forceUnsafe?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the rebase command.
@@ -484,6 +513,24 @@ export interface TestOptions {
     headless?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
+    /**
+     * Run the scoped pre-test build (packaging exactly the requested paths,
+     * MIXED harnesses allowed) and exit without dispatching tests. One
+     * ~10-minute build then covers both an xpcshell and a browser-chrome
+     * half of a slice; run each harness afterwards without `--build`
+     * (FORGE J9). Emits `FIREFORGE-VERDICT: PASS` on success.
+     */
+    buildOnly?: boolean;
+    /**
+     * Union the paths this build packages onto the recorded coverage claim
+     * instead of REPLACING it (FORGE L1), so successive scoped builds
+     * accumulate and an earlier slice's build-less runs stay covered. Valid
+     * only with `--build`/`--build-only` and explicit paths. Refused
+     * fail-closed unless the build anchor is unchanged: same engine HEAD,
+     * same `engine/mozconfig`, and every previously fingerprinted packageable
+     * file byte-identical. See `src/core/coverage-extend.ts`.
+     */
+    extendCoverage?: boolean;
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -745,6 +792,8 @@ export interface PatchDeleteOptions {
     dryRun?: boolean;
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the `fireforge patch rename` subcommand. Updates the
@@ -760,9 +809,22 @@ export interface PatchRenameOptions {
      * New human-readable name. Sanitised the same way `export --name`
      * sanitises into the filename slug (lowercase, non-alphanumerics
      * collapsed to `-`, length-capped). The patch's `name` field stores
-     * the raw value; the filename uses the sanitised slug.
+     * the raw value; the filename uses the sanitised slug. Optional when
+     * `--category`/`--order`/`--description` carry the change.
      */
     to?: string;
+    /**
+     * New category (validated against configured categories). Rewrites
+     * the filename prefix and the manifest row in one transaction —
+     * recategorising no longer requires `patch delete` + fresh export.
+     */
+    category?: string;
+    /**
+     * Move the patch to this exact UNUSED sparse order. Collisions refuse
+     * with a pointer to `patch reorder` (which renumbers siblings); an
+     * order change is projected through cross-patch lint first.
+     */
+    order?: number;
     /**
      * Replacement description. Omit to leave the description unchanged
      * (intentional — operators frequently want to relabel the slug
@@ -775,6 +837,8 @@ export interface PatchRenameOptions {
     yes?: boolean;
     /** Bypass force-mode patchPolicy refusals. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the patch reorder command.
@@ -786,6 +850,8 @@ export interface PatchReorderOptions {
     yes?: boolean;
     dryRun?: boolean;
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the patch compact command.
@@ -797,6 +863,8 @@ export interface PatchCompactOptions {
     dryRun?: boolean;
     /** Bypass force-mode patchPolicy refusals. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the status command.
@@ -819,6 +887,23 @@ export interface StatusOptions {
     testCoverage?: boolean;
     /** Output machine-readable JSON instead of human-readable text. */
     json?: boolean;
+    /**
+     * With `--json`: emit only the summary counts (plus the offending
+     * files per fail-set classification when the `--check`/`--fail-on`
+     * policy is active), omitting the per-file `files[]` payload that
+     * grows with the queue (FORGE K8). Refused without `--json`.
+     */
+    summary?: boolean;
+    /**
+     * With `--json` (and composing with `--summary`), append an additive
+     * `ownership` block — the flat path→owning-patch rows plus
+     * managed/unmanaged/conflict counts — so a gate reads ownership,
+     * classification, and the check verdict from ONE scan instead of three
+     * back-to-back `status` invocations (FORGE L3). A modifier, not a mode:
+     * exit semantics are unchanged, so ownership conflicts still fail only
+     * the human `--ownership` mode. Refused without `--json`.
+     */
+    includeOwnership?: boolean;
     /**
      * Exit non-zero when any classification in the fail policy is
      * non-empty (default policy: unmanaged, patch-owned-drift, conflict).

package/dist/src/types/commands/patches.d.ts

@@ -212,6 +212,14 @@ export interface PatchLintIssue {
     fingerprint?: string;
     /** Human-readable description of the issue */
     message: string;
+    /**
+     * Queue entry filenames this issue implicates (the declaring/importing
+     * patch, or every creator for a duplicate-creation clash). Used by the
+     * export placement gate to attribute projected errors to the exported
+     * patch vs pre-existing patches without parsing messages or the
+     * rename-sensitive fingerprint (FORGE K9).
+     */
+    patches?: string[];
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
     /**

package/dist/src/types/furnace.d.ts

@@ -260,6 +260,13 @@ export interface ApplyResult {
      * persisted — the engine has been restored to its pre-apply state.
      */
     rolledBack?: boolean;
+    /**
+     * Operator-facing warnings, printed by `logApplyResult`. Populated when
+     * apply overwrote a deployed, patch-owned file whose engine bytes
+     * differed from the component source (FORGE J6) — the case where a
+     * shipped engine-only fix is silently reverted by the copy.
+     */
+    warnings?: string[];
 }
 /**
  * An action that would be performed during a dry-run deploy.

package/dist/src/utils/build-info.d.ts

@@ -0,0 +1,31 @@
+/** Source identity of the running build. */
+export interface BuildIdentity {
+    shortCommit: string;
+    dirty: boolean;
+    /**
+     * Content hash of the uncommitted diff, present only for a DIRTY
+     * installed build (FORGE L8). Two packs from the same HEAD with
+     * different uncommitted content share `shortCommit` and the `.dirty`
+     * marker, so without this they report byte-identical `--version`
+     * strings — which is what made a field report against
+     * `0.41.0+g<sha>.dirty` impossible to trace back to a specific pack.
+     * Absent in a git checkout: identity there comes from live git, and
+     * hashing the full diff on every `--version` call is not worth it.
+     */
+    dirtyHash?: string;
+}
+/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+export declare function readBuildInfoFile(packageRoot: string): BuildIdentity | null;
+type GitRunner = (args: string[]) => string;
+/** @internal Live git identity of the checkout; null when git is unusable. */
+export declare function readGitBuildIdentity(runGit?: GitRunner): BuildIdentity | null;
+/**
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * null identity. The trailing content hash appears only for a dirty
+ * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * segment stays valid semver build metadata (dot-separated alphanumerics).
+ */
+export declare function formatVersionWithIdentity(version: string, identity: BuildIdentity | null): string;
+/** The `--version` string: semver plus build identity when known. */
+export declare function getCliVersion(): string;
+export {};

package/dist/src/utils/build-info.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Build identity for `--version` (FORGE K2/K3/L8). Three distinct builds
+ * shipped as plain "0.41.0" — consumers had to fingerprint tarballs by
+ * sha256 to know which build a claim was verified against. `--version`
+ * now reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
+ *
+ * - In a git checkout (dev runs via tsx), identity comes from live git —
+ *   a stale `dist/build-info.json` from an old build must never win.
+ * - In an installed package, it comes from `dist/build-info.json`,
+ *   stamped by scripts/generate-build-info.mjs at build/pack time.
+ * - When neither yields an identity, `--version` degrades to the plain
+ *   semver. Reading identity must never throw.
+ *
+ * Deliberately NOT wired into the per-patch lint cache key: identity
+ * would churn the cache on every commit at the same semver for no
+ * correctness gain (`getPackageVersion` stays the cache input).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPackageRoot, getPackageVersion } from './package-root.js';
+import { isObject } from './validation.js';
+/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+export function readBuildInfoFile(packageRoot) {
+    try {
+        const raw = readFileSync(join(packageRoot, 'dist', 'build-info.json'), 'utf-8');
+        const data = JSON.parse(raw);
+        if (!isObject(data) || data['schemaVersion'] !== 1)
+            return null;
+        const shortCommit = data['shortCommit'];
+        const dirty = data['dirty'];
+        if (typeof shortCommit !== 'string' || shortCommit.length === 0)
+            return null;
+        const dirtyHash = data['dirtyHash'];
+        return {
+            shortCommit,
+            dirty: dirty === true,
+            ...(typeof dirtyHash === 'string' && dirtyHash.length > 0 ? { dirtyHash } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const defaultGitRunner = (args) => execFileSync('git', args, {
+    cwd: getPackageRoot(),
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+});
+/** @internal Live git identity of the checkout; null when git is unusable. */
+export function readGitBuildIdentity(runGit = defaultGitRunner) {
+    try {
+        const commit = runGit(['rev-parse', 'HEAD']).trim();
+        if (!/^[0-9a-f]{7,40}$/.test(commit))
+            return null;
+        const status = runGit(['status', '--porcelain']);
+        return { shortCommit: commit.slice(0, 12), dirty: status.length > 0 };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the running build's identity: live git in a checkout (covers
+ * worktrees, whose `.git` is a file), else the stamped build-info file,
+ * else null. Never throws.
+ */
+function getBuildIdentity() {
+    try {
+        const packageRoot = getPackageRoot();
+        if (existsSync(join(packageRoot, '.git'))) {
+            return readGitBuildIdentity();
+        }
+        return readBuildInfoFile(packageRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * null identity. The trailing content hash appears only for a dirty
+ * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * segment stays valid semver build metadata (dot-separated alphanumerics).
+ */
+export function formatVersionWithIdentity(version, identity) {
+    if (identity === null)
+        return version;
+    if (!identity.dirty)
+        return `${version}+g${identity.shortCommit}`;
+    const contentHash = identity.dirtyHash === undefined ? '' : `.${identity.dirtyHash}`;
+    return `${version}+g${identity.shortCommit}.dirty${contentHash}`;
+}
+/** The `--version` string: semver plus build identity when known. */
+export function getCliVersion() {
+    return formatVersionWithIdentity(getPackageVersion(), getBuildIdentity());
+}

package/dist/src/utils/concurrency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bounded-concurrency helpers shared by commands that fan out per-file IO
+ * (status classification, import's unmanaged-dirty guard, re-export scans,
+ * the dry-run purity guard). Kept deliberately tiny: one order-preserving
+ * mapper, no queues, no cancellation.
+ */
+/** Maps items with at most `limit` in-flight promises. Preserves order. */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -0,0 +1,21 @@
+/**
+ * Bounded-concurrency helpers shared by commands that fan out per-file IO
+ * (status classification, import's unmanaged-dirty guard, re-export scans,
+ * the dry-run purity guard). Kept deliberately tiny: one order-preserving
+ * mapper, no queues, no cancellation.
+ */
+/** Maps items with at most `limit` in-flight promises. Preserves order. */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/dist/src/utils/errors.d.ts

@@ -1,2 +1,41 @@
+/**
+ * Throwable normalisation primitives.
+ *
+ * **This module must import nothing.** It sits at the very bottom of the
+ * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it — so it is the one place a shared helper can live and be
+ * provably cycle-immune. Adding an import here makes that whole subtree
+ * reachable from every util, and any future `src/errors/*` module wanting a
+ * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
+ * that would like `getNodeErrorCode`) then closes the loop and fails the
+ * `dpdm --exit-code circular:1` release gate. A helper that needs an import
+ * belongs in a sibling leaf module, not here.
+ */
 /** Normalizes unknown throwables into an Error instance. */
 export declare function toError(error: unknown): Error;
+/**
+ * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
+ * unknown throwable, or `undefined` when the value carries no string `code`.
+ *
+ * The check is deliberately structural rather than `error instanceof Error`:
+ * a plain object carrying `.code` — exactly the shape {@link toError} exists
+ * to normalise — reaches errno consumers through rejected promises and
+ * cross-realm throws. Nine hand-rolled copies of this predicate existed
+ * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
+ * and so misclassified that shape as "no code".
+ */
+export declare function getNodeErrorCode(error: unknown): string | undefined;
+/**
+ * Checks whether a process with the given PID is still running, using
+ * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ *
+ * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * process exists but is owned by another uid, which happens routinely with
+ * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
+ * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
+ * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
+ * build's tree clone and a live furnace lock were removed out from under
+ * their owner. Any other errno is treated as "unknown, assume alive", which
+ * is the safe direction for every caller: it refuses rather than destroys.
+ */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/src/utils/errors.js

@@ -1,4 +1,17 @@
 // SPDX-License-Identifier: EUPL-1.2
+/**
+ * Throwable normalisation primitives.
+ *
+ * **This module must import nothing.** It sits at the very bottom of the
+ * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it — so it is the one place a shared helper can live and be
+ * provably cycle-immune. Adding an import here makes that whole subtree
+ * reachable from every util, and any future `src/errors/*` module wanting a
+ * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
+ * that would like `getNodeErrorCode`) then closes the loop and fails the
+ * `dpdm --exit-code circular:1` release gate. A helper that needs an import
+ * belongs in a sibling leaf module, not here.
+ */
 /** Normalizes unknown throwables into an Error instance. */
 export function toError(error) {
     if (error instanceof Error) {
@@ -12,3 +25,45 @@ export function toError(error) {
     }
     return new Error(typeof error === 'string' ? error : String(error), { cause: error });
 }
+/**
+ * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
+ * unknown throwable, or `undefined` when the value carries no string `code`.
+ *
+ * The check is deliberately structural rather than `error instanceof Error`:
+ * a plain object carrying `.code` — exactly the shape {@link toError} exists
+ * to normalise — reaches errno consumers through rejected promises and
+ * cross-realm throws. Nine hand-rolled copies of this predicate existed
+ * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
+ * and so misclassified that shape as "no code".
+ */
+export function getNodeErrorCode(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+}
+/**
+ * Checks whether a process with the given PID is still running, using
+ * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ *
+ * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * process exists but is owned by another uid, which happens routinely with
+ * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
+ * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
+ * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
+ * build's tree clone and a live furnace lock were removed out from under
+ * their owner. Any other errno is treated as "unknown, assume alive", which
+ * is the safe direction for every caller: it refuses rather than destroys.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return getNodeErrorCode(error) !== 'ESRCH';
+    }
+}

package/dist/src/utils/fs.js

@@ -2,6 +2,7 @@
 import { randomUUID } from 'node:crypto';
 import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
+import { getNodeErrorCode } from './errors.js';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
 const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
 function sleep(ms) {
@@ -33,9 +34,7 @@ export async function pathExistsStrict(path) {
         return true;
     }
     catch (error) {
-        const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-            ? error.code
-            : undefined;
+        const code = getNodeErrorCode(error);
         if (code === 'ENOENT') {
             return false;
         }
@@ -68,9 +67,7 @@ export async function removeDir(path) {
             return;
         }
         catch (error) {
-            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-                ? error.code
-                : undefined;
+            const code = getNodeErrorCode(error);
             if (!code || !RETRIABLE_REMOVE_ERRORS.has(code) || attempt === 4) {
                 throw error;
             }
@@ -177,9 +174,7 @@ export async function writeFileAtomic(path, content) {
         existingMode = (await stat(path)).mode;
     }
     catch (error) {
-        const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-            ? error.code
-            : undefined;
+        const code = getNodeErrorCode(error);
         if (code !== 'ENOENT') {
             throw error;
         }
@@ -223,9 +218,7 @@ async function renameWithRetries(from, to) {
             return;
         }
         catch (error) {
-            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-                ? error.code
-                : undefined;
+            const code = getNodeErrorCode(error);
             if (!code || !RETRIABLE_RENAME_ERRORS.has(code) || attempt === 4) {
                 throw error;
             }