@needle-tools/worker-launcher 0.0.0-stage → 1.0.0-alpha.9

package/src/manager.js

@@ -0,0 +1,112 @@
+import {mkdir,readFile,writeFile,rename} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {join} from 'node:path';
+import {executeDocker} from './docker-client.js';
+import {validWorkerTag} from './registry-access.js';
+
+const environments={staging:'https://cloud-staging.needle.tools/api',production:'https://cloud.needle.tools/api'};
+const ownerLabel='tools.needle.worker-launcher';
+const defaults={environment:'staging',workerId:'',count:1,cpus:2,memory:4};
+
+function validate(value,allowEmpty=false){
+ if(!environments[value.environment])throw new Error('Choose staging or production.');
+ if(typeof value.workerId!=='string'||!(allowEmpty&&value.workerId==='')&&!/^worker-[A-Za-z0-9_-]{1,120}$/.test(value.workerId))throw new Error('Enter the worker ID created in Cloud admin.');
+ for(const [field,min,max] of [['count',1,32],['cpus',1,128],['memory',1,512]])if(!Number.isInteger(value[field])||value[field]<min||value[field]>max)throw new Error(`${field} must be an integer from ${min} to ${max}.`);
+}
+
+export async function createManager({directory,docker=executeDocker,imageOverride=process.env.NEEDLE_WORKER_IMAGE,credentials,registry}={}){
+ await mkdir(directory,{recursive:true,mode:0o700});
+ const file=join(directory,'settings.json');
+ let settings={...defaults},managerId=randomUUID(),workerKey='',enabled=false,pinnedImage,credentialError,imageTag='';
+ let queue=Promise.resolve(),pending=0;
+ try{
+  const stored=JSON.parse(await readFile(file,'utf8'));
+  settings=Object.fromEntries(Object.keys(defaults).map(key=>[key,stored.settings?.[key]??defaults[key]]));
+  managerId=stored.managerId;enabled=stored.enabled===true;
+  if(!/^[a-f0-9-]{36}$/.test(managerId))throw new Error('Invalid launcher identity');
+  validate(settings,true);
+  if(stored.imageTag){if(!validWorkerTag(stored.imageTag))throw new Error('Invalid saved worker image version.');imageTag=stored.imageTag;}
+  if(stored.pinnedImage?.reference===image()&&/^sha256:[a-zA-Z0-9-]+$/.test(stored.pinnedImage.id))pinnedImage=stored.pinnedImage;
+ }catch(error){if(error.code!=='ENOENT')throw error;}
+ function identity(value=settings){return `${managerId}:${value.environment}:${value.workerId}`;}
+ function image(){return imageOverride||`container.needle.tools/needle-cloud/worker:${imageTag||settings.environment}`;}
+ async function pull(reference){if(registry?.status().configured)await registry.pull(reference);else await docker(['pull',reference],{timeout:180000});}
+ if(credentials&&settings.workerId){
+  try{workerKey=await credentials.get(identity());if(workerKey&&!/^ncw_[a-f0-9]{64}$/.test(workerKey))throw new Error('Stored worker key is invalid. Enter a new key from Cloud admin.');}
+  catch(error){workerKey='';credentialError=error.message;console.error('[worker-launcher] Protected key unavailable',{reason:credentialError});}
+ }
+ async function persist(){await writeFile(file+'.tmp',JSON.stringify({managerId,settings,imageTag,enabled,pinnedImage},null,2),{mode:0o600});await rename(file+'.tmp',file);}
+ await persist();
+ async function owned(){
+  const output=await docker(['ps','-a','--filter',`label=${ownerLabel}=${managerId}`,'--format','{{json .}}']);
+  return output?output.split(/\r?\n/).map(line=>{const value=JSON.parse(line);return {id:value.ID,name:value.Names,state:value.State,status:value.Status,image:value.Image};}):[];
+ }
+ async function exclusive(action){pending++;const operation=queue.then(action);queue=operation.catch(()=>{});try{return await operation;}finally{pending--;}}
+ async function reconcile(){return exclusive(async()=>{
+  if(!enabled)return;
+  const info=JSON.parse(await docker(['info','--format','{{json .}}']));
+  if(info.OSType!=='linux')throw new Error('Switch Docker to Linux containers.');
+  if(!['x86_64','amd64'].includes(info.Architecture))throw new Error('This launcher currently supports Linux amd64 workers. Apple Silicon support needs validation.');
+  const containers=await owned(),prefix=`needle-worker-${managerId.slice(0,8)}-`;
+  const slots=new Map();
+  for(const container of containers){
+   const slot=container.name?.startsWith(prefix)?Number(container.name.slice(prefix.length)):NaN;
+   if(!Number.isInteger(slot)||slot<1||slot>settings.count||slots.has(slot))throw new Error('An owned container does not match this configuration. Stop and remove the old containers before starting again.');
+   slots.set(slot,container);
+  }
+  const missing=Array.from({length:settings.count},(_,index)=>index+1).filter(slot=>!slots.has(slot));
+  if(missing.length){
+   if(!workerKey)throw new Error(credentialError||'Enter the worker key for this session or unlock the protected key store before creating containers.');
+   if(pinnedImage){try{await docker(['image','inspect','--format','{{.Id}}',pinnedImage.id]);}catch{if(pinnedImage.digest)await pull(pinnedImage.digest);else throw new Error('The pinned worker image is missing. Restore it or reset the worker configuration; automatic upgrades are disabled.');}}
+   else{
+    if(!imageOverride)await pull(image());
+    const id=await docker(['image','inspect','--format','{{.Id}}',image()]);
+    if(!/^sha256:[a-zA-Z0-9-]+$/.test(id))throw new Error('Docker did not return a valid image identity.');
+    let digest;
+    if(!imageOverride){const digests=await docker(['image','inspect','--format','{{range .RepoDigests}}{{println .}}{{end}}',id]);const repository=image().replace(/:[^/:]+$/,'');digest=digests.split(/\r?\n/).find(value=>value.startsWith(repository+'@sha256:')&&/^[^\s]+@sha256:[a-f0-9]{64}$/.test(value));}
+    pinnedImage={reference:image(),id,digest};await persist();
+   }
+  }
+  const environment={NEEDLE_SHARE_ENDPOINT:environments[settings.environment],NEEDLE_WORKER_ID:settings.workerId,NEEDLE_SHARE_API_KEY:workerKey,ENABLE_OPTIMIZATION:'true',ENABLE_HDRI_COMPRESSION:'true',ENABLE_AI_MATERIAL:'false',ENABLE_AI_3D_ASSET:'false',ENABLE_SPLAT_COMPRESSION:'false'};
+  // @todo 2026-11-03T12:53:12Z Add worker drain before replacing healthy containers for image upgrades; see plans/worker-orchestrator.md. Recovery only starts stopped or missing replicas.
+  for(let slot=1;slot<=settings.count&&enabled;slot++){
+   const existing=slots.get(slot);
+   if(existing){if(['running','restarting'].includes(existing.state))continue;if(existing.state==='paused')await docker(['unpause',existing.id]);else await docker(['start',existing.id]);continue;}
+   const args=['run','--detach','--init','--restart','unless-stopped','--label',`${ownerLabel}=${managerId}`,'--label',`tools.needle.worker-slot=${slot}`,'--name',prefix+slot,'--cpus',String(settings.cpus),'--memory',`${settings.memory}g`];
+   for(const key of Object.keys(environment))args.push('--env',key);
+   args.push(pinnedImage.id);await docker(args,{environment,timeout:30000});
+  }
+ });}
+ const manager={
+  shouldRun:()=>enabled,
+  async status(){
+   let containers=[],dockerStatus;
+   try{const info=JSON.parse(await docker(['info','--format','{{json .}}']));if(info.OSType!=='linux')throw new Error('Switch Docker to Linux containers.');dockerStatus={available:true,version:info.ServerVersion,architecture:info.Architecture};containers=await owned();}
+   catch(error){dockerStatus={available:false,error:error.message};}
+   return {settings:{...settings},imageTag,configured:!!workerKey,enabled,busy:pending>0,image:image(),endpoint:environments[settings.environment],docker:dockerStatus,containers,keyProtection:credentials?.kind||'Session only',credentialError};
+  },
+  async configure(value){return exclusive(async()=>{
+   validate(value);
+   if(value.imageTag!==undefined&&value.imageTag!==''&&!validWorkerTag(value.imageTag))throw new Error('Choose a valid worker image version.');
+   if(value.workerKey!==undefined&&value.workerKey!==''&&(typeof value.workerKey!=='string'||!/^ncw_[a-f0-9]{64}$/.test(value.workerKey)))throw new Error('Enter a valid enrolled worker key.');
+   if(enabled)throw new Error('Stop the worker before changing its configuration.');
+   if(settings.workerId&&(await owned()).length)throw new Error('Stop and remove this launcher?s containers before changing their configuration.');
+   const next=Object.fromEntries(Object.keys(defaults).map(key=>[key,value[key]]));
+   const changed=settings.environment!==next.environment||settings.workerId!==next.workerId,previousIdentity=identity();
+   const nextKey=value.workerKey||(changed?'':workerKey);
+   if(credentials&&value.workerKey)await credentials.set(identity(next),value.workerKey);
+   settings=next;imageTag=value.imageTag||'';workerKey=nextKey;credentialError=undefined;pinnedImage=undefined;await persist();
+   if(credentials&&changed)await credentials.remove(previousIdentity);
+  });},
+  async forget(){return exclusive(async()=>{if(enabled||(await owned()).length)throw Error('Stop and remove this worker’s containers before removing its configuration.');if(credentials)await credentials.remove(identity());workerKey='';settings={...defaults};imageTag='';pinnedImage=undefined;credentialError=undefined;await persist();});},
+  async enable(){return exclusive(async()=>{if(!workerKey)throw new Error(credentialError||'Enter the worker key for this session or unlock the protected key store before starting containers.');enabled=true;await persist();});},
+  async start(){await manager.enable();await reconcile();},
+  reconcile,
+  async stop(confirmed){
+   if(confirmed!==true)throw new Error('Confirm that stopping may interrupt active jobs.');
+   enabled=false;
+   return exclusive(async()=>{enabled=false;await persist();const containers=await owned();for(const container of containers)await docker(['rm','--force',container.id],{timeout:30000});});
+  },
+ };
+ return manager;
+}

