prismcast 1.10.2 → 1.11.0

package/dist/utils/processInspector.js

@@ -0,0 +1,127 @@
+import { createDefaultProcessInspectorContext } from "./processInspector.context.js";
+/**
+ * Returns a snapshot of every visible process. Callers filter the result for the processes they care about.
+ * @param ctx - The process inspector context. Defaults to real I/O wiring.
+ * @returns The current process table.
+ */
+export function listProcesses(ctx = createDefaultProcessInspectorContext()) {
+    return ctx.enumerate();
+}
+/**
+ * Parses a single /proc/<pid>/cmdline payload. The on-disk format separates argv entries with NUL bytes and may or may not include a trailing NUL. Empty
+ * payloads (kernel threads, zombie processes) yield an empty command line - callers decide whether to drop those entries.
+ * @param raw - The /proc/<pid>/cmdline payload.
+ * @returns The decoded command line.
+ */
+export function parseLinuxProcCmdline(raw) {
+    // Drop a trailing NUL if present so the join does not produce a phantom blank arg.
+    const trimmed = raw.endsWith("\0") ? raw.slice(0, -1) : raw;
+    return trimmed.split("\0").join(" ");
+}
+/**
+ * Parses the ppid (field 4) from a /proc/<pid>/stat payload. The format embeds the executable name in parentheses at field 2; that name can contain
+ * whitespace and parentheses itself, so we anchor on the last closing paren before splitting. After the closing paren, the first field is field 3 (state) and
+ * the second is field 4 (ppid).
+ * @param raw - The /proc/<pid>/stat payload.
+ * @returns The parent process ID, or null when the payload is malformed.
+ */
+export function parseLinuxProcStat(raw) {
+    const rparen = raw.lastIndexOf(")");
+    if (rparen === -1) {
+        return null;
+    }
+    const fields = raw.slice(rparen + 1).trim().split(/\s+/);
+    // We want field 4 (ppid), which lands at index 1 in the post-paren split: index 0 is state (field 3), index 1 is ppid (field 4).
+    if (fields.length < 2) {
+        return null;
+    }
+    const ppid = parseInt(fields[1] ?? "", 10);
+    return Number.isNaN(ppid) ? null : ppid;
+}
+/**
+ * Parses the output of `ps -axww -o pid=,ppid=,command=` (or equivalent shape). Each non-empty line begins with leading whitespace, then the PID and PPID as
+ * integers, then whitespace, then the full command. Lines that do not match this shape are silently dropped.
+ * @param raw - The raw ps output.
+ * @returns The parsed process table.
+ */
+export function parseMacOsPsOutput(raw) {
+    const results = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        // Three captures: pid, ppid, and the rest. The command line is the rest of the line verbatim (may contain spaces).
+        const match = /^(\d+)\s+(\d+)\s+(.+)$/.exec(trimmed);
+        if (match === null) {
+            continue;
+        }
+        const pid = parseInt(match[1] ?? "", 10);
+        const ppid = parseInt(match[2] ?? "", 10);
+        const commandLine = match[3] ?? "";
+        if (Number.isNaN(pid) || Number.isNaN(ppid)) {
+            continue;
+        }
+        results.push({ commandLine, pid, ppid });
+    }
+    return results;
+}
+/**
+ * Parses the output of PowerShell's `Get-CimInstance Win32_Process | Format-List ProcessId,ParentProcessId,CommandLine` (or equivalent shape). The format
+ * places each property on its own line as "Name : Value", with blank lines separating records. CommandLine may be blank (system processes) or contain
+ * embedded colons - we split on the first " : " separator only.
+ * @param raw - The raw Format-List output.
+ * @returns The parsed process table.
+ */
+export function parseWindowsFormatListOutput(raw) {
+    const results = [];
+    let currentPid = null;
+    let currentPpid = null;
+    let currentCommandLine = null;
+    // A record is only committed once both pid and ppid have been seen, since ownership decisions depend on both being present and trustworthy. A missing
+    // command line is tolerated and recorded as an empty string.
+    const flush = () => {
+        if ((currentPid !== null) && (currentPpid !== null)) {
+            results.push({ commandLine: currentCommandLine ?? "", pid: currentPid, ppid: currentPpid });
+        }
+        currentPid = null;
+        currentPpid = null;
+        currentCommandLine = null;
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === "") {
+            flush();
+            continue;
+        }
+        // Format-List output is "Name : Value" with the colon surrounded by spaces. We split on the first " : " so values containing colons survive intact.
+        const sep = line.indexOf(" : ");
+        if (sep === -1) {
+            continue;
+        }
+        const key = line.slice(0, sep).trim();
+        const value = line.slice(sep + 3);
+        switch (key) {
+            case "ProcessId": {
+                const parsed = parseInt(value.trim(), 10);
+                currentPid = Number.isNaN(parsed) ? null : parsed;
+                break;
+            }
+            case "ParentProcessId": {
+                const parsed = parseInt(value.trim(), 10);
+                currentPpid = Number.isNaN(parsed) ? null : parsed;
+                break;
+            }
+            case "CommandLine": {
+                currentCommandLine = value;
+                break;
+            }
+            default: {
+                // Other Format-List keys (Name, Path, ...) are ignored. Tolerating extra fields keeps the parser robust to upstream additions.
+            }
+        }
+    }
+    // Flush the trailing record if the output did not end with a blank line.
+    flush();
+    return results;
+}
+//# sourceMappingURL=processInspector.js.map

