@gfdelarue/testkit 0.3.2 → 0.3.3

package/dist/process/files/json-file.js

@@ -1 +1 @@
-import s from"node:fs";import a from"node:path";const p=String;export function isPropertyContainer(t){return typeof t=="object"&&t!==null||typeof t=="function"}export function readProperty(t,e){return Reflect.get(t,e)}export function serializeJson(t,e){let r;try{r=JSON.stringify(t,null,2)}catch(o){throw new Error(`${e} is not JSON serializable`,{cause:o})}if(typeof r!="string")throw new Error(`${e} is not JSON serializable`);return r}export function errorMessage(t){if(t instanceof Error)return t.message;if(isPropertyContainer(t)){const e=readProperty(t,"message");if(typeof e=="string"&&e.length>0)return e}return p(t)}const u=new Set(["EPERM","EACCES","EBUSY"]),y=process.platform==="win32"?100:25,l=10,A=100;class S extends Error{attempts;code="TESTKIT_ATOMIC_WRITE_FAILED";cause;path;tempPath;constructor(e,r,o,n){super(`Failed to atomically replace ${e} after ${o.toString()} attempt${o===1?"":"s"}: ${errorMessage(n)}`,{cause:n}),this.name="AtomicWriteError",this.attempts=o,this.cause=n,this.path=e,this.tempPath=r}}export function writeJsonFileAtomicWithRetry(t,e,r={}){const o=a.dirname(t),n=a.join(o,`.${a.basename(t)}.${process.pid.toString()}.${Date.now().toString()}.${Math.random().toString(16).slice(2)}.tmp`),c=r.attempts??y,f=r.baseDelayMs??l,m=r.maxDelayMs??A;s.writeFileSync(n,serializeJson(e,`atomic JSON file ${t}`));try{for(let i=1;i<=c;i+=1)try{s.renameSync(n,t);return}catch(E){if(!isRetryableAtomicReplaceError(E)||i>=c)throw new S(t,n,i,E);R(Math.min(m,f*i))}}finally{s.rmSync(n,{force:!0})}}export function isRetryableAtomicReplaceError(t){if(!isPropertyContainer(t))return!1;const e=readProperty(t,"code");return typeof e=="string"&&u.has(e)}function R(t){if(t<=0)return;const e=new SharedArrayBuffer(4);Atomics.wait(new Int32Array(e),0,0,t)}
+import s from"node:fs";import c from"node:path";const p=String;export function isPropertyContainer(t){return typeof t=="object"&&t!==null||typeof t=="function"}export function readProperty(t,r){return Reflect.get(t,r)}export function serializeJson(t,r){let e;try{e=JSON.stringify(t,null,2)}catch(o){throw new Error(`${r} is not JSON serializable`,{cause:o})}if(typeof e!="string")throw new Error(`${r} is not JSON serializable`);return e}export function errorMessage(t){if(t instanceof Error)return t.message;if(isPropertyContainer(t)){const r=readProperty(t,"message");if(typeof r=="string"&&r.length>0)return r}return p(t)}const y=new Set(["EPERM","EACCES","EBUSY"]),u=process.platform==="win32"?100:25,l=10,S=100;class A extends Error{attempts;code="TESTKIT_ATOMIC_WRITE_FAILED";cause;path;tempPath;constructor(r,e,o,n){super(`Failed to atomically replace ${r} after ${o.toString()} attempt${o===1?"":"s"}: ${errorMessage(n)}`,{cause:n}),this.name="AtomicWriteError",this.attempts=o,this.cause=n,this.path=r,this.tempPath=e}}export function writeJsonFileAtomicWithRetry(t,r,e={}){const o=c.dirname(t),n=c.join(o,`.${c.basename(t)}.${process.pid.toString()}.${Date.now().toString()}.${Math.random().toString(16).slice(2)}.tmp`),a=e.attempts??u,E=e.baseDelayMs??l,m=e.maxDelayMs??S;s.writeFileSync(n,serializeJson(r,`atomic JSON file ${t}`));try{for(let i=1;i<=a;i+=1)try{s.renameSync(n,t);return}catch(f){if(!isRetryableAtomicReplaceError(f)||i>=a||R(t))throw new A(t,n,i,f);_(Math.min(m,E*i))}}finally{s.rmSync(n,{force:!0})}}export function isRetryableAtomicReplaceError(t){if(!isPropertyContainer(t))return!1;const r=readProperty(t,"code");return typeof r=="string"&&y.has(r)}function R(t){try{return s.lstatSync(t).isDirectory()}catch{return!1}}function _(t){if(t<=0)return;const r=new SharedArrayBuffer(4);Atomics.wait(new Int32Array(r),0,0,t)}

package/dist/process/host-process.d.ts

@@ -1,12 +1,17 @@
-import { type ManagedProcessRequest, type ManagedProcessResult, type SupervisedProcessHandle, type SupervisedProcessOutputMode } from "./process.js";
+import { type ManagedProcessRequest, type ManagedProcessResult, type SupervisedProcessHandle, type SupervisedProcessLiveHandle, type SupervisedProcessOutputMode } from "./process.js";
 export interface ManagedHostProcessRequest extends Omit<ManagedProcessRequest, "env" | "signal"> {
     readonly env?: Readonly<NodeJS.ProcessEnv>;
     readonly signal?: AbortSignal;
 }
 export interface SupervisedHostProcessRequest extends ManagedHostProcessRequest {
     readonly outputMode: SupervisedProcessOutputMode;
+    readonly recoveryIdentity?: "capture";
+}
+export interface SupervisedHostProcessWithoutRecoveryRequest extends Omit<SupervisedHostProcessRequest, "recoveryIdentity"> {
+    readonly recoveryIdentity: "none";
 }
 export declare function runManagedHostProcess(request: Readonly<ManagedHostProcessRequest>): Promise<ManagedProcessResult>;
+export declare function startManagedHostProcess(request: Readonly<SupervisedHostProcessWithoutRecoveryRequest>): SupervisedProcessLiveHandle;
 export declare function startManagedHostProcess(request: Readonly<SupervisedHostProcessRequest>): SupervisedProcessHandle;
 export declare function managedHostProcessInfrastructureError(displayLabel: string, result: Readonly<ManagedProcessResult>): Error | null;
 export declare function normalizeManagedHostEnvironment(environment?: Readonly<NodeJS.ProcessEnv>, platform?: NodeJS.Platform): Record<string, string>;

package/dist/process/host-process.js