package/src/registry-access.js

@@ -0,0 +1,80 @@
+// @ts-check
+import {readFile,writeFile,rename,mkdir} from 'node:fs/promises';
+import {join} from 'node:path';
+import {readWorkerMetadata} from './registry-metadata.js';
+import {pullRegistryImage} from './registry-pull.js';
+
+export const registryHost='container.needle.tools';
+export const workerRepository='needle-cloud/worker';
+/** @param {unknown} tag @returns {tag is string} */
+export function validWorkerTag(tag){return typeof tag==='string'&&/^[\w][\w.-]{0,127}$/.test(tag);}
+/** @typedef {{kind:string,get:(id:string)=>Promise<string>,set:(id:string,value:string)=>Promise<unknown>,remove:(id:string)=>Promise<unknown>}} Vault */
+/** @typedef {{username:string,password:string,serveraddress:string}} RegistryAuth */
+/** @param {{directory:string,credentials:Vault,request?:typeof fetch,pull?:(reference:string,auth:RegistryAuth)=>Promise<unknown>}} options */
+export async function createRegistryAccess({directory,credentials,request=fetch,pull=pullRegistryImage}){
+ const file=join(directory,'registry.json'),identity=`registry:${registryHost}`;
+ let userId='',busy=false;
+ try{const value=JSON.parse(await readFile(file,'utf8'));if(typeof value.userId==='string'&&/^[A-Za-z0-9_-]{1,256}$/.test(value.userId))userId=value.userId;}
+ catch(error){if(!(error instanceof Error&&'code' in error&&error.code==='ENOENT'))throw new Error('Could not read registry settings.');}
+ /** @param {unknown} id @param {unknown} key @returns {RegistryAuth} */
+ function validate(id,key){
+  if(typeof id!=='string'||!/^[A-Za-z0-9_-]{1,256}$/.test(id))throw new Error('Enter your Logto user ID from the registry account menu.');
+  if(typeof key!=='string'||!key.length||key.length>4096||/[\s\x00-\x1f\x7f]/.test(key))throw new Error('Enter a valid Zot API key.');
+  return {username:id,password:key,serveraddress:registryHost};
+ }
+ async function auth(){
+  if(!userId)throw new Error('Connect your registry account in Launcher settings first.');
+  try{
+   const protectedValue=await credentials.get(identity);
+   if(!protectedValue.startsWith('ncr_'))throw new Error();
+   const value=JSON.parse(Buffer.from(protectedValue.slice(4),'base64url').toString('utf8'));
+   if(value.username!==userId)throw new Error();
+   return validate(value.username,value.password);
+  }catch{throw new Error('Registry credentials are unavailable. Unlock the OS credential store or reconnect in Settings.');}
+ }
+ /** @param {RegistryAuth} credential */
+ async function tags(credential){
+  const endpoint=`https://${registryHost}/v2/${workerRepository}/tags/list`;
+  let next=endpoint+'?n=100';const found=new Set();
+  for(let page=0;next&&page<20;page++){
+   let response;
+   try{response=await request(next,{headers:{Authorization:'Basic '+Buffer.from(credential.username+':'+credential.password).toString('base64'),Accept:'application/json'},redirect:'error',signal:AbortSignal.timeout(15000)});}
+   catch{throw new Error('Could not reach the registry securely. Check your connection and try again.');}
+   if(!response.ok){await response.body?.cancel();throw new Error(response.status===401?'Registry login failed. Check your user ID and Zot API key.':response.status===403||response.status===404?'Read access to the worker repository was denied or it has no published versions.':'Registry is unavailable. Please try again.');}
+   let raw='';
+   if(!response.body)throw new Error('Registry returned an empty response.');
+   const reader=response.body.getReader();let size=0;
+   try{const decoder=new TextDecoder();for(;;){const {done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>1024*1024)throw new Error('Registry response is too large.');raw+=decoder.decode(value,{stream:true});}raw+=decoder.decode();}
+   finally{await reader.cancel().catch(()=>{});}
+   let value;try{value=JSON.parse(raw);}catch{throw new Error('Registry returned invalid version data.');}
+   if(value?.name!==workerRepository||value.tags!==null&&(!Array.isArray(value.tags)||!value.tags.every(validWorkerTag)))throw new Error('Registry returned invalid version data.');
+   for(const tag of value.tags??[])found.add(tag);
+   const link=response.headers.get('link');
+   if(!link){next='';continue;}
+   const match=link.match(/^<([^>]+)>;\s*rel="?next"?$/);
+   if(!match)throw new Error('Registry returned unsupported pagination.');
+   const target=new URL(match[1],endpoint);
+   if(target.origin!==`https://${registryHost}`||target.pathname!==new URL(endpoint).pathname||target.username||target.password||target.hash)throw new Error('Registry returned unsafe pagination.');
+   next=target.href;
+  }
+  if(next)throw new Error('Too many worker versions to list.');
+  return {repository:workerRepository,tags:[...found].sort()};
+ }
+ /** @param {()=>Promise<unknown>} action */
+ async function exclusive(action){if(busy)throw new Error('A registry operation is already running.');busy=true;try{return await action();}finally{busy=false;}}
+ /** @param {string} id */
+ async function persist(id){await mkdir(directory,{recursive:true,mode:0o700});await writeFile(file+'.tmp',JSON.stringify({userId:id}),{mode:0o600});await rename(file+'.tmp',file);userId=id;}
+ return {
+  status:()=>({host:registryHost,repository:workerRepository,userId,configured:!!userId,protection:credentials.kind,busy}),
+  /** @param {{userId?:unknown,apiKey?:unknown}} value */
+  connect:async value=>exclusive(async()=>{const credential=validate(value.userId,value.apiKey);await tags(credential);try{await credentials.set(identity,'ncr_'+Buffer.from(JSON.stringify(credential)).toString('base64url'));}catch{throw new Error('Could not save registry credentials in the OS vault. Unlock it and try again.');}await persist(credential.username);}),
+  forget:async()=>exclusive(async()=>{await credentials.remove(identity);await persist('');}),
+  list:async()=>tags(await auth()),
+  /** @param {unknown} tag */
+  details:async tag=>{if(!validWorkerTag(tag))throw Error('Choose a valid worker version.');return readWorkerMetadata(tag,await auth(),request);},
+  /** @param {unknown} tag */
+  install:async tag=>exclusive(async()=>{if(!validWorkerTag(tag))throw new Error('Choose a valid worker version.');const credential=await auth();if(!(await tags(credential)).tags.includes(tag))throw new Error('This worker version is unavailable for your account.');await pull(`${registryHost}/${workerRepository}:${tag}`,credential);}),
+  /** @param {string} reference */
+  pull:async reference=>{if(!reference.startsWith(`${registryHost}/${workerRepository}:`)&&!new RegExp(`^${registryHost.replaceAll('.','\\.')}/${workerRepository}@sha256:[a-f0-9]{64}$`).test(reference))throw new Error('Only the configured worker repository can be pulled.');await pull(reference,await auth());}
+ };
+}