package/dist/utils/processInspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processInspector.js","sourceRoot":"","sources":["../../src/utils/processInspector.ts"],"names":[],"mappings":"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"}

package/dist/utils/retry.d.ts

@@ -1,4 +1,4 @@
-import { type Clock } from "./clock.ts";
+import type { Clock } from "./clock.ts";
 /**
  * Options for retryOperation. Groups all parameters into a single object to avoid positional parameter sprawl and make the function extensible.
  */
@@ -17,7 +17,30 @@ export interface RetryOptions<T> {
  * Implements a generic retry mechanism with exponential backoff and jitter. This function attempts an operation multiple times, waiting progressively longer between
  * attempts to avoid overwhelming failing services. The exponential backoff with jitter prevents thundering herd problems where many clients retry simultaneously.
  * @param options - Retry configuration including the operation, attempt limits, timeouts, and optional backoff tuning.
- * @returns The result of the operation if successful.
+ * @returns The result of the operation if successful, or undefined when earlySuccessCheck reports the operation already succeeded after a timeout-shaped error.
  * @throws The last error encountered if all attempts fail.
  */
 export declare function retryOperation<T>(options: RetryOptions<T>): Promise<T | undefined>;
+/**
+ * The timing fields maxRetryDuration reads from a retry configuration. A narrow subset of RetryOptions so the estimator depends only on what its closed form
+ * needs, never on the operation, clock, or callbacks.
+ */
+export interface RetryDurationTiming {
+    backoffJitter?: number;
+    maxAttempts: number;
+    maxBackoffDelay?: number;
+    timeoutMs: number;
+}
+/**
+ * Computes the worst-case wall-clock duration of a retryOperation run: every attempt consuming its full per-attempt timeout, plus one backoff sleep per retry
+ * after the first, each taken at its ceiling (the backoff cap plus the full jitter). The estimate reads the same default constants the loop reads, so it cannot
+ * drift from the loop's arithmetic. The loop seeds each backoff at one second and doubles, capped at maxBackoffDelay, so every gap is at or below
+ * maxBackoffDelay + backoffJitter; taking that ceiling for each gap makes the result an upper bound - a leak bound for a caller sizing a window that must outlive
+ * the retries, never an under-count. The closed form holds only for configurations whose operation carries no unbounded callback: earlySuccessCheck runs awaited
+ * on the timeout path and can add time beyond the per-attempt timeout, so a caller relying on the bound must pass a configuration without one.
+ *
+ * @param timing - The attempt count, per-attempt timeout, and optional backoff tuning.
+ * @returns The worst-case duration in milliseconds.
+ */
+export declare function maxRetryDuration(timing: RetryDurationTiming): number;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAYxC;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAG7B,aAAa,CAAC,EAAE,MAAM,CAAC;IAKvB,KAAK,CAAC,EAAE,KAAK,CAAC;IAGd,WAAW,EAAE,MAAM,CAAC;IAIpB,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAG3C,WAAW,EAAE,MAAM,CAAC;IAGpB,eAAe,CAAC,EAAE,MAAM,CAAC;IAGzB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAI5B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAG5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA0ExF;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAGlC,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,WAAW,EAAE,MAAM,CAAC;IAGpB,eAAe,CAAC,EAAE,MAAM,CAAC;IAGzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CASpE"}

package/dist/utils/retry.js

@@ -1,21 +1,27 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
  * retry.ts: Retry logic with exponential backoff for PrismCast. Time-dependent operations route through a Clock (see clock.ts) so tests can deterministically
- * control sleeps and timeout races without depending on real-time delays - the function's nested raceWithTimeout/Promise.race/finally/await delay chain is
- * exactly the shape Node's synchronous mock.timers.tick cannot drain.
+ * control sleeps and per-attempt bounds without depending on real-time delays - the function's nested waitWithTimeout/finally/await delay chain is exactly the
+ * shape Node's synchronous mock.timers.tick cannot drain.
  */
-import { realClock } from "./clock.js";
 import { formatError, isSessionClosedError } from "./errors.js";
 import { LOG } from "./logger.js";
+import { realClock } from "./clock.js";
+// Default maximum jitter added to each backoff sleep in milliseconds. Prevents synchronized retries across concurrent operations. Read by both retryOperation's
+// destructuring default and maxRetryDuration, so the worst-case estimate cannot drift from the loop that produces the sleeps.
+const DEFAULT_BACKOFF_JITTER = 1000;
+// Default cap on each backoff sleep in milliseconds. Bounds the exponential growth so a long retry chain never sleeps unboundedly. Read by both retryOperation's
+// destructuring default and maxRetryDuration, so the worst-case estimate cannot drift from the loop that produces the sleeps.
+const DEFAULT_MAX_BACKOFF_DELAY = 3000;
 /**
  * Implements a generic retry mechanism with exponential backoff and jitter. This function attempts an operation multiple times, waiting progressively longer between
  * attempts to avoid overwhelming failing services. The exponential backoff with jitter prevents thundering herd problems where many clients retry simultaneously.
  * @param options - Retry configuration including the operation, attempt limits, timeouts, and optional backoff tuning.
- * @returns The result of the operation if successful.
+ * @returns The result of the operation if successful, or undefined when earlySuccessCheck reports the operation already succeeded after a timeout-shaped error.
  * @throws The last error encountered if all attempts fail.
  */
 export async function retryOperation(options) {
-    const { backoffJitter = 1000, clock = realClock, description, earlySuccessCheck, maxAttempts, maxBackoffDelay = 3000, operation, shouldAbort, timeoutMs } = options;
+    const { backoffJitter = DEFAULT_BACKOFF_JITTER, clock = realClock, description, earlySuccessCheck, maxAttempts, maxBackoffDelay = DEFAULT_MAX_BACKOFF_DELAY, operation, shouldAbort, timeoutMs } = options;
     let lastError = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         // Check if we should abort before starting this attempt. This catches cases where the page was closed during the backoff delay between retries.
@@ -27,7 +33,7 @@ export async function retryOperation(options) {
         }
         try {
             // eslint-disable-next-line no-await-in-loop
-            return await clock.raceWithTimeout(operation(), timeoutMs);
+            return await clock.waitWithTimeout(operation(), timeoutMs);
         }
         catch (error) {
             lastError = error;
@@ -54,6 +60,7 @@ export async function retryOperation(options) {
             LOG.warn("Attempt %s failed for %s: %s.", attempt, description, formatError(error));
             // Between retry attempts, wait with exponential backoff plus random jitter.
             if (attempt < maxAttempts) {
+                // The progression seeds at one second (1000ms) and doubles each attempt - 1s, 2s, 4s, ... - capped at maxBackoffDelay so growth never exceeds the ceiling.
                 const baseDelay = Math.min(1000 * (2 ** (attempt - 1)), maxBackoffDelay);
                 const jitter = Math.random() * backoffJitter;
                 // eslint-disable-next-line no-await-in-loop
@@ -61,6 +68,26 @@ export async function retryOperation(options) {
             }
         }
     }
+    // When maxAttempts < 1 the loop body never runs and lastError is still its initial null; throwing it here is the intentional, predictable failure mode for an
+    // out-of-contract maxAttempts.
     throw lastError;
 }
+/**
+ * Computes the worst-case wall-clock duration of a retryOperation run: every attempt consuming its full per-attempt timeout, plus one backoff sleep per retry
+ * after the first, each taken at its ceiling (the backoff cap plus the full jitter). The estimate reads the same default constants the loop reads, so it cannot
+ * drift from the loop's arithmetic. The loop seeds each backoff at one second and doubles, capped at maxBackoffDelay, so every gap is at or below
+ * maxBackoffDelay + backoffJitter; taking that ceiling for each gap makes the result an upper bound - a leak bound for a caller sizing a window that must outlive
+ * the retries, never an under-count. The closed form holds only for configurations whose operation carries no unbounded callback: earlySuccessCheck runs awaited
+ * on the timeout path and can add time beyond the per-attempt timeout, so a caller relying on the bound must pass a configuration without one.
+ *
+ * @param timing - The attempt count, per-attempt timeout, and optional backoff tuning.
+ * @returns The worst-case duration in milliseconds.
+ */
+export function maxRetryDuration(timing) {
+    const { backoffJitter = DEFAULT_BACKOFF_JITTER, maxAttempts, maxBackoffDelay = DEFAULT_MAX_BACKOFF_DELAY, timeoutMs } = timing;
+    // One backoff sleep sits between consecutive attempts, so a run of N attempts has N-1 gaps. Clamped at zero so an out-of-contract attempt count below one never
+    // produces a negative gap count.
+    const gaps = Math.max(0, maxAttempts - 1);
+    return (maxAttempts * timeoutMs) + (gaps * (maxBackoffDelay + backoffJitter));
+}
 //# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAc,SAAS,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AA4ClC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAAwB;IAE9D,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,KAAK,GAAG,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEpK,IAAI,SAAS,GAAY,IAAI,CAAC;IAE9B,KAAI,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAEvD,gJAAgJ;QAChJ,IAAG,WAAW,EAAE,EAAE,EAAE,CAAC;YAEnB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAG,OAAO,GAAG,CAAC,EAAE,CAAC;YAEf,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,iCAAiC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC;YAEH,4CAA4C;YAC5C,OAAO,MAAM,KAAK,CAAC,eAAe,CAAC,SAAS,EAAE,EAAE,SAAS,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,SAAS,GAAG,KAAK,CAAC;YAElB,8HAA8H;YAC9H,IAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAE/B,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,2CAA2C,EAAE,WAAW,CAAC,CAAC;gBAE7E,MAAM,KAAK,CAAC;YACd,CAAC;YAED,6JAA6J;YAC7J,gKAAgK;YAChK,IAAG,iBAAiB,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAEjE,IAAI,CAAC;oBAEH,4CAA4C;oBAC5C,MAAM,aAAa,GAAG,MAAM,iBAAiB,EAAE,CAAC;oBAEhD,IAAG,aAAa,EAAE,CAAC;wBAEjB,OAAO;oBACT,CAAC;gBACH,CAAC;gBAAC,OAAM,WAAW,EAAE,CAAC;oBAEpB,yDAAyD;gBAC3D,CAAC;YACH,CAAC;YAED,oIAAoI;YACpI,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;YAEpF,4EAA4E;YAC5E,IAAG,OAAO,GAAG,WAAW,EAAE,CAAC;gBAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;gBACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC;gBAE7C,4CAA4C;gBAC5C,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,gKAAgK;AAChK,8HAA8H;AAC9H,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,iKAAiK;AACjK,8HAA8H;AAC9H,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAuCvC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAAwB;IAE9D,MAAM,EAAE,aAAa,GAAG,sBAAsB,EAAE,KAAK,GAAG,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,GAAG,yBAAyB,EACzJ,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEhD,IAAI,SAAS,GAAY,IAAI,CAAC;IAE9B,KAAI,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAEvD,gJAAgJ;QAChJ,IAAG,WAAW,EAAE,EAAE,EAAE,CAAC;YAEnB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAG,OAAO,GAAG,CAAC,EAAE,CAAC;YAEf,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,iCAAiC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC;YAEH,4CAA4C;YAC5C,OAAO,MAAM,KAAK,CAAC,eAAe,CAAC,SAAS,EAAE,EAAE,SAAS,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,SAAS,GAAG,KAAK,CAAC;YAElB,8HAA8H;YAC9H,IAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAE/B,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,2CAA2C,EAAE,WAAW,CAAC,CAAC;gBAE7E,MAAM,KAAK,CAAC;YACd,CAAC;YAED,6JAA6J;YAC7J,gKAAgK;YAChK,IAAG,iBAAiB,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAEjE,IAAI,CAAC;oBAEH,4CAA4C;oBAC5C,MAAM,aAAa,GAAG,MAAM,iBAAiB,EAAE,CAAC;oBAEhD,IAAG,aAAa,EAAE,CAAC;wBAEjB,OAAO;oBACT,CAAC;gBACH,CAAC;gBAAC,OAAM,WAAW,EAAE,CAAC;oBAEpB,yDAAyD;gBAC3D,CAAC;YACH,CAAC;YAED,oIAAoI;YACpI,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;YAEpF,4EAA4E;YAC5E,IAAG,OAAO,GAAG,WAAW,EAAE,CAAC;gBAEzB,2JAA2J;gBAC3J,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;gBACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC;gBAE7C,4CAA4C;gBAC5C,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;IAED,8JAA8J;IAC9J,+BAA+B;IAC/B,MAAM,SAAS,CAAC;AAClB,CAAC;AAqBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA2B;IAE1D,MAAM,EAAE,aAAa,GAAG,sBAAsB,EAAE,WAAW,EAAE,eAAe,GAAG,yBAAyB,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAE/H,gKAAgK;IAChK,iCAAiC;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;IAE1C,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,eAAe,GAAG,aAAa,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/dist/utils/runtimeIdentity.context.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeIdentityContext } from "./runtimeIdentity.ts";
+/**
+ * Builds the default RuntimeIdentityContext from real runtime I/O.
+ * @returns A RuntimeIdentityContext populated from the live process.
+ */
+export declare function createDefaultRuntimeIdentityContext(): RuntimeIdentityContext;
+//# sourceMappingURL=runtimeIdentity.context.d.ts.map

package/dist/utils/runtimeIdentity.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeIdentity.context.d.ts","sourceRoot":"","sources":["../../src/utils/runtimeIdentity.context.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAWnE;;;GAGG;AACH,wBAAgB,mCAAmC,IAAI,sBAAsB,CAQ5E"}

package/dist/utils/runtimeIdentity.context.js

@@ -0,0 +1,43 @@
+import { getBootSessionId } from "./bootSession.js";
+import { isProcessRunning } from "./pid.js";
+import { listProcesses } from "./processInspector.js";
+/* The product-identity token searched for in a process's command line. This mirrors the package name / SERVICE_NAME identity; it lives as a local constant
+ * because the runtime-identity context must remain free of sideways imports into identity.ts. Matching is case-insensitive so launcher casing differences (e.g.
+ * the macOS app bundle versus the lowercase binary) do not cause a false negative.
+ */
+const PRISMCAST_COMMAND_TOKEN = "prismcast";
+/**
+ * Builds the default RuntimeIdentityContext from real runtime I/O.
+ * @returns A RuntimeIdentityContext populated from the live process.
+ */
+export function createDefaultRuntimeIdentityContext() {
+    return {
+        getBootSessionId: () => getBootSessionId(),
+        isPidOurProcess: (pid) => resolvePidIdentity(pid),
+        isProcessRunning
+    };
+}
+/**
+ * Resolves whether the live process at the given PID is genuinely a PrismCast instance by enumerating the OS process table and matching the product token in the
+ * row's command line. Returns true when the row's command line contains the token, false when it contains a non-empty command line without the token, and null
+ * when identity cannot be determined - the process table is empty (unsupported platform or enumeration failure), the PID is absent from it, or the matching
+ * row reports an empty command line (kernel threads, hidden command lines). The null cases all map upstream to the conservative held-live verdict.
+ * @param pid - The PID to identify.
+ * @returns True for a confirmed PrismCast process, false for a confirmed different process, null when identity cannot be determined.
+ */
+function resolvePidIdentity(pid) {
+    const processes = listProcesses();
+    const match = processes.find((entry) => entry.pid === pid);
+    // The PID is absent from the snapshot (it exited between the liveness check and this enumeration, or the platform returned an empty table). We cannot prove the
+    // process is unrelated, so identity is indeterminate.
+    if (match === undefined) {
+        return null;
+    }
+    const commandLine = match.commandLine.trim();
+    // An empty command line (kernel thread, process that hid its argv) gives us nothing to match against, so identity remains indeterminate.
+    if (commandLine === "") {
+        return null;
+    }
+    return commandLine.toLowerCase().includes(PRISMCAST_COMMAND_TOKEN);
+}
+//# sourceMappingURL=runtimeIdentity.context.js.map

package/dist/utils/runtimeIdentity.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeIdentity.context.js","sourceRoot":"","sources":["../../src/utils/runtimeIdentity.context.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;GAGG;AACH,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,mCAAmC;IAEjD,OAAO;QAEL,gBAAgB,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE;QAC1C,eAAe,EAAE,CAAC,GAAW,EAAqB,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC;QAC5E,gBAAgB;KACjB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAAC,GAAW;IAErC,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAE3D,gKAAgK;IAChK,sDAAsD;IACtD,IAAG,KAAK,KAAK,SAAS,EAAE,CAAC;QAEvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAE7C,yIAAyI;IACzI,IAAG,WAAW,KAAK,EAAE,EAAE,CAAC;QAEtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AACrE,CAAC"}

package/dist/utils/runtimeIdentity.d.ts

@@ -0,0 +1,98 @@
+import type { Nullable } from "../types/index.ts";
+/**
+ * The structured identity record persisted to disk.
+ */
+export interface IdentityRecord {
+    readonly bootId: string;
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly version: string;
+}
+/**
+ * Discriminated union representing the on-disk state at a given path. Every branch is exhaustive at compile time, so callers must handle each variant
+ * explicitly and the type system catches any new state added in the future.
+ */
+export type IdentityState = {
+    kind: "free";
+} | {
+    kind: "held-live";
+    record: IdentityRecord;
+} | {
+    kind: "stale-different-boot";
+    record: IdentityRecord;
+} | {
+    kind: "stale-dead-pid";
+    record: IdentityRecord;
+} | {
+    kind: "stale-malformed";
+    raw: string;
+};
+/**
+ * Outcome of a claim attempt. ok: true means we now own the slot; ok: false means another live instance holds it and we should not start.
+ */
+export type ClaimResult = {
+    ok: true;
+    record: IdentityRecord;
+} | {
+    ok: false;
+    conflict: IdentityRecord;
+};
+/**
+ * The runtime capability set inspect/claim consume. Production wires the defaults from real I/O via createDefaultRuntimeIdentityContext; tests pass a context
+ * literal to drive each state-machine branch deterministically.
+ */
+export interface RuntimeIdentityContext {
+    readonly getBootSessionId: () => string;
+    readonly isPidOurProcess: (pid: number) => Nullable<boolean>;
+    readonly isProcessRunning: (pid: number) => boolean;
+}
+/**
+ * Inspects the identity file at the given path and reports the current state. Reads the file, parses the record, and combines boot session match with PID
+ * liveness and process-identity verification to classify which branch of the state machine applies. Never mutates disk state.
+ * @param filePath - The absolute path to the identity file.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ * @returns The current state.
+ */
+export declare function inspect(filePath: string, ctx?: RuntimeIdentityContext): IdentityState;
+/**
+ * Attempts to claim the identity slot at the given path for the current process. If the slot is free or in any "stale-*" state, the record is overwritten
+ * with our identity and { ok: true } is returned. If the slot is held-live by another process, no write occurs and { ok: false } is returned with the
+ * conflicting holder's record so the caller can surface a precise diagnostic.
+ * @param filePath - The absolute path to the identity file.
+ * @param metadata - Caller-supplied metadata (the version string at minimum) that ends up in the persisted record.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ * @returns The claim result.
+ */
+export declare function claim(filePath: string, metadata: {
+    version: string;
+}, ctx?: RuntimeIdentityContext): ClaimResult;
+/**
+ * Releases the identity slot by removing the file at the given path - but only if the file's record identifies the current process. The PID-match check
+ * inside makes ownership structural: a rejected duplicate startup's exit handler sees a held-live record belonging to a different PID and leaves the file
+ * alone, while the legitimate holder sees its own PID and cleans up. Safe to call more than once: a missing file is not an error. Release is purely hygiene -
+ * a process that fails to release on death has its file recovered transparently on the next startup via the stale-different-boot or stale-dead-pid branches.
+ * @param filePath - The absolute path to the identity file.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ */
+export declare function release(filePath: string, ctx?: RuntimeIdentityContext): void;
+/**
+ * Unconditionally removes the identity file at the given path. Intended for an explicit user-invoked reset or recovery flow where the caller has deliberately
+ * asked to clear stale state without the safety check that release() provides. Prefer release() for normal lifecycle cleanup.
+ * @param filePath - The absolute path to the identity file.
+ */
+export declare function forceRelease(filePath: string): void;
+/**
+ * Serializes a record to its on-disk representation. The first line is the bare PID for backwards compatibility with shell tooling; subsequent lines are
+ * key=value pairs in deterministic order. The trailing newline keeps the file well-formed for POSIX text-file tools.
+ * @param record - The identity record to serialize.
+ * @returns The serialized payload.
+ */
+export declare function serializeRecord(record: IdentityRecord): string;
+/**
+ * Parses the on-disk representation of an identity record. Returns null when the payload cannot be interpreted as a complete record (missing or non-integer
+ * pid, missing bootId). Unknown key=value pairs are silently ignored so future fields can be added without breaking older readers.
+ * @param raw - The raw file contents.
+ * @returns The parsed record, or null when the payload is unusable.
+ */
+export declare function parseRecord(raw: string): Nullable<IdentityRecord>;
+//# sourceMappingURL=runtimeIdentity.d.ts.map

package/dist/utils/runtimeIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeIdentity.d.ts","sourceRoot":"","sources":["../../src/utils/runtimeIdentity.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAKlD;;GAEG;AACH,MAAM,WAAW,cAAc;IAG7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAGrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAG3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACvB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,WAAW,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IAGrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAQxC,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC,CAAC;IAG7D,QAAQ,CAAC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,sBAA8D,GAAG,aAAa,CAgD5H;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,GAAE,sBAA8D,GAAG,WAAW,CAoBvJ;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,sBAA8D,GAAG,IAAI,CAWnH;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAM9D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,CA6FjE"}

package/dist/utils/runtimeIdentity.js

@@ -0,0 +1,181 @@
+import { clearPidFile } from "./pid.js";
+import { createDefaultRuntimeIdentityContext } from "./runtimeIdentity.context.js";
+import fs from "node:fs";
+/**
+ * Inspects the identity file at the given path and reports the current state. Reads the file, parses the record, and combines boot session match with PID
+ * liveness and process-identity verification to classify which branch of the state machine applies. Never mutates disk state.
+ * @param filePath - The absolute path to the identity file.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ * @returns The current state.
+ */
+export function inspect(filePath, ctx = createDefaultRuntimeIdentityContext()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        // ENOENT is the canonical "no file" case: the slot is free.
+        if (error.code === "ENOENT") {
+            return { kind: "free" };
+        }
+        // Any other read error (EACCES, EIO, ...) is reported as malformed-with-empty-raw so callers fall through to the overwrite path rather than crashing on
+        // transient I/O.
+        return { kind: "stale-malformed", raw: "" };
+    }
+    const record = parseRecord(raw);
+    if (record === null) {
+        return { kind: "stale-malformed", raw };
+    }
+    if (record.bootId !== ctx.getBootSessionId()) {
+        return { kind: "stale-different-boot", record };
+    }
+    if (!ctx.isProcessRunning(record.pid)) {
+        return { kind: "stale-dead-pid", record };
+    }
+    // The PID is alive and the boot session matches, but within a single boot the kernel can reassign a freed PID to an unrelated process after PrismCast was
+    // SIGKILLed. We confirm process identity through the processInspector port: a verdict of false means the process table positively identified a non-PrismCast
+    // command line at this PID, so the original writer is gone and the slot is stale. A verdict of true (confirmed PrismCast) or null (cannot determine) both
+    // keep the held-live verdict - we only downgrade on positive proof of a different process. We classify the recycled case as stale-dead-pid rather than a
+    // new branch because the operational meaning is identical - the writing process is gone - and callers already overwrite that state.
+    if (ctx.isPidOurProcess(record.pid) === false) {
+        return { kind: "stale-dead-pid", record };
+    }
+    return { kind: "held-live", record };
+}
+/**
+ * Attempts to claim the identity slot at the given path for the current process. If the slot is free or in any "stale-*" state, the record is overwritten
+ * with our identity and { ok: true } is returned. If the slot is held-live by another process, no write occurs and { ok: false } is returned with the
+ * conflicting holder's record so the caller can surface a precise diagnostic.
+ * @param filePath - The absolute path to the identity file.
+ * @param metadata - Caller-supplied metadata (the version string at minimum) that ends up in the persisted record.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ * @returns The claim result.
+ */
+export function claim(filePath, metadata, ctx = createDefaultRuntimeIdentityContext()) {
+    const state = inspect(filePath, ctx);
+    if (state.kind === "held-live") {
+        return { conflict: state.record, ok: false };
+    }
+    const record = {
+        bootId: ctx.getBootSessionId(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        version: metadata.version
+    };
+    writeRecord(filePath, record);
+    return { ok: true, record };
+}
+/**
+ * Releases the identity slot by removing the file at the given path - but only if the file's record identifies the current process. The PID-match check
+ * inside makes ownership structural: a rejected duplicate startup's exit handler sees a held-live record belonging to a different PID and leaves the file
+ * alone, while the legitimate holder sees its own PID and cleans up. Safe to call more than once: a missing file is not an error. Release is purely hygiene -
+ * a process that fails to release on death has its file recovered transparently on the next startup via the stale-different-boot or stale-dead-pid branches.
+ * @param filePath - The absolute path to the identity file.
+ * @param ctx - The runtime identity context. Defaults to real I/O wiring.
+ */
+export function release(filePath, ctx = createDefaultRuntimeIdentityContext()) {
+    const state = inspect(filePath, ctx);
+    // Only remove the file when it identifies us. Any other state (free, stale, or held-live by another process) means it is not ours to remove.
+    if ((state.kind !== "held-live") || (state.record.pid !== process.pid)) {
+        return;
+    }
+    clearPidFile(filePath, "identity");
+}
+/**
+ * Unconditionally removes the identity file at the given path. Intended for an explicit user-invoked reset or recovery flow where the caller has deliberately
+ * asked to clear stale state without the safety check that release() provides. Prefer release() for normal lifecycle cleanup.
+ * @param filePath - The absolute path to the identity file.
+ */
+export function forceRelease(filePath) {
+    clearPidFile(filePath, "identity");
+}
+/**
+ * Serializes a record to its on-disk representation. The first line is the bare PID for backwards compatibility with shell tooling; subsequent lines are
+ * key=value pairs in deterministic order. The trailing newline keeps the file well-formed for POSIX text-file tools.
+ * @param record - The identity record to serialize.
+ * @returns The serialized payload.
+ */
+export function serializeRecord(record) {
+    return String(record.pid) + "\n" +
+        "bootId=" + record.bootId + "\n" +
+        "startedAt=" + record.startedAt + "\n" +
+        "version=" + record.version + "\n";
+}
+/**
+ * Parses the on-disk representation of an identity record. Returns null when the payload cannot be interpreted as a complete record (missing or non-integer
+ * pid, missing bootId). Unknown key=value pairs are silently ignored so future fields can be added without breaking older readers.
+ * @param raw - The raw file contents.
+ * @returns The parsed record, or null when the payload is unusable.
+ */
+export function parseRecord(raw) {
+    const lines = raw.split("\n");
+    // String.prototype.split always returns at least one element, so this guard can never actually fire - it is belt-and-suspenders defense that documents the
+    // empty-payload intent and keeps the array-access below structurally safe even if the split contract were ever to change.
+    if (lines.length === 0) {
+        return null;
+    }
+    const firstLine = lines[0];
+    if (firstLine === undefined) {
+        return null;
+    }
+    const pid = parseInt(firstLine.trim(), 10);
+    if (Number.isNaN(pid)) {
+        return null;
+    }
+    let bootId = null;
+    let startedAt = "";
+    let version = "";
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) {
+            continue;
+        }
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        const eq = trimmed.indexOf("=");
+        if (eq === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eq);
+        const value = trimmed.slice(eq + 1);
+        switch (key) {
+            case "bootId": {
+                bootId = value;
+                break;
+            }
+            case "startedAt": {
+                startedAt = value;
+                break;
+            }
+            case "version": {
+                version = value;
+                break;
+            }
+            default: {
+                // Unknown keys are silently ignored to support forward compatibility - older readers must tolerate fields added in newer writers.
+            }
+        }
+    }
+    // bootId is the only required metadata field. A file without one was written by a pre-runtimeIdentity PrismCast (or by an external tool) and is treated as
+    // malformed for state-machine purposes.
+    if (bootId === null) {
+        return null;
+    }
+    return { bootId, pid, startedAt, version };
+}
+/**
+ * Persists a record to disk via atomic write (write-temp + rename). On POSIX rename is atomic within a filesystem; on Windows the rename is best-effort but
+ * the partial-write window remains negligible. A torn write would parse as malformed, which the state machine recovers from on the next inspect - so atomicity
+ * here is hygiene, not something callers depend on for correctness.
+ * @param filePath - The absolute path to the identity file.
+ * @param record - The record to persist.
+ */
+function writeRecord(filePath, record) {
+    const payload = serializeRecord(record);
+    const tempPath = filePath + ".tmp";
+    fs.writeFileSync(tempPath, payload, "utf-8");
+    fs.renameSync(tempPath, filePath);
+}
+//# sourceMappingURL=runtimeIdentity.js.map

package/dist/utils/runtimeIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeIdentity.js","sourceRoot":"","sources":["../../src/utils/runtimeIdentity.ts"],"names":[],"mappings":"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"}

package/dist/utils/sanitize.d.ts

@@ -12,3 +12,4 @@ export declare function sanitizeString(value: string): string;
  * @returns True if the string contains at least one non-printable character.
  */
 export declare function containsNonPrintable(value: string): boolean;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/utils/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO3D"}