@@ -1 +1 @@
-import d from"node:fs";import s from"node:path";import{runManagedProcess as h,startSupervisedProcess as E}from"./process.js";export function runManagedHostProcess(e){const t=f(e);return h(t)}export function startManagedHostProcess(e){const t=f(e);return E({...t,outputMode:e.outputMode})}export function managedHostProcessInfrastructureError(e,t){const o=[];if(t.terminationError&&o.push(`process-scope termination was incomplete: ${t.terminationError.message}`),t.error&&o.push(`could not execute: ${t.error.message}`),t.timedOut&&o.push("exceeded its managed deadline"),t.cancelled&&o.push("was cancelled"),t.outputLimitExceeded&&o.push("exceeded the managed stdout/stderr capture limit"),o.length===0)return null;const n=new Error(`${e} ${o.join("; ")}`);return Object.defineProperty(n,"result",{enumerable:!1,value:Object.freeze({...t})}),n}export function normalizeManagedHostEnvironment(e=process.env,t=process.platform){const o=Object.entries(e).filter(r=>typeof r[1]=="string");if(t!=="win32")return Object.fromEntries(o);const n=new Map;for(const[r,a]of o){const c=r.toLowerCase();n.set(c,{key:v(c,r),value:a})}return Object.fromEntries([...n.entries()].sort(([r],[a])=>r.localeCompare(a)).map(([,r])=>[r.key,r.value]))}export function resolveManagedHostExecutable(e,t,o,n=process.platform){const r=resolveManagedHostExecutableIfAvailable(e,t,o,n);if(r)return r;throw o.PATH?new Error(`Could not resolve managed host executable ${JSON.stringify(e)}`):new Error(`Could not resolve managed host executable ${JSON.stringify(e)} because PATH is unavailable`)}export function resolveManagedHostExecutableIfAvailable(e,t,o,n=process.platform){if(e.trim().length===0)throw new Error("Managed host process executable must be non-empty");if(!s.isAbsolute(t))throw new Error("Managed host process working directory must be absolute");if(s.isAbsolute(e))return m(e,n);if(e.includes("/")||e.includes("\\"))throw new Error(`Managed host process executable paths must be absolute, got ${JSON.stringify(e)}`);const r=o.PATH;if(!r)return null;const a=b(e,o,n),c=n==="win32"?";":":";for(const u of r.split(c)){if(u.length===0)continue;const g=s.isAbsolute(u)?u:s.resolve(t,u);for(const w of a){const l=s.join(g,`${e}${w}`);try{const i=d.statSync(l);if(i.isFile()&&(n==="win32"||(i.mode&73)!==0))return m(l,n)}catch(i){if(!p(i,"ENOENT")&&!p(i,"ENOTDIR"))throw i}}}return null}function f(e){const t=s.resolve(e.cwd),o=normalizeManagedHostEnvironment(e.env);return{args:e.args,cwd:t,displayLabel:e.displayLabel,env:o,executable:resolveManagedHostExecutable(e.executable,t,o),signal:e.signal??new AbortController().signal,timeoutMs:e.timeoutMs,windowsVerbatimArguments:e.windowsVerbatimArguments}}function b(e,t,o){return o!=="win32"?[""]:s.extname(e).length>0?[""]:(t.PATHEXT||".COM;.EXE").split(";").map(r=>r.trim()).filter(r=>[".com",".exe"].includes(r.toLowerCase()))}function m(e,t){if(t==="win32"&&[".bat",".cmd"].includes(s.extname(e).toLowerCase()))throw new Error(`Windows batch wrappers are not managed host executables: ${e}`);const o=d.statSync(e);if(!o.isFile())throw new Error(`Managed host executable is not a regular file: ${e}`);if(t!=="win32"&&(o.mode&73)===0)throw new Error(`Managed host executable is not executable: ${e}`);return e}function v(e,t){return e==="path"?"PATH":e==="pathext"?"PATHEXT":e==="comspec"?"ComSpec":t}function p(e,t){return e!==null&&typeof e=="object"&&"code"in e&&Reflect.get(e,"code")===t}
+import l from"node:fs";import s from"node:path";import{runManagedProcess as E,startSupervisedProcess as f}from"./process.js";export function runManagedHostProcess(e){const t=m(e);return E(t)}export function startManagedHostProcess(e){const t=m(e);return e.recoveryIdentity==="none"?f({...t,outputMode:e.outputMode,recoveryIdentity:"none"}):f({...t,outputMode:e.outputMode})}export function managedHostProcessInfrastructureError(e,t){const o=[];if(t.terminationError&&o.push(`process-scope termination was incomplete: ${t.terminationError.message}`),t.error&&o.push(`could not execute: ${t.error.message}`),t.timedOut&&o.push("exceeded its managed deadline"),t.cancelled&&o.push("was cancelled"),t.outputLimitExceeded&&o.push("exceeded the managed stdout/stderr capture limit"),o.length===0)return null;const r=new Error(`${e} ${o.join("; ")}`);return Object.defineProperty(r,"result",{enumerable:!1,value:Object.freeze({...t})}),r}export function normalizeManagedHostEnvironment(e=process.env,t=process.platform){const o=Object.entries(e).filter(n=>typeof n[1]=="string");if(t!=="win32")return Object.fromEntries(o);const r=new Map;for(const[n,a]of o){const c=n.toLowerCase();r.set(c,{key:y(c,n),value:a})}return Object.fromEntries([...r.entries()].sort(([n],[a])=>n.localeCompare(a)).map(([,n])=>[n.key,n.value]))}export function resolveManagedHostExecutable(e,t,o,r=process.platform){const n=resolveManagedHostExecutableIfAvailable(e,t,o,r);if(n)return n;throw o.PATH?new Error(`Could not resolve managed host executable ${JSON.stringify(e)}`):new Error(`Could not resolve managed host executable ${JSON.stringify(e)} because PATH is unavailable`)}export function resolveManagedHostExecutableIfAvailable(e,t,o,r=process.platform){if(e.trim().length===0)throw new Error("Managed host process executable must be non-empty");if(!s.isAbsolute(t))throw new Error("Managed host process working directory must be absolute");if(s.isAbsolute(e))return p(e,r);if(e.includes("/")||e.includes("\\"))throw new Error(`Managed host process executable paths must be absolute, got ${JSON.stringify(e)}`);const n=o.PATH;if(!n)return null;const a=b(e,o,r),c=r==="win32"?";":":";for(const u of n.split(c)){if(u.length===0)continue;const g=s.isAbsolute(u)?u:s.resolve(t,u);for(const h of a){const d=s.join(g,`${e}${h}`);try{const i=l.statSync(d,{throwIfNoEntry:!1});if(i!==void 0&&i.isFile()&&(r==="win32"||(i.mode&73)!==0))return p(d,r)}catch(i){if(!w(i,"ENOENT")&&!w(i,"ENOTDIR"))throw i}}}return null}function m(e){const t=s.resolve(e.cwd),o=normalizeManagedHostEnvironment(e.env);return{args:e.args,cwd:t,displayLabel:e.displayLabel,env:o,executable:resolveManagedHostExecutable(e.executable,t,o),signal:e.signal??new AbortController().signal,timeoutMs:e.timeoutMs,windowsVerbatimArguments:e.windowsVerbatimArguments}}function b(e,t,o){return o!=="win32"?[""]:s.extname(e).length>0?[""]:(t.PATHEXT||".COM;.EXE").split(";").map(n=>n.trim()).filter(n=>[".com",".exe"].includes(n.toLowerCase()))}function p(e,t){if(t==="win32"&&[".bat",".cmd"].includes(s.extname(e).toLowerCase()))throw new Error(`Windows batch wrappers are not managed host executables: ${e}`);const o=l.statSync(e);if(!o.isFile())throw new Error(`Managed host executable is not a regular file: ${e}`);if(t!=="win32"&&(o.mode&73)===0)throw new Error(`Managed host executable is not executable: ${e}`);return e}function y(e,t){return e==="path"?"PATH":e==="pathext"?"PATHEXT":e==="comspec"?"ComSpec":t}function w(e,t){return e!==null&&typeof e=="object"&&"code"in e&&Reflect.get(e,"code")===t}