package/src/registry-metadata.js

@@ -0,0 +1,14 @@
+// Metadata is read only from the fixed worker repository; redirects never receive credentials.
+export async function readWorkerMetadata(tag,credential,request=fetch){
+ const base='https://container.needle.tools/v2/needle-cloud/worker';
+ const headers={Authorization:'Basic '+Buffer.from(credential.username+':'+credential.password).toString('base64'),Accept:'application/vnd.oci.image.index.v1+json, application/vnd.oci.image.manifest.v1+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.docker.distribution.manifest.v2+json'};
+ async function json(path){const response=await request(base+path,{headers,redirect:'error',signal:AbortSignal.timeout(15000)});if(!response.ok){await response.body?.cancel();throw Error('Could not read image metadata (HTTP '+response.status+').');}if(!response.body)throw Error('Image metadata is empty.');const reader=response.body.getReader();let size=0,raw='';try{const decoder=new TextDecoder();for(;;){const {done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>4*1024*1024)throw Error('Image metadata is too large.');raw+=decoder.decode(value,{stream:true});}raw+=decoder.decode();return JSON.parse(raw);}finally{await reader.cancel().catch(()=>{});}}
+ const digest=value=>typeof value==='string'&&/^sha256:[a-f0-9]{64}$/.test(value);
+ let manifest=await json('/manifests/'+encodeURIComponent(tag));
+ const annotations={...manifest.annotations};
+ if(Array.isArray(manifest.manifests)){const child=manifest.manifests.find(item=>item.platform?.os==='linux'&&item.platform?.architecture==='amd64');if(!child||!digest(child.digest))throw Error('No Linux amd64 runtime metadata is available.');manifest=await json('/manifests/'+child.digest);}
+ if(!digest(manifest.config?.digest))throw Error('Image config metadata is unavailable.');
+ const config=await json('/blobs/'+manifest.config.digest),labels={...config.config?.Labels,...annotations,...manifest.annotations};
+ const text=value=>typeof value==='string'?value.replace(/[\x00-\x1f\x7f]/g,'').slice(0,256):'';
+ return {title:text(labels['org.opencontainers.image.title']),version:text(labels['org.opencontainers.image.version']),revision:text(labels['org.opencontainers.image.revision']),created:text(labels['org.opencontainers.image.created']||config.created),platform:[text(config.os),text(config.architecture)].filter(Boolean).join('/')};
+}

