@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/utils/fs.js

@@ -202,9 +202,9 @@ export async function writeFileAtomic(path, content) {
 /**
  * Renames the temp file over its destination, retrying transient sharing
  * violations. On Windows, a rename onto a target that another writer is
- * concurrently replacing — or that an antivirus/indexer briefly holds open —
+ * concurrently replacing (or that an antivirus/indexer briefly holds open)
  * fails with EPERM/EACCES/EBUSY even though the same rename succeeds a moment
- * later; POSIX renames never hit this. Non-retriable codes and exhausted
+ * later. POSIX renames never hit this. Non-retriable codes and exhausted
  * budgets rethrow, so a genuine permission problem still surfaces.
  */
 async function renameWithRetries(from, to) {
@@ -237,7 +237,7 @@ async function syncParentDir(path) {
             await directoryHandle?.close();
         }
         catch {
-            // Nothing left to do — the handle is being discarded either way.
+            // Nothing left to do. The handle is being discarded either way.
         }
     }
 }
@@ -272,7 +272,7 @@ export async function copyDir(src, dest) {
  * artefacts out of their listings without racing the rename.
  *
  * Intentionally anchored so a legitimately-named backup file like
- * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is not treated
  * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
  */
 export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9a-f-]{36}$/i;
@@ -281,8 +281,8 @@ export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9
  *
  * Each invocation gets its own path via PID + UUID, so concurrent writers
  * targeting the same destination never interfere with each other. Cleanup of