package/dist/process/index.d.ts

@@ -1,5 +1,5 @@
-export { runManagedProcess, ProcessExitedBeforeReadyError, startSupervisedProcess, terminateAttributedProcessLineage, terminateOwnedPosixProcessGroup, type AttributedProcessLineageTerminationRequest, type ManagedProcessCancellationSignal, type ManagedProcessRequest, type ManagedProcessResult, type OwnedPosixProcessGroupTerminationRequest, type SupervisedProcessHandle, type SupervisedProcessOutputMode, type SupervisedProcessRecoveryIdentity, type SupervisedProcessReady, type SupervisedProcessRequest, } from "./process.js";
-export { managedHostProcessInfrastructureError, normalizeManagedHostEnvironment, resolveManagedHostExecutable, resolveManagedHostExecutableIfAvailable, runManagedHostProcess, startManagedHostProcess, type ManagedHostProcessRequest, type SupervisedHostProcessRequest, } from "./host-process.js";
+export { runManagedProcess, ProcessExitedBeforeReadyError, startSupervisedProcess, terminateAttributedProcessLineage, terminateOwnedPosixProcessGroup, type AttributedProcessLineageTerminationRequest, type ManagedProcessCancellationSignal, type ManagedProcessRequest, type ManagedProcessResult, type OwnedPosixProcessGroupTerminationRequest, type SupervisedProcessHandle, type SupervisedProcessLiveHandle, type SupervisedProcessWithoutRecoveryRequest, type SupervisedProcessOutputMode, type SupervisedProcessRecoveryIdentity, type SupervisedProcessReady, type SupervisedProcessRequest, } from "./process.js";
+export { managedHostProcessInfrastructureError, normalizeManagedHostEnvironment, resolveManagedHostExecutable, resolveManagedHostExecutableIfAvailable, runManagedHostProcess, startManagedHostProcess, type ManagedHostProcessRequest, type SupervisedHostProcessRequest, type SupervisedHostProcessWithoutRecoveryRequest, } from "./host-process.js";
 export { requireManagedHostCommandSuccess, runManagedHostCommand } from "./host-command.js";
 export { resolvePosixCommandShell } from "./command-shell.js";
 export { captureOutput, type CaptureOutputOptions, type OutputLineHandler } from "./capture-output.js";

package/dist/process/locks.js