package/src/registry-pull.js

@@ -0,0 +1,29 @@
+// @ts-check
+import {request} from 'node:http';
+import {executeDocker} from './docker-client.js';
+
+/** Pull through the local Engine API; no registry secret enters argv, files or container environments.
+ * @param {string} reference
+ * @param {import('./registry-access.js').RegistryAuth} auth
+ * @param {{execute?:(args:string[])=>Promise<string>,environment?:NodeJS.ProcessEnv}} [options]
+ * @returns {Promise<void>}
+ */
+export async function pullRegistryImage(reference,auth,{execute=executeDocker,environment=process.env}={}){
+ const endpoint=environment.DOCKER_CONTEXT?JSON.parse(await execute(['context','inspect','--format','{{json .Endpoints.docker}}']))?.Host:environment.DOCKER_HOST||JSON.parse(await execute(['context','inspect','--format','{{json .Endpoints.docker}}']))?.Host;
+ if(typeof endpoint!=='string'||!endpoint.startsWith('unix://')&&!endpoint.startsWith('npipe:////./pipe/'))throw new Error('Registry credentials require a local Docker socket. Remote Docker contexts are not supported.');
+ const socketPath=endpoint.startsWith('unix://')?endpoint.slice(7):'\\\\.\\pipe\\'+endpoint.slice('npipe:////./pipe/'.length);
+ const version=(await execute(['version','--format','{{.Server.APIVersion}}'])).trim();
+ if(!/^1\.\d+$/.test(version))throw new Error('Could not determine the Docker Engine API version.');
+ await new Promise((resolve,reject)=>{
+  let complete=false,buffer='';
+  const fail=()=>{if(!complete){complete=true;req.destroy();reject(new Error('Worker image download failed. Check Docker, registry access and available disk space.'));}};
+  const req=request({socketPath,path:`/v${version}/images/create?${new URLSearchParams({fromImage:reference,platform:'linux/amd64'})}`,method:'POST',headers:{'X-Registry-Auth':Buffer.from(JSON.stringify(auth)).toString('base64url'),'Content-Length':0}},res=>{
+   if(res.statusCode!==200){res.resume();fail();return;}
+   res.setEncoding('utf8');
+   res.on('data',chunk=>{buffer+=chunk;if(buffer.length>1024*1024){fail();return;}let end;while((end=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,end);buffer=buffer.slice(end+1);if(line.trim())try{if(JSON.parse(line).error)fail();}catch{fail();}}});
+   res.on('error',fail);res.on('aborted',fail);
+   res.on('end',()=>{if(buffer.trim())try{if(JSON.parse(buffer).error)fail();}catch{fail();}if(!complete){complete=true;resolve(undefined);}});
+  });
+  const timer=setTimeout(fail,180000);req.on('close',()=>clearTimeout(timer));req.on('error',fail);req.end();
+ });
+}