- * the temp file is the caller's responsibility on error; we intentionally do
- * NOT glob-delete peer temp files here to avoid racing with other writers.
+ * the temp file is the caller's responsibility on error. We intentionally do
+ * not glob-delete peer temp files here to avoid racing with other writers.
  */
 function createAtomicTempPath(path) {
     const directory = dirname(path);
@@ -306,7 +306,7 @@ function createAtomicTempPath(path) {
 export async function checkDiskSpace(path, minBytes, onLowSpace) {
     try {
         const stats = await statfs(path);
-        // bavail = blocks available to UNPRIVILEGED users; bfree includes the
+        // bavail = blocks available to UNPRIVILEGED users. bfree includes the
         // root-reserved blocks (typically 5% on ext4), so it over-reported free
         // space and silently suppressed the low-space warning exactly when it
         // mattered.
@@ -321,7 +321,7 @@ export async function checkDiskSpace(path, minBytes, onLowSpace) {
     }
     catch {
         // statfs may not be available on all platforms or the path may
-        // not exist yet — silently degrade rather than blocking the operation.
+        // not exist yet, so silently degrade rather than blocking the operation.
         return undefined;
     }
 }

package/dist/src/utils/line-dispatch.d.ts

@@ -1,15 +1,15 @@
 /**
  * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
- * a sibling so the exec module stays within its size budget; the contract
+ * a sibling so the exec module stays within its size budget. The contract
  * (terminators, partial-line cap) is documented on the function.
  */
 /**
  * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
+ * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
  * matters for progress-bar style output (mach, cargo) that repaints a line
  * with carriage returns and never sends a newline, which otherwise
  * accumulates indefinitely. A single trailing `\r` is held back since it may
  * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line — callers keep accumulating into it.
+ * remaining partial line. Callers keep accumulating into it.
  */
 export declare function dispatchCompleteLines(buffer: string, cb: ((line: string) => void) | undefined): string;

package/dist/src/utils/line-dispatch.js

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
- * a sibling so the exec module stays within its size budget; the contract
+ * a sibling so the exec module stays within its size budget. The contract
  * (terminators, partial-line cap) is documented on the function.
  */
 /**
  * Cap on the partial-line tail kept between chunks. A child emitting one
  * enormous line with no terminator (minified JS dumped to stderr, a raw
- * binary blob) would otherwise grow the buffer without bound — the 50 MB cap
+ * binary blob) would otherwise grow the buffer without bound: the 50 MB cap
  * guards the collector, not these line buffers. When the tail exceeds the
  * cap it is dispatched as a synthetic (oversized) line so the matchers still
  * see its content, then the buffer resets.
@@ -15,12 +15,12 @@
 const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
 /**
  * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
+ * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
  * matters for progress-bar style output (mach, cargo) that repaints a line
  * with carriage returns and never sends a newline, which otherwise
  * accumulates indefinitely. A single trailing `\r` is held back since it may
  * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line — callers keep accumulating into it.
+ * remaining partial line. Callers keep accumulating into it.
  */
 export function dispatchCompleteLines(buffer, cb) {
     let searchFrom = 0;
@@ -31,7 +31,7 @@ export function dispatchCompleteLines(buffer, cb) {
         if (idx === -1)
             break;
         if (buffer[idx] === '\r' && idx === buffer.length - 1) {
-            // Possible first half of a chunk-split \r\n — wait for the next chunk.
+            // Possible first half of a chunk-split \r\n, so wait for the next chunk.
             break;
         }
         const line = buffer.slice(0, idx);

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

@@ -64,9 +64,9 @@ export declare function warn(message: string): void;
 export declare const NOTICE_PREFIX = "[FireForge] NOTICE:";
 /**
  * Logs one of FireForge's own "why this is happening / why this is slow"
- * explanations at WARNING severity.
+ * explanations at warning severity.
  *
- * These lines are not warnings about the operator's code — they explain a
+ * These lines are not warnings about the operator's code. They explain a
  * decision FireForge just made (escalating an incremental build to a full
  * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
@@ -98,10 +98,10 @@ export declare function cancel(message: string): void;
 /**
  * Checks whether a prompt result represents a user cancellation.
  *
- * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * Narrows to `symbol`: clack returns its cancel sentinel as a symbol and
  * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
  * that narrowing and forces `as string` / `as PatchCategory` casts across
- * the command modules on the *non*-cancelled branch, where the value is
+ * the command modules on the non-cancelled branch, where the value is
  * already known not to be the sentinel. Keep the predicate form.
  */
 export declare function isCancel(value: unknown): value is symbol;

package/dist/src/utils/logger.js

@@ -6,11 +6,11 @@ let verboseMode = false;
 /**
  * Whether machine-output mode is active (`--json` / `--raw`).
  *
- * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
+ * In machine mode, stdout belongs exclusively to the machine-readable
  * payload: all human-facing diagnostics (intro/outro banners, info, warn,
  * error, steps, notes) are routed to stderr as plain unstyled lines.
- * Otherwise clack's log helpers write styled warnings to stdout *before* the
- * JSON body — a truncated-directory warning during `status --json` breaks
+ * Otherwise clack's log helpers write styled warnings to stdout before the
+ * JSON body, and a truncated-directory warning during `status --json` breaks
  * every `JSON.parse(stdout)` consumer.
  */
 let machineOutputMode = false;
@@ -35,11 +35,11 @@ export function isMachineOutputMode() {
 /**
  * Whether stdout is sealed behind a machine-readable final line.
  *
- * The `FIREFORGE-VERDICT:` contract promises that line as the run's LAST
- * stdout write — but emit-then-throw failure paths rethrow into
+ * The `FIREFORGE-VERDICT:` contract promises that line as the run's last
+ * stdout write, but emit-then-throw failure paths rethrow into
  * `withErrorHandling`, whose clack error/cancel rendering lands on stdout
  * in non-machine mode, displacing the verdict from the final line. The
- * verdict sink seals stdout the moment it writes; every later logger call
+ * verdict sink seals stdout the moment it writes. Every later logger call
  * routes to stderr through the same diagnostic channel machine mode uses.
  * `withErrorHandling`'s finally clears the seal (alongside machine mode).
  */
@@ -138,9 +138,9 @@ export function warn(message) {
 export const NOTICE_PREFIX = '[FireForge] NOTICE:';
 /**
  * Logs one of FireForge's own "why this is happening / why this is slow"
- * explanations at WARNING severity.
+ * explanations at warning severity.
  *
- * These lines are not warnings about the operator's code — they explain a
+ * These lines are not warnings about the operator's code. They explain a
  * decision FireForge just made (escalating an incremental build to a full
  * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
@@ -196,7 +196,7 @@ export function formatErrorText(message) {
  */
 export function spinner(initialMessage) {
     if (routeToStderr()) {
-        // Spinner progress is diagnostics; keep stdout clean for the payload.
+        // Spinner progress is diagnostics. Keep stdout clean for the payload.
         return {
             message: (msg) => {
                 writeDiagnostic('', msg);
@@ -251,10 +251,10 @@ export function cancel(message) {
 /**
  * Checks whether a prompt result represents a user cancellation.
  *
- * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * Narrows to `symbol`: clack returns its cancel sentinel as a symbol and
  * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
  * that narrowing and forces `as string` / `as PatchCategory` casts across
- * the command modules on the *non*-cancelled branch, where the value is
+ * the command modules on the non-cancelled branch, where the value is
  * already known not to be the sentinel. Keep the predicate form.
  */
 export function isCancel(value) {

package/dist/src/utils/machine-output.js

@@ -11,8 +11,8 @@
  *   1. Success writes exactly one JSON document to stdout.
  *   2. Failure writes exactly one `{ schemaVersion, error, code }` document
  *      to stdout, then exits non-zero.
- *   3. Machine mode is engaged BEFORE any output, so every diagnostic —
- *      including one rendered later by `withErrorHandling` — routes to
+ *   3. Machine mode is engaged before any output, so every diagnostic,
+ *      including one rendered later by `withErrorHandling`, routes to
  *      stderr and cannot corrupt the payload.
  */
 import { CommandError } from '../errors/base.js';

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

@@ -1,14 +1,14 @@
 import type { Command } from 'commander';
 /**
  * Filters an object to only include keys whose values are not undefined.
- * Designed for use with exactOptionalPropertyTypes — the result can be
+ * Designed for use with exactOptionalPropertyTypes: the result can be
  * spread into typed option objects without assigning undefined to optional
  * properties.
  *
  * Constrained to `object`, not `Record<string, unknown>`: a named interface
  * has no index signature, so the narrower constraint rejects exactly the
  * annotations this helper is most useful with. Nothing in the body needs the
- * index signature — the key walk goes through `Object.keys`.
+ * index signature, since the key walk goes through `Object.keys`.
  *
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
@@ -21,7 +21,7 @@ export declare function pickDefined<T extends object>(obj: T): {
  * commander's own invalid-argument channel.
  *
  * Commander only treats errors whose `code` is `'commander.invalidArgument'`
- * as argument-validation failures; anything else re-throws out of
+ * as argument-validation failures. Anything else re-throws out of
  * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
  * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
  * That covers a plain Error, a `GeneralError`, and even a FireForge
@@ -62,25 +62,25 @@ export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
  * invalid-argument channel). In that role the value is never `undefined`, so
- * the environment fallback cannot leak into flag PARSING — only into flag
- * ABSENCE, which is where it belongs.
+ * the environment fallback cannot leak into flag parsing, only into flag
+ * absence, which is where it belongs.
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
 /**
- * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * The session-wide wait budget in milliseconds, or undefined when none is
  * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
  *
- * Exists for the SECONDARY locks a command takes after the one its
+ * Exists for the secondary locks a command takes after the one its
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
- * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
  * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it — this reaches
+ * flag reaches the three furnace commands that declare it. This reaches
  * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
  * `override`, `chrome-doc`, …), which have no flag to thread but are just
  * as contended.
  *
- * Deliberately env-only: a flag belongs to one invocation and is passed
+ * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
  * session-wide default is expressed. An explicit budget at a call site
  * always wins over this.
@@ -98,12 +98,12 @@ export declare function ensureWaitLockOptionEverywhere(command: Command): void;
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch
  * directory lock for queue-mutating ones). The parsed option value is `true`
- * for the bare flag or a validated integer; feed it through
+ * for the bare flag or a validated integer. Feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  *
- * A command can take MORE than one lock — a furnace mutation takes the
- * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * A command can take more than one lock (a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock`) and the budget
  * has to reach all of them or the flag is a half-truth. The secondary locks
  * read the session budget through {@link sessionWaitLockMs} rather than
  * having it threaded to every call site.

package/dist/src/utils/options.js

@@ -3,14 +3,14 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from './errors.js';
 /**
  * Filters an object to only include keys whose values are not undefined.
- * Designed for use with exactOptionalPropertyTypes — the result can be
+ * Designed for use with exactOptionalPropertyTypes: the result can be
  * spread into typed option objects without assigning undefined to optional
  * properties.
  *
  * Constrained to `object`, not `Record<string, unknown>`: a named interface
  * has no index signature, so the narrower constraint rejects exactly the
  * annotations this helper is most useful with. Nothing in the body needs the
- * index signature — the key walk goes through `Object.keys`.
+ * index signature, since the key walk goes through `Object.keys`.
  *
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
@@ -29,7 +29,7 @@ export function pickDefined(obj) {
  * commander's own invalid-argument channel.
  *
  * Commander only treats errors whose `code` is `'commander.invalidArgument'`
- * as argument-validation failures; anything else re-throws out of
+ * as argument-validation failures. Anything else re-throws out of
  * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
  * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
  * That covers a plain Error, a `GeneralError`, and even a FireForge
@@ -87,12 +87,12 @@ function parseWaitLockSeconds(raw) {
  * The standing wait budget from {@link WAIT_LOCK_ENV_VAR}, or undefined when
  * it is unset or empty.
  *
- * Exists because a wait budget is a property of the SESSION, not of the
+ * Exists because a wait budget is a property of the session, not of the
  * invocation: a checkout worked by several concurrent agent sessions has a
  * held lock as its normal state, and an unattended loop would otherwise have
- * to thread `--wait-lock` through every command it issues — the one place
- * it is easiest to forget, and the failure only shows up once the loop has
- * already produced a tail of refusals.
+ * to thread `--wait-lock` through every command it issues. That is the one
+ * place it is easiest to forget, and the failure only shows up once the loop
+ * has already produced a tail of refusals.
  *
  * An unusable value is a usage error rather than a silent fall-back to
  * fail-fast: the operator set it precisely because they did not want to
@@ -124,8 +124,8 @@ function waitLockSecondsFromEnv() {
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
  * invalid-argument channel). In that role the value is never `undefined`, so
- * the environment fallback cannot leak into flag PARSING — only into flag
- * ABSENCE, which is where it belongs.
+ * the environment fallback cannot leak into flag parsing, only into flag
+ * absence, which is where it belongs.
  */
 export function resolveWaitLockSeconds(value) {
     if (value === undefined || value === false) {
@@ -144,20 +144,20 @@ export function resolveWaitLockSeconds(value) {
     return parsed;
 }
 /**
- * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * The session-wide wait budget in milliseconds, or undefined when none is
  * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
  *
- * Exists for the SECONDARY locks a command takes after the one its
+ * Exists for the secondary locks a command takes after the one its
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
- * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
  * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it — this reaches
+ * flag reaches the three furnace commands that declare it. This reaches
  * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
  * `override`, `chrome-doc`, …), which have no flag to thread but are just
  * as contended.
  *
- * Deliberately env-only: a flag belongs to one invocation and is passed
+ * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
  * session-wide default is expressed. An explicit budget at a call site
  * always wins over this.
@@ -169,12 +169,12 @@ export function sessionWaitLockMs() {
     return seconds === undefined ? undefined : seconds * 1000;
 }
 /**
- * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
+ * Registers `--wait-lock [seconds]` on a command that takes no lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
- * error — a command that rejects it with "unknown option" kills the whole
+ * error. A command that rejects it with "unknown option" kills the whole
  * sequence with a usage error instead of a lock message.
  *
- * The flag is accepted and ignored here — never silently repurposed — and
+ * The flag is accepted and ignored here, never silently repurposed, and
  * the help text says so, so nobody reads its presence as evidence that this
  * command waits for anything.
  *
@@ -209,12 +209,12 @@ export function ensureWaitLockOptionEverywhere(command) {
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch
  * directory lock for queue-mutating ones). The parsed option value is `true`
- * for the bare flag or a validated integer; feed it through
+ * for the bare flag or a validated integer. Feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  *
- * A command can take MORE than one lock — a furnace mutation takes the
- * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * A command can take more than one lock (a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock`) and the budget
  * has to reach all of them or the flag is a half-truth. The secondary locks
  * read the session budget through {@link sessionWaitLockMs} rather than
  * having it threaded to every call site.

package/dist/src/utils/package-root.js

@@ -36,8 +36,8 @@ export function getPackageRoot() {
             }
         }
         catch (error) {
-            // Absent package.json: keep walking. A package.json that EXISTS but
-            // fails to parse is a different animal — walking past it could bind
+            // Absent package.json: keep walking. A package.json that exists but
+            // fails to parse is a different case: walking past it could bind
             // to a wrong ancestor package (any parent exposing bin.fireforge) or
             // end in the unhelpful generic "could not locate" error, hiding the
             // actual syntax problem.

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

@@ -7,13 +7,13 @@ export declare function normalizePathSlashes(path: string): string;
  * (`browser/base/content/foo.js`).
  *
  * The match is case-insensitive because default macOS and Windows
- * filesystems treat `Engine/` and `engine/` as the same directory; a literal
- * lowercase-only check leaves `mach` and the manifest writers resolving
- * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * filesystems treat `Engine/` and `engine/` as the same directory. A
+ * literal lowercase-only check leaves `mach` and the manifest writers
+ * resolving against a wrongly-cased prefix. Leading whitespace is ignored so
  * tab-completed inputs do not slip past the strip.
  *
  * The return value is trimmed of that leading whitespace when the prefix
- * matched, and otherwise passed through verbatim — callers that care about
+ * matched, and otherwise passed through verbatim. Callers that care about
  * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user

package/dist/src/utils/paths.js

@@ -21,13 +21,13 @@ export function normalizePathSlashes(path) {
  * (`browser/base/content/foo.js`).
  *
  * The match is case-insensitive because default macOS and Windows
- * filesystems treat `Engine/` and `engine/` as the same directory; a literal
- * lowercase-only check leaves `mach` and the manifest writers resolving
- * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * filesystems treat `Engine/` and `engine/` as the same directory. A
+ * literal lowercase-only check leaves `mach` and the manifest writers
+ * resolving against a wrongly-cased prefix. Leading whitespace is ignored so
  * tab-completed inputs do not slip past the strip.
  *
  * The return value is trimmed of that leading whitespace when the prefix
- * matched, and otherwise passed through verbatim — callers that care about
+ * matched, and otherwise passed through verbatim. Callers that care about
  * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user

package/dist/src/utils/process-group.d.ts

@@ -1,15 +1,15 @@
 /**
  * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget;
- * deliberately spawn-based (not `exec`-based) so the two modules do not
- * import each other cyclically.
+ * out of `process.ts` to keep that file within the per-file line budget.
+ * Spawn-based rather than `exec`-based so the two modules do not import
+ * each other cyclically.
  */
 import { type ChildProcess } from 'node:child_process';
 /**
- * Sends `signal` to the child's whole tree: the process GROUP on POSIX
- * (negative-PID kill — reaches mach → python → firefox → content-process
- * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
- * fallback on Windows. No-ops once the direct child has exited (group
+ * Sends `signal` to the child's whole tree: the process group on POSIX
+ * (negative-PID kill, which reaches mach → python → firefox →
+ * content-process chains), or a `taskkill /T /F` tree kill plus a direct
+ * `child.kill` fallback on Windows. No-ops once the direct child has exited (group
  * survivors after exit are the post-run sweep's job, not this function's).
  *
  * A failed group kill falls through to a direct `child.kill` on POSIX too:
@@ -30,7 +30,7 @@ interface ProcessGroupSurvivor {
  * the PID of a child started with `detached: true`): lists survivors,
  * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
  * about anything that still refuses to die. POSIX only (no-op on win32).
- * The only kill target is `-pgid` — never anything outside the group.
+ * The only kill target is `-pgid`, never anything outside the group.
  * A healthy run costs exactly one `pgrep`.
  */
 export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{

package/dist/src/utils/process-group.js

@@ -1,19 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Process-group kill and post-run sweep helpers for the exec layer. Split
- * out of `process.ts` to keep that file within the per-file line budget;
- * deliberately spawn-based (not `exec`-based) so the two modules do not
- * import each other cyclically.
+ * out of `process.ts` to keep that file within the per-file line budget.
+ * Spawn-based rather than `exec`-based so the two modules do not import
+ * each other cyclically.
  */
 import { spawn } from 'node:child_process';
 import { getNodeErrorCode } from './errors.js';
 import { verbose, warn } from './logger.js';
 import { sleep } from './sleep.js';
 /**
- * Sends `signal` to the child's whole tree: the process GROUP on POSIX
- * (negative-PID kill — reaches mach → python → firefox → content-process
- * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
- * fallback on Windows. No-ops once the direct child has exited (group
+ * Sends `signal` to the child's whole tree: the process group on POSIX
+ * (negative-PID kill, which reaches mach → python → firefox →
+ * content-process chains), or a `taskkill /T /F` tree kill plus a direct
+ * `child.kill` fallback on Windows. No-ops once the direct child has exited (group
  * survivors after exit are the post-run sweep's job, not this function's).
  *
  * A failed group kill falls through to a direct `child.kill` on POSIX too:
@@ -38,19 +38,19 @@ export function killProcessTree(child, signal, usesProcessGroup) {
             catch {
                 // ESRCH/EPERM: the group is gone, or was never created because the
                 // platform ignored `detached`. Signal the direct child rather than
-                // doing nothing — it may well still be alive. Without this
+                // doing nothing, since it may well still be alive. Without this
                 // fall-through a failed group kill left the child running.
                 child.kill(signal);
             }
         }
         else {
-            // No process group on Windows — taskkill /T walks the descendant
+            // No process group on Windows, so taskkill /T walks the descendant
             // tree instead. Always forced (/F): there is no SIGTERM analogue,
             // so the grace window only exists on POSIX.
             spawn('taskkill', ['/pid', String(targetPid), '/T', '/F'], {
                 stdio: 'ignore',
             }).on('error', () => {
-                // taskkill unavailable — nothing more we can do beyond the
+                // taskkill unavailable, so nothing more we can do beyond the
                 // direct-child kill below.
             });
             child.kill(signal);
@@ -104,10 +104,10 @@ async function listGroupSurvivors(pgid) {
         return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
     }
     catch (error) {
-        // Same errno semantics as `isProcessAlive` (which cannot be called here —
-        // it probes a single positive pid): only ESRCH proves the group is gone.
-        // EPERM means it exists under another uid, and an unrecognized failure is
-        // not evidence of absence — report survivors in both cases.
+        // Same errno semantics as `isProcessAlive` (which cannot be called here,
+        // since it probes a single positive pid): only ESRCH proves the group is
+        // gone. EPERM means it exists under another uid, and an unrecognized
+        // failure is not evidence of absence, so report survivors in both cases.
         if (getNodeErrorCode(error) === 'ESRCH')
             return [];
         return [{ pid: -1, command: 'unknown (pgrep unavailable; group liveness probe denied)' }];
@@ -128,7 +128,7 @@ function describeSurvivors(list) {
  * the PID of a child started with `detached: true`): lists survivors,
  * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
  * about anything that still refuses to die. POSIX only (no-op on win32).
- * The only kill target is `-pgid` — never anything outside the group.
+ * The only kill target is `-pgid`, never anything outside the group.
  * A healthy run costs exactly one `pgrep`.
  */
 export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
@@ -143,11 +143,11 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
         process.kill(-pgid, 'SIGTERM');
     }
     catch {
-        // The group vanished between the listing and the signal — nothing left to
-        // escalate against, so report the survivors collected so far.
+        // The group vanished between the listing and the signal, so there is
+        // nothing left to escalate against. Report the survivors collected so far.
         return { survivors };
     }
-    // Deliberately ref'd (sleep's default): this wait sits between the group
+    // Ref'd (sleep's default): this wait sits between the group
     // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
     // child 'close' handler after the signal forwarder is disposed. With an
     // unref'd timer nothing keeps the event loop alive, so Node could exit
@@ -164,7 +164,7 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
             // nothing to signal.
             return { survivors };
         }
-        // Deliberately ref'd (sleep's default): this wait sits between the group
+        // Ref'd (sleep's default): this wait sits between the group
         // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
         // child 'close' handler after the signal forwarder is disposed. With an
         // unref'd timer nothing keeps the event loop alive, so Node could exit