@@ -1,4 +1,4 @@
-import{AsyncLocalStorage as te}from"node:async_hooks";import{randomUUID as re}from"node:crypto";import c from"node:fs";import ne from"node:os";import l from"node:path";import{setTimeout as oe}from"node:timers/promises";import{captureProcessCreationIdentity as F}from"./process-identity.js";function se(e){try{c.mkdirSync(e,{mode:448})}catch(t){if(!i(t,"EEXIST"))throw t}return x(e)}function ce(e){try{const t=c.lstatSync(e);return t.isDirectory()&&!t.isSymbolicLink()?"real":"unsafe"}catch(t){if(i(t,"ENOENT"))return"absent";throw t}}function j(e){const t=c.lstatSync(e,{bigint:!0});if(!t.isDirectory()||t.isSymbolicLink())throw new Error(`Process lock path is not a real directory: ${e}`);return{birthtimeNs:t.birthtimeNs,dev:t.dev,ino:t.ino}}function x(e){try{return j(e)}catch(t){if(i(t,"ENOENT")||ae(t))return null;throw t}}function h(e,t){const n=x(e);return n!==null&&n.birthtimeNs===t.birthtimeNs&&n.dev===t.dev&&n.ino===t.ino}function ie(e,t,n){return h(e,t)?M(n)?"unsafe":"retry":h(n,t)?"published":"unsafe"}function ae(e){return e instanceof Error&&e.message.startsWith("Process lock path is not a real directory:")}const K="owner.json",R=1,A="claim-",g="choosing",V="ticket",ue=100,U=65e3,le=100,fe=new Set(["EACCES","EBUSY","EPERM"]),de=5e3,W=ne.hostname(),me=process.platform==="win32"?de:0,T=new te;class q extends Error{constructor(t,n){super(`Timed out waiting for process lock ${l.basename(t)}${ve(n)}`),this.name="ProcessLockTimeoutError"}}export async function withProcessLock(e,t,n={}){const r=z(e);_e(r);const o=await he(r,n),s=T.getStore(),d=new Set(s??[]);d.add(r);try{return await T.run(d,t)}finally{o()}}export async function tryWithProcessLock(e,t,n={}){let r;try{r=await withProcessLock(e,async()=>{try{return{ok:!0,value:await t()}}catch(o){return{error:o,ok:!1}}},{...n,timeoutMs:0})}catch(o){if(o instanceof q)return{acquired:!1};throw o}if(!r.ok)throw r.error;return{acquired:!0,value:r.value}}export function probeProcessLock(e,t={}){const n=z(e),r=X(n);if(!M(r))return"absent";const o=t.identityObservations??new Map,s=b(r,o,t);return s.rootAvailable&&s.claims.length===0?(P(r),"absent"):"active"}async function he(e,t){const n=De(t.timeoutMs,null,"process lock timeout"),r=Fe(t.retryIntervalMs,ue,"process lock retry interval"),o=t.identityObservations??new Map,s=Q(process.pid);if(s===null)throw new Error(`Cannot acquire process lock ${e}: current process creation identity is unavailable`);const d=Date.now(),f={createdAt:new Date(d).toISOString(),hostname:W,pid:process.pid,processIdentity:s,schemaVersion:R,token:re()},a=X(e),u=l.join(a,`${A}${f.token}`),p=`${a}.preparing-${f.token}`;Ee(p,f);let y=null,v=!1,w=null,S=!1,D=0;try{for(y=j(p);;){N(t.signal,e);const E=se(a);if(E!==null){try{c.renameSync(p,u),S=!0,w=E}catch(m){if(!i(m,"ENOENT"))if(ye(m)){const k=ie(p,y,u);if(k==="published")S=!0,w=E;else if(k==="retry"&&D<le)D+=1;else throw m}else throw m}if(S){if(!h(a,E))throw new Error(`Process lock directory changed during claim publication: ${a}`);if(!h(u,y))throw new Error(`Process lock claim changed during publication: ${u}`);break}}else b(a,o,t);G(e,null,d,n),await J(r,t.signal,e)}if(w===null)throw new Error(`Process lock claim was published without its directory identity: ${u}`);const I=w,Z=b(a,o,t,I),L=we(Z.claims);for(pe(u,L);;){N(t.signal,e);const E=b(a,o,t,I),m=E.claims.find(ee=>ee.claimDirectory===u);if(m?.state!=="ready"||m.ticket!==L||m.ownerRecord===null||!B(m.ownerRecord,f))throw new Error(`Process lock claim disappeared or changed before acquisition: ${u}`);const k=ke(E.claims,m);if(k===null)return v=!0,()=>{Re(u,a,I,f,L)};G(e,k.ownerRecord,d,n),await J(r,t.signal,e)}}finally{S?!v&&w!==null&&y!==null&&h(a,w)&&h(u,y)&&(c.rmSync(u,{force:!0,recursive:!0}),o.delete(u),P(a)):y!==null&&h(p,y)&&c.rmSync(p,{force:!0,recursive:!0})}}function ye(e){return process.platform==="win32"&&C(e)&&typeof e.code=="string"&&fe.has(e.code)}function Ee(e,t){c.mkdirSync(e,{mode:448});try{c.writeFileSync(l.join(e,K),`${JSON.stringify(t)}
+import{AsyncLocalStorage as Z}from"node:async_hooks";import{randomUUID as ee}from"node:crypto";import c from"node:fs";import te from"node:os";import l from"node:path";import{setTimeout as re}from"node:timers/promises";import{captureProcessCreationIdentity as D}from"./process-identity.js";function ne(e){try{c.mkdirSync(e,{mode:448})}catch(t){if(!i(t,"EEXIST"))throw t}return j(e)}function oe(e){try{const t=c.lstatSync(e);return t.isDirectory()&&!t.isSymbolicLink()?"real":"unsafe"}catch(t){if(i(t,"ENOENT"))return"absent";throw t}}function F(e){const t=c.lstatSync(e,{bigint:!0});if(!t.isDirectory()||t.isSymbolicLink())throw new Error(`Process lock path is not a real directory: ${e}`);return{birthtimeNs:t.birthtimeNs,dev:t.dev,ino:t.ino}}function j(e){try{return F(e)}catch(t){if(i(t,"ENOENT")||ce(t))return null;throw t}}function h(e,t){const n=j(e);return n!==null&&n.birthtimeNs===t.birthtimeNs&&n.dev===t.dev&&n.ino===t.ino}function se(e,t,n){return h(e,t)?M(n)?"unsafe":"retry":h(n,t)?"published":"unsafe"}function ce(e){return e instanceof Error&&e.message.startsWith("Process lock path is not a real directory:")}const x="owner.json",R=1,A="claim-",g="choosing",K="ticket",ie=100,V=65e3,ae=100,ue=new Set(["EACCES","EBUSY","EPERM"]),le=5e3,U=te.hostname(),fe=process.platform==="win32"?le:0,T=new Z;class W extends Error{constructor(t,n){super(`Timed out waiting for process lock ${l.basename(t)}${Ce(n)}`),this.name="ProcessLockTimeoutError"}}export async function withProcessLock(e,t,n={}){const r=X(e);Oe(r);const o=await me(r,n),s=T.getStore(),m=new Set(s??[]);m.add(r);try{return await T.run(m,t)}finally{o()}}export async function tryWithProcessLock(e,t,n={}){let r;try{r=await withProcessLock(e,async()=>{try{return{ok:!0,value:await t()}}catch(o){return{error:o,ok:!1}}},{...n,timeoutMs:0})}catch(o){if(o instanceof W)return{acquired:!1};throw o}if(!r.ok)throw r.error;return{acquired:!0,value:r.value}}export function probeProcessLock(e,t={}){const n=X(e),r=B(n);if(!M(r))return"absent";const o=t.identityObservations??new Map,s=b(r,o,t);return s.rootAvailable&&s.claims.length===0?(_(r),"absent"):"active"}async function me(e,t){const n=$e(t.timeoutMs,null,"process lock timeout"),r=ve(t.retryIntervalMs,ie,"process lock retry interval"),o=t.identityObservations??new Map,s=D(process.pid);if(s===null)throw new Error(`Cannot acquire process lock ${e}: current process creation identity is unavailable`);const m=Date.now(),f={createdAt:new Date(m).toISOString(),hostname:U,pid:process.pid,processIdentity:s,schemaVersion:R,token:ee()},a=B(e),u=l.join(a,`${A}${f.token}`),w=`${a}.preparing-${f.token}`;he(w,f);let y=null,$=!1,p=null,S=!1,v=0;try{for(y=F(w);;){N(t.signal,e);const E=ne(a);if(E!==null){try{c.renameSync(w,u),S=!0,p=E}catch(d){if(!i(d,"ENOENT"))if(de(d)){const k=se(w,y,u);if(k==="published")S=!0,p=E;else if(k==="retry"&&v<ae)v+=1;else throw d}else throw d}if(S){if(!h(a,E))throw new Error(`Process lock directory changed during claim publication: ${a}`);if(!h(u,y))throw new Error(`Process lock claim changed during publication: ${u}`);break}}else b(a,o,t);z(e,null,m,n),await G(r,t.signal,e)}if(p===null)throw new Error(`Process lock claim was published without its directory identity: ${u}`);const I=p,J=b(a,o,t,I),L=Ee(J.claims);for(ye(u,L);;){N(t.signal,e);const E=b(a,o,t,I),d=E.claims.find(Q=>Q.claimDirectory===u);if(d?.state!=="ready"||d.ticket!==L||d.ownerRecord===null||!H(d.ownerRecord,f))throw new Error(`Process lock claim disappeared or changed before acquisition: ${u}`);const k=we(E.claims,d);if(k===null)return $=!0,()=>{Ie(u,a,I,f,L)};z(e,k.ownerRecord,m,n),await G(r,t.signal,e)}}finally{S?!$&&p!==null&&y!==null&&h(a,p)&&h(u,y)&&(c.rmSync(u,{force:!0,recursive:!0}),o.delete(u),_(a)):y!==null&&h(w,y)&&c.rmSync(w,{force:!0,recursive:!0})}}function de(e){return process.platform==="win32"&&C(e)&&typeof e.code=="string"&&ue.has(e.code)}function he(e,t){c.mkdirSync(e,{mode:448});try{c.writeFileSync(l.join(e,x),`${JSON.stringify(t)}
 `,{encoding:"utf8",flag:"wx",mode:384}),c.writeFileSync(l.join(e,g),`${t.token}
-`,{encoding:"utf8",flag:"wx",mode:384})}catch(n){throw c.rmSync(e,{force:!0,recursive:!0}),n}}function pe(e,t){c.writeFileSync(l.join(e,V),`${t.toString()}
-`,{encoding:"utf8",flag:"wx",mode:384}),c.rmSync(l.join(e,g))}function we(e){const t=e.reduce((n,r)=>r.ticket===null?n:Math.max(n,r.ticket),0);if(t>=Number.MAX_SAFE_INTEGER)throw new Error("Process lock ticket space is exhausted");return t+1}function ke(e,t){if(t.ticket===null||t.ownerRecord===null)return t;const n=t.ownerRecord.token;for(const r of e){if(r.claimDirectory===t.claimDirectory)continue;if(r.state!=="ready"||r.ticket===null||r.ownerRecord===null)return r;const o=r.ownerRecord.token;if(Se(r.ticket,o,t.ticket,n)<0)return r}return null}function Se(e,t,n,r){return e===n?t.localeCompare(r):e-n}function b(e,t,n,r=null){const o=ce(e);if(o==="absent")return{claims:[],rootAvailable:!0};if(o==="unsafe"){const f=O(e);return Le(e,t,n)?{claims:[],rootAvailable:!0}:{claims:[f],rootAvailable:!1}}if(r!==null&&!h(e,r))return{claims:[O(e)],rootAvailable:!1};let s;try{s=c.readdirSync(e,{withFileTypes:!0})}catch(f){if(i(f,"ENOENT"))return{claims:[],rootAvailable:!0};throw f}const d=[];for(const f of s){const a=l.join(e,f.name),u=!f.name.startsWith(A)||!f.isDirectory()?O(a):Y(a);Ne(u,t,n)?Ie(a,t):d.push(u)}return{claims:d,rootAvailable:!0}}function O(e){return{claimDirectory:e,ownerRecord:null,state:"malformed",ticket:null}}function Y(e){const t=Te(e),n=M(l.join(e,g)),r=be(e),o=l.basename(e).slice(A.length),s=t===null||t.token===o;return{claimDirectory:e,ownerRecord:t,state:t===null||!s?"malformed":n?"choosing":r===null?"malformed":"ready",ticket:r}}function be(e){try{const t=c.readFileSync(l.join(e,V),"utf8").trim(),n=Number(t);return Number.isSafeInteger(n)&&n>0?n:null}catch{return null}}function Ne(e,t,n){const r=e.ownerRecord;if(r===null||r.hostname!==W)return n.hostScope==="current-host"&&Me(e.claimDirectory)>=U;if(Ce(r.pid)==="absent")return!0;const o=_(r),s=t.get(e.claimDirectory);if(s?.ownerKey===o&&Date.now()-s.checkedAtMs<me)return!1;const d=Q(r.pid);return t.set(e.claimDirectory,{checkedAtMs:Date.now(),ownerKey:o}),d!==null&&d!==r.processIdentity}function Ie(e,t){t.delete(e),c.rmSync(e,{force:!0,recursive:!0})}function Le(e,t,n){if(n.hostScope!=="current-host")return!1;const r=H(e);if(r==="absent")return!0;if(r==="real-directory"||ge(r)<U)return!1;const o=H(e);if(o==="absent")return!0;if(o==="real-directory"||!Ae(o,r))return!1;try{return c.unlinkSync(e),t.delete(e),!0}catch(s){if(i(s,"ENOENT"))return!0;if(i(s,"EISDIR")||i(s,"EPERM"))return!1;throw s}}function Re(e,t,n,r,o){if(!h(t,n))throw new Error(`Process lock directory changed before release: ${t}`);const s=Y(e);if(s.state!=="ready"||s.ticket!==o||s.ownerRecord===null||!B(s.ownerRecord,r))throw new Error(`Process lock ownership changed before release: ${e}`);c.rmSync(e,{force:!0,recursive:!0}),P(t)}function H(e){try{const t=c.lstatSync(e,{bigint:!0});return t.isDirectory()&&!t.isSymbolicLink()?"real-directory":{birthtimeNs:t.birthtimeNs,ctimeNs:t.ctimeNs,dev:t.dev,ino:t.ino,mode:t.mode,mtimeNs:t.mtimeNs,size:t.size}}catch(t){if(i(t,"ENOENT"))return"absent";throw t}}function Ae(e,t){return e.birthtimeNs===t.birthtimeNs&&e.ctimeNs===t.ctimeNs&&e.dev===t.dev&&e.ino===t.ino&&e.mode===t.mode&&e.mtimeNs===t.mtimeNs&&e.size===t.size}function ge(e){return Math.max(0,Date.now()-Number(e.mtimeNs)/1e6)}function P(e){try{c.rmdirSync(e)}catch(t){if(!i(t,"ENOENT")&&!i(t,"ENOTEMPTY")&&!i(t,"EEXIST"))throw t}}function Te(e){let t;try{t=JSON.parse(c.readFileSync(l.join(e,K),"utf8"))}catch{return null}return C(t)?Oe(t):null}function Oe(e){const t=Object.keys(e).sort(),n=["createdAt","hostname","pid","processIdentity","schemaVersion","token"];return t.length!==n.length||t.some((r,o)=>r!==n[o])||e.schemaVersion!==R||!je(e.createdAt)||typeof e.hostname!="string"||e.hostname.length===0||!xe(e.pid)||typeof e.processIdentity!="string"||e.processIdentity.length===0||typeof e.token!="string"||e.token.length===0?null:{createdAt:e.createdAt,hostname:e.hostname,pid:e.pid,processIdentity:e.processIdentity,schemaVersion:R,token:e.token}}function B(e,t){return _(e)===_(t)}function _(e){return[e.hostname,e.pid.toString(),e.processIdentity,e.token,e.createdAt].join("\0")}function X(e){return`${e}.dir`}function z(e){const t=l.resolve(Pe(e)),n=c.realpathSync.native(l.dirname(t));return l.join(n,l.basename(t))}function Pe(e){if(e.trim().length===0)throw new Error("Process lock path must not be empty");return e}function _e(e){if(T.getStore()?.has(e))throw new Error(`Reentrant process lock acquisition is not allowed: ${e}`)}function G(e,t,n,r){if(r!==null&&Date.now()-n>=r)throw new q(e,t)}function Me(e){try{return Math.max(0,Date.now()-c.lstatSync(e).mtimeMs)}catch(t){if(i(t,"ENOENT"))return Number.POSITIVE_INFINITY;throw t}}function Ce(e){try{return process.kill(e,0),"alive"}catch(t){return i(t,"ESRCH")?"absent":i(t,"EPERM")?"alive":"unknown"}}async function J(e,t,n){N(t,n);try{await oe(e,void 0,{signal:t})}catch(r){throw N(t,n),r}}function N(e,t){if(e?.aborted)throw $e(e,t)}function $e(e,t){return e.reason instanceof Error?e.reason:new Error(`Waiting for process lock was aborted: ${t}`)}function ve(e){return e===null?"":` (host=${e.hostname} pid=${e.pid.toString()} identity=${e.processIdentity} createdAt=${e.createdAt})`}function De(e,t,n){const r=e===void 0?t:e;if(r!==null&&(!Number.isSafeInteger(r)||r<0))throw new Error(`${n} must be null or a non-negative safe integer`);return r}function Fe(e,t,n){const r=e??t;if(!Number.isSafeInteger(r)||r<=0)throw new Error(`${n} must be a positive safe integer`);return r}function je(e){return typeof e=="string"&&e.length>0&&Number.isFinite(Date.parse(e))}function xe(e){return Number.isSafeInteger(e)&&Number(e)>0}function M(e){try{return c.lstatSync(e),!0}catch(t){if(i(t,"ENOENT"))return!1;throw t}}function i(e,t){return C(e)&&e.code===t}function C(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}let $;function Q(e){return e!==process.pid?F(e):($===void 0&&($=F(e)),$)}
+`,{encoding:"utf8",flag:"wx",mode:384})}catch(n){throw c.rmSync(e,{force:!0,recursive:!0}),n}}function ye(e,t){c.writeFileSync(l.join(e,K),`${t.toString()}
+`,{encoding:"utf8",flag:"wx",mode:384}),c.rmSync(l.join(e,g))}function Ee(e){const t=e.reduce((n,r)=>r.ticket===null?n:Math.max(n,r.ticket),0);if(t>=Number.MAX_SAFE_INTEGER)throw new Error("Process lock ticket space is exhausted");return t+1}function we(e,t){if(t.ticket===null||t.ownerRecord===null)return t;const n=t.ownerRecord.token;for(const r of e){if(r.claimDirectory===t.claimDirectory)continue;if(r.state!=="ready"||r.ticket===null||r.ownerRecord===null)return r;const o=r.ownerRecord.token;if(pe(r.ticket,o,t.ticket,n)<0)return r}return null}function pe(e,t,n,r){return e===n?t.localeCompare(r):e-n}function b(e,t,n,r=null){const o=oe(e);if(o==="absent")return{claims:[],rootAvailable:!0};if(o==="unsafe"){const f=O(e);return Ne(e,t,n)?{claims:[],rootAvailable:!0}:{claims:[f],rootAvailable:!1}}if(r!==null&&!h(e,r))return{claims:[O(e)],rootAvailable:!1};let s;try{s=c.readdirSync(e,{withFileTypes:!0})}catch(f){if(i(f,"ENOENT"))return{claims:[],rootAvailable:!0};throw f}const m=[];for(const f of s){const a=l.join(e,f.name),u=!f.name.startsWith(A)||!f.isDirectory()?O(a):q(a);Se(u,t,n)?be(a,t):m.push(u)}return{claims:m,rootAvailable:!0}}function O(e){return{claimDirectory:e,ownerRecord:null,state:"malformed",ticket:null}}function q(e){const t=Ae(e),n=M(l.join(e,g)),r=ke(e),o=l.basename(e).slice(A.length),s=t===null||t.token===o;return{claimDirectory:e,ownerRecord:t,state:t===null||!s?"malformed":n?"choosing":r===null?"malformed":"ready",ticket:r}}function ke(e){try{const t=c.readFileSync(l.join(e,K),"utf8").trim(),n=Number(t);return Number.isSafeInteger(n)&&n>0?n:null}catch{return null}}function Se(e,t,n){const r=e.ownerRecord;if(r===null||r.hostname!==U)return n.hostScope==="current-host"&&_e(e.claimDirectory)>=V;if(Pe(r.pid)==="absent")return!0;const o=P(r),s=t.get(e.claimDirectory);if(s?.ownerKey===o&&Date.now()-s.checkedAtMs<fe)return!1;const m=D(r.pid);return t.set(e.claimDirectory,{checkedAtMs:Date.now(),ownerKey:o}),m!==null&&m!==r.processIdentity}function be(e,t){t.delete(e),c.rmSync(e,{force:!0,recursive:!0})}function Ne(e,t,n){if(n.hostScope!=="current-host")return!1;const r=Y(e);if(r==="absent")return!0;if(r==="real-directory"||Re(r)<V)return!1;const o=Y(e);if(o==="absent")return!0;if(o==="real-directory"||!Le(o,r))return!1;try{return c.unlinkSync(e),t.delete(e),!0}catch(s){if(i(s,"ENOENT"))return!0;if(i(s,"EISDIR")||i(s,"EPERM"))return!1;throw s}}function Ie(e,t,n,r,o){if(!h(t,n))throw new Error(`Process lock directory changed before release: ${t}`);const s=q(e);if(s.state!=="ready"||s.ticket!==o||s.ownerRecord===null||!H(s.ownerRecord,r))throw new Error(`Process lock ownership changed before release: ${e}`);c.rmSync(e,{force:!0,recursive:!0}),_(t)}function Y(e){try{const t=c.lstatSync(e,{bigint:!0});return t.isDirectory()&&!t.isSymbolicLink()?"real-directory":{birthtimeNs:t.birthtimeNs,ctimeNs:t.ctimeNs,dev:t.dev,ino:t.ino,mode:t.mode,mtimeNs:t.mtimeNs,size:t.size}}catch(t){if(i(t,"ENOENT"))return"absent";throw t}}function Le(e,t){return e.birthtimeNs===t.birthtimeNs&&e.ctimeNs===t.ctimeNs&&e.dev===t.dev&&e.ino===t.ino&&e.mode===t.mode&&e.mtimeNs===t.mtimeNs&&e.size===t.size}function Re(e){return Math.max(0,Date.now()-Number(e.mtimeNs)/1e6)}function _(e){try{c.rmdirSync(e)}catch(t){if(!i(t,"ENOENT")&&!i(t,"ENOTEMPTY")&&!i(t,"EEXIST"))throw t}}function Ae(e){let t;try{t=JSON.parse(c.readFileSync(l.join(e,x),"utf8"))}catch{return null}return C(t)?ge(t):null}function ge(e){const t=Object.keys(e).sort(),n=["createdAt","hostname","pid","processIdentity","schemaVersion","token"];return t.length!==n.length||t.some((r,o)=>r!==n[o])||e.schemaVersion!==R||!De(e.createdAt)||typeof e.hostname!="string"||e.hostname.length===0||!Fe(e.pid)||typeof e.processIdentity!="string"||e.processIdentity.length===0||typeof e.token!="string"||e.token.length===0?null:{createdAt:e.createdAt,hostname:e.hostname,pid:e.pid,processIdentity:e.processIdentity,schemaVersion:R,token:e.token}}function H(e,t){return P(e)===P(t)}function P(e){return[e.hostname,e.pid.toString(),e.processIdentity,e.token,e.createdAt].join("\0")}function B(e){return`${e}.dir`}function X(e){const t=l.resolve(Te(e)),n=c.realpathSync.native(l.dirname(t));return l.join(n,l.basename(t))}function Te(e){if(e.trim().length===0)throw new Error("Process lock path must not be empty");return e}function Oe(e){if(T.getStore()?.has(e))throw new Error(`Reentrant process lock acquisition is not allowed: ${e}`)}function z(e,t,n,r){if(r!==null&&Date.now()-n>=r)throw new W(e,t)}function _e(e){try{return Math.max(0,Date.now()-c.lstatSync(e).mtimeMs)}catch(t){if(i(t,"ENOENT"))return Number.POSITIVE_INFINITY;throw t}}function Pe(e){try{return process.kill(e,0),"alive"}catch(t){return i(t,"ESRCH")?"absent":i(t,"EPERM")?"alive":"unknown"}}async function G(e,t,n){N(t,n);try{await re(e,void 0,{signal:t})}catch(r){throw N(t,n),r}}function N(e,t){if(e?.aborted)throw Me(e,t)}function Me(e,t){return e.reason instanceof Error?e.reason:new Error(`Waiting for process lock was aborted: ${t}`)}function Ce(e){return e===null?"":` (host=${e.hostname} pid=${e.pid.toString()} identity=${e.processIdentity} createdAt=${e.createdAt})`}function $e(e,t,n){const r=e===void 0?t:e;if(r!==null&&(!Number.isSafeInteger(r)||r<0))throw new Error(`${n} must be null or a non-negative safe integer`);return r}function ve(e,t,n){const r=e??t;if(!Number.isSafeInteger(r)||r<=0)throw new Error(`${n} must be a positive safe integer`);return r}function De(e){return typeof e=="string"&&e.length>0&&Number.isFinite(Date.parse(e))}function Fe(e){return Number.isSafeInteger(e)&&Number(e)>0}function M(e){try{return c.lstatSync(e),!0}catch(t){if(i(t,"ENOENT"))return!1;throw t}}function i(e,t){return C(e)&&e.code===t}function C(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}