package/src/server.js

@@ -0,0 +1,47 @@
+import {createServer} from 'node:http';
+import {randomBytes,timingSafeEqual} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+
+const assets=new Map([['/',['index.html','text/html']],['/setup',['index.html','text/html']],['/settings',['index.html','text/html']],['/app.js',['app.js','text/javascript']],['/app.css',['app.css','text/css']],['/needle-logo.svg',['needle-logo.svg','image/svg+xml']],['/favicon.ico',['favicon.ico','image/x-icon']],['/favicon.svg',['favicon.svg','image/svg+xml']],...['workspace-tokens.css','workspace-controls.css'].map(name=>['/'+name,[name,'text/css']])]);
+export function createLauncherServer(manager,{autostart,supervisor,registry}={}){
+ const session=randomBytes(32).toString('hex');
+ return createServer(async(req,res)=>{
+  res.setHeader('Cache-Control','no-store');res.setHeader('X-Content-Type-Options','nosniff');res.setHeader('Referrer-Policy','no-referrer');
+  res.setHeader('Content-Security-Policy',"default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'");
+  const port=req.socket.localPort;
+  if(![`127.0.0.1:${port}`,`localhost:${port}`].includes(req.headers.host)){res.writeHead(403).end('Invalid localhost host');return;}
+  const origin=`http://${req.headers.host}`;
+  const send=(status,value)=>{res.writeHead(status,{'Content-Type':'application/json'}).end(JSON.stringify(value));};
+  try{
+   const route=new URL(req.url,origin).pathname;
+   if(req.method==='GET'&&assets.has(route)){
+    const [file,type]=assets.get(route);const body=await readFile(new URL('../public/'+file,import.meta.url));
+    if(['/', '/setup', '/settings'].includes(route))res.setHeader('Set-Cookie',`needle_launcher=${session}; HttpOnly; SameSite=Strict; Path=/`);
+    res.writeHead(200,{'Content-Type':type+'; charset=utf-8'}).end(body);return;
+   }
+   if(req.method==='GET'&&route==='/api/session'&&req.headers['x-launcher-session']==='refresh'&&req.headers['sec-fetch-site']==='same-origin'){res.setHeader('Set-Cookie',`needle_launcher=${session}; HttpOnly; SameSite=Strict; Path=/`);send(200,{ok:true});return;}
+   const cookie=req.headers.cookie?.split(';').map(value=>value.trim()).find(value=>value.startsWith('needle_launcher='))?.slice('needle_launcher='.length)||'';
+   if(cookie.length!==session.length||!timingSafeEqual(Buffer.from(cookie),Buffer.from(session))){send(401,{error:'Open the launcher page to start a local session.'});return;}
+   if(req.method==='GET'&&route==='/api/status'){const status=await manager.status();if(supervisor)status.supervision=supervisor.status();send(200,status);return;}
+   if(req.method==='GET'&&route==='/api/autostart'&&autostart){send(200,await autostart.status());return;}
+   if(req.method==='GET'&&route==='/api/registry'&&registry){send(200,registry.status());return;}
+   if(req.method!=='POST'||req.headers.origin!==origin){send(403,{error:'Only same-origin launcher requests are allowed.'});return;}
+   if(!req.headers['content-type']?.startsWith('application/json')){send(415,{error:'Use JSON requests.'});return;}
+   let data='';for await(const chunk of req){data+=chunk;if(Buffer.byteLength(data)>16384){send(413,{error:'Request too large.'});return;}}
+   let body;try{body=JSON.parse(data);}catch{send(400,{error:'Invalid JSON.'});return;}
+   if(!body||typeof body!=='object'||Array.isArray(body)){send(400,{error:'Expected settings object.'});return;}
+   if(route==='/api/settings')await manager.configure(body);
+   else if(route==='/api/registry/connect'&&registry)await registry.connect(body);
+   else if(route==='/api/registry/forget'&&registry)await registry.forget();
+   else if(route==='/api/registry/list'&&registry){send(200,await registry.list());return;}
+   else if(route==='/api/registry/details'&&registry){send(200,await registry.details(body.tag));return;}
+   else if(route==='/api/registry/install'&&registry)await registry.install(body.tag);
+   else if(route==='/api/autostart'&&autostart){send(200,await autostart.set(body.enabled));return;}
+   else if(route==='/api/remove')await manager.remove(body.profileId,body.confirmed);
+   else if(route==='/api/start')await (supervisor||manager).start(body.profileId);
+   else if(route==='/api/stop')await (supervisor||manager).stop(body.confirmed,body.profileId);
+   else{send(404,{error:'Unknown launcher action.'});return;}
+   send(200,{ok:true});
+  }catch(error){console.error('[worker-launcher] Request failed',{path:req.url?.split('?')[0],reason:error.code||error.name});send(400,{error:error.message});}
+ });
+}

package/src/supervisor.js

@@ -0,0 +1,21 @@
+export function createSupervisor({manager,readiness,now=Date.now,interval=10000}){
+ let state={phase:'paused',error:undefined,retryAt:0},failures=0,active=false,timer,closed=false,generation=0;
+ function update(next){const changed=state.phase!==next.phase||state.error!==next.error;state=next;if(changed)console.log('[worker-launcher] Supervisor state',{phase:state.phase,...(state.error?{reason:state.error}:{})});}
+ const api={
+  status:()=>({...state,docker:readiness.status?.()}),
+  async tick(){
+   if(active||closed)return;
+   if(!manager.shouldRun()){update({phase:'paused',retryAt:0});return;}
+   if(now()<state.retryAt)return;
+   active=true;const run=generation;
+   try{update({phase:'checking',retryAt:0});await readiness.ensure();if(run!==generation||!manager.shouldRun())return;update({phase:'recovering',retryAt:0});await manager.reconcile();if(run===generation&&manager.shouldRun()){failures=0;update({phase:'running',retryAt:0});}}
+   catch(error){if(run===generation){failures++;update({phase:'error',error:error.message,retryAt:now()+Math.min(300000,10000*2**Math.min(failures-1,5))});}}
+   finally{active=false;}
+  },
+  async start(){await manager.enable();generation++;state.retryAt=0;void api.tick();},
+  async stop(confirmed){if(confirmed!==true)throw new Error('Confirm that stopping may interrupt active jobs.');generation++;await manager.stop(true);failures=0;update({phase:'paused',retryAt:0});},
+  startLoop(){closed=false;void api.tick();timer=setInterval(()=>void api.tick(),interval);timer.unref();},
+  close(){closed=true;generation++;clearInterval(timer);},
+ };
+ return api;
+}