package/dist/process/process-contracts.d.ts

@@ -18,10 +18,15 @@ export interface ManagedProcessRequest {
 }
 export type SupervisedProcessOutputMode = "bounded-capture" | "caller-drained";
 export interface SupervisedProcessRequest extends Omit<ManagedProcessRequest, "timeoutMs"> {
+    readonly recoveryIdentity?: "capture";
     readonly shutdownTimeoutMs?: number;
     readonly outputMode: SupervisedProcessOutputMode;
     readonly timeoutMs: number | null;
 }
+/** Live supervision without publishing an identity for later recovery. */
+export interface SupervisedProcessWithoutRecoveryRequest extends Omit<SupervisedProcessRequest, "recoveryIdentity"> {
+    readonly recoveryIdentity: "none";
+}
 export interface ManagedProcessResult {
     readonly cancelled: boolean;
     readonly error: Error | null;
@@ -43,9 +48,12 @@ export interface SupervisedProcessRecoveryIdentity {
     readonly processGroupId: number | null;
 }
 /** A live child handle plus the identity needed for later best-effort recovery. */
-export interface SupervisedProcessHandle {
-    readonly completion: Promise<ManagedProcessResult>;
+export interface SupervisedProcessHandle extends SupervisedProcessLiveHandle {
     readonly ready: Promise<SupervisedProcessReady>;
+}
+/** Controls the child through its live handle, without persisted recovery metadata. */
+export interface SupervisedProcessLiveHandle {
+    readonly completion: Promise<ManagedProcessResult>;
     readonly stderr: Readable;
     readonly stdin: Writable;
     readonly stdout: Readable;

package/dist/process/process-identity.js

@@ -1 +1 @@
-import{execFileSync as c}from"node:child_process";import a from"node:fs";import{DARWIN_PS_EXECUTABLE as d,HOST_POSIX_INSPECTION_ENVIRONMENT as l,requireWindowsHostPowerShellCommand as f}from"./host-inspection-command.js";import{formatWindowsKernelProcessIdentity as m,parseWindowsKernelProcessIdentity as p}from"./windows-process-identity.js";const w=3e3,I=16*1024,S=8e3;export function captureProcessCreationIdentity(e){const t=Number(e);if(!Number.isSafeInteger(t)||t<=0)return null;try{if(process.platform==="linux")return E(t);if(process.platform==="darwin")return T(t);if(process.platform==="win32")return P(t)}catch{return null}return null}export function processCreationIdentityMatches(e,t){return observeProcessCreationIdentity(e,t)==="matches"}export function observeProcessCreationIdentity(e,t,n={}){const r=Number(e);if(!Number.isSafeInteger(r)||r<=0||typeof t!="string"||t.length===0)return"unknown";const i=(n.captureIdentity??captureProcessCreationIdentity)(r);return i!==null?i===t?"matches":"different":(n.inspectLiveness??inspectProcessLiveness)(r)==="absent"?"different":"unknown"}export function parseWindowsProcessCreationIdentity(e){return p(e)}function E(e){return parseLinuxProcessCreationIdentity(e,a.readFileSync(`/proc/${e.toString()}/stat`,"utf8"))}export function parseLinuxProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Linux process stat identity requires a positive pid");const n=t.trim(),r=n.lastIndexOf(")"),i=n.indexOf(" ");if(r<0||i<1||Number(n.slice(0,i))!==e)throw new Error("Linux process stat identity is malformed");const o=n.slice(r+1).trim().split(/\s+/u)[19];if(!/^\d+$/u.test(o))throw new Error("Linux process stat start time is malformed");return`linux-proc-start:${o}`}function T(e){const t=runBoundedProcessIdentityQuery({args:["-p",e.toString(),"-o","pid=,lstart="],environment:l,executable:d,timeoutMs:w,windowsHide:!1});return parseDarwinProcessCreationIdentity(e,t)}export function parseDarwinProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Darwin process start identity requires a positive pid");const n=t.trim().replace(/\s+/gu," "),r=/^(\d+) ((?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?:[1-9]|[12]\d|3[01]) (?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d \d{4})$/u.exec(n);if(r===null||Number(r[1])!==e)throw new Error("Darwin process start identity is malformed");return`darwin-ps-start:${r[2]}`}function P(e){const t=f(),n=windowsProcessCreationIdentityScript(e),r=runBoundedProcessIdentityQuery({args:["-NoLogo","-NoProfile","-NonInteractive","-Command",n],environment:t.environment,executable:t.executable,timeoutMs:S,windowsHide:!0});if(!/^\d+$/u.test(r))throw new Error("Windows process creation identity is malformed");return m(r)}export function windowsProcessCreationIdentityScript(e){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Windows process creation identity script requires a positive pid");return`$ErrorActionPreference = "Stop"; $p = [Diagnostics.Process]::GetProcessById(${e.toString()}); try { $fileTime = [Int64]$p.StartTime.ToUniversalTime().ToFileTimeUtc(); if ($fileTime -le 0) { exit 3 }; [Console]::Write($fileTime.ToString([Globalization.CultureInfo]::InvariantCulture)) } finally { $p.Dispose() }`}export function runBoundedProcessIdentityQuery(e){if(!Number.isSafeInteger(e.timeoutMs)||e.timeoutMs<=0)throw new Error("Process identity query timeout must be a positive safe integer in milliseconds");return c(e.executable,[...e.args],{encoding:"utf8",env:e.environment,killSignal:"SIGKILL",maxBuffer:I,stdio:["ignore","pipe","ignore"],timeout:e.timeoutMs,windowsHide:e.windowsHide}).trim()}export function inspectProcessLiveness(e){try{return process.kill(e,0),"alive"}catch(t){return s(t,"ESRCH")?"absent":s(t,"EPERM")?"alive":"unknown"}}function s(e,t){return typeof e=="object"&&e!==null&&Reflect.get(e,"code")===t}
+import{execFileSync as a}from"node:child_process";import d from"node:fs";import{DARWIN_PS_EXECUTABLE as l,HOST_POSIX_INSPECTION_ENVIRONMENT as f,requireWindowsHostPowerShellCommand as m}from"./host-inspection-command.js";import{formatWindowsKernelProcessIdentity as p,parseWindowsKernelProcessIdentity as w}from"./windows-process-identity.js";import{windowsOwnerExecutable as I}from"./windows-native.js";const S=3e3,E=16*1024,T=8e3;let o;export function captureProcessCreationIdentity(e){const t=Number(e);if(!Number.isSafeInteger(t)||t<=0)return null;if(t===process.pid&&o!==void 0)return o;try{let r=null;return process.platform==="linux"?r=y(t):process.platform==="darwin"?r=P(t):process.platform==="win32"&&(r=g(t)),t===process.pid&&r!==null&&(o=r),r}catch{return null}}export function processCreationIdentityMatches(e,t){return observeProcessCreationIdentity(e,t)==="matches"}export function observeProcessCreationIdentity(e,t,r={}){const n=Number(e);if(!Number.isSafeInteger(n)||n<=0||typeof t!="string"||t.length===0)return"unknown";const i=(r.captureIdentity??captureProcessCreationIdentity)(n);return i!==null?i===t?"matches":"different":(r.inspectLiveness??inspectProcessLiveness)(n)==="absent"?"different":"unknown"}export function parseWindowsProcessCreationIdentity(e){return w(e)}function y(e){return parseLinuxProcessCreationIdentity(e,d.readFileSync(`/proc/${e.toString()}/stat`,"utf8"))}export function parseLinuxProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Linux process stat identity requires a positive pid");const r=t.trim(),n=r.lastIndexOf(")"),i=r.indexOf(" ");if(n<0||i<1||Number(r.slice(0,i))!==e)throw new Error("Linux process stat identity is malformed");const s=r.slice(n+1).trim().split(/\s+/u)[19];if(!/^\d+$/u.test(s))throw new Error("Linux process stat start time is malformed");return`linux-proc-start:${s}`}function P(e){const t=runBoundedProcessIdentityQuery({args:["-p",e.toString(),"-o","pid=,lstart="],environment:f,executable:l,timeoutMs:S,windowsHide:!1});return parseDarwinProcessCreationIdentity(e,t)}export function parseDarwinProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Darwin process start identity requires a positive pid");const r=t.trim().replace(/\s+/gu," "),n=/^(\d+) ((?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?:[1-9]|[12]\d|3[01]) (?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d \d{4})$/u.exec(r);if(n===null||Number(n[1])!==e)throw new Error("Darwin process start identity is malformed");return`darwin-ps-start:${n[2]}`}function g(e){const t=runBoundedProcessIdentityQuery({args:["process-identity",e.toString()],environment:m().environment,executable:I(),timeoutMs:T,windowsHide:!0});if(!/^\d+$/u.test(t))throw new Error("Windows process creation identity is malformed");return p(t)}export function windowsProcessCreationIdentityScript(e){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Windows process creation identity script requires a positive pid");return`$ErrorActionPreference = "Stop"; $p = [Diagnostics.Process]::GetProcessById(${e.toString()}); try { $fileTime = [Int64]$p.StartTime.ToUniversalTime().ToFileTimeUtc(); if ($fileTime -le 0) { exit 3 }; [Console]::Write($fileTime.ToString([Globalization.CultureInfo]::InvariantCulture)) } finally { $p.Dispose() }`}export function runBoundedProcessIdentityQuery(e){if(!Number.isSafeInteger(e.timeoutMs)||e.timeoutMs<=0)throw new Error("Process identity query timeout must be a positive safe integer in milliseconds");return a(e.executable,[...e.args],{encoding:"utf8",env:e.environment,killSignal:"SIGKILL",maxBuffer:E,stdio:["ignore","pipe","ignore"],timeout:e.timeoutMs,windowsHide:e.windowsHide}).trim()}export function inspectProcessLiveness(e){try{return process.kill(e,0),"alive"}catch(t){return u(t,"ESRCH")?"absent":u(t,"EPERM")?"alive":"unknown"}}function u(e,t){return typeof e=="object"&&e!==null&&Reflect.get(e,"code")===t}

package/dist/process/process.d.ts

@@ -1,5 +1,5 @@
-import { type ManagedProcessRequest, type ManagedProcessResult, type SupervisedProcessHandle, type SupervisedProcessRequest } from "./process-contracts.js";
-export { type AttributedProcessLineageTerminationRequest, type ManagedProcessCancellationSignal, type ManagedProcessRequest, type ManagedProcessResult, type OwnedPosixProcessGroupTerminationRequest, type SupervisedProcessHandle, type SupervisedProcessOutputMode, type SupervisedProcessRecoveryIdentity, type SupervisedProcessReady, type SupervisedProcessRequest, } from "./process-contracts.js";
+import { type ManagedProcessRequest, type ManagedProcessResult, type SupervisedProcessHandle, type SupervisedProcessLiveHandle, type SupervisedProcessWithoutRecoveryRequest, type SupervisedProcessRequest } from "./process-contracts.js";
+export { type AttributedProcessLineageTerminationRequest, type ManagedProcessCancellationSignal, type ManagedProcessRequest, type ManagedProcessResult, type OwnedPosixProcessGroupTerminationRequest, type SupervisedProcessHandle, type SupervisedProcessLiveHandle, type SupervisedProcessWithoutRecoveryRequest, type SupervisedProcessOutputMode, type SupervisedProcessRecoveryIdentity, type SupervisedProcessReady, type SupervisedProcessRequest, } from "./process-contracts.js";
 export { terminateAttributedProcessLineage, terminateOwnedPosixProcessGroup } from "./recovery.js";
 export { cleanupExitedProcessGroup } from "./process-group.js";
 export declare function runManagedProcess(request: Readonly<ManagedProcessRequest>): Promise<ManagedProcessResult>;
@@ -8,4 +8,5 @@ export declare class ProcessExitedBeforeReadyError extends Error {
     readonly exitSignal: NodeJS.Signals | null;
     constructor(exitCode: number | null, exitSignal: NodeJS.Signals | null);
 }
+export declare function startSupervisedProcess(request: Readonly<SupervisedProcessWithoutRecoveryRequest>): SupervisedProcessLiveHandle;
 export declare function startSupervisedProcess(request: Readonly<SupervisedProcessRequest>): SupervisedProcessHandle;