row 197 r8 proof candidate: Herb's c45ddeb6b 37 paths on this commit's parent (not for landing)

This commit is contained in:
jason.woltje committed 2026-10-21 07:38:34 -05:00
1 parent 6d5545d442
commit 6c31874e54
37 files changed
+2183 -35

No files matched your search

+97
View File
@@ -0,0 +1,97 @@
# Gate lanes
This tooling is for Sage's granted test gates on dragon-lin. It does not grant
itself a slot. A grant reference is an audit field, not an authentication token.
Until Sage adopts these lanes, the existing shared-slot procedure still applies.
Ask Sage with the lane, candidate SHA and exact command. Get a separate grant
for image preparation, suites, and the whole-slot paired proof. New state is
`/mnt/storage/scratch/mosaic-gate-lanes`. Old slot files are untouched.
Invoke the entry from the builder or canonical repository. The --checkout target
must be a separate clean scratch clone containing identical tooling source:
```bash
scripts/testing/gate-lane.sh run --lane a --candidate FULL_SHA \
--checkout /mnt/storage/scratch/ROW-RUN/wt \
--out /mnt/storage/scratch/ROW-RUN/out --grant SAGE_MESSAGE_ID \
--image-receipt /mnt/storage/scratch/PREP/image-receipt.json
```
Each run creates a private root like `/mnt/storage/scratch/ga-ABCDEF` (30 bytes).
An explicit `--temp-root` must already be private, outside `/tmp`, and no longer
than 30 UTF-8 bytes after resolving symlinks. The sandbox's own `/tmp` and HOME
are unchanged. Host HOME stays real. A listener covering loopback port 9, an
unsafe privileged-port threshold or unreadable host inventory refuses startup.
Lane a leases ports 61000..61127, lane b 61128..61255. Refuse any band overlapping
the host's current ephemeral range or a live listener. Port-0 fixtures with a
held server keep using port 0. Never replace the literal dead Board :9 URLs.
Two Node test files run per lane, including nested shell-suite Node runners.
```bash
scripts/testing/gate-lane.sh status
scripts/testing/gate-lane.sh recover --run-id RUN_NONCE --grant SAGE_MESSAGE_ID
```
Status reports each lane, the image lock, unfinished receipts and unmanaged
test/landing/build processes as LEGACY BUSY. It prints no command lines or
environment values. A dead owner with an unfinished receipt is quarantined even
when flock is free. Recovery takes both lanes and the exclusive image lock.
Unknown process-group, scope or Docker ownership refuses recovery. Do not remove
lock files, old receipts, or another run's resources to clear a refusal.
An image receipt records exact COPY input hashes/modes, image ID, release tag,
base digest and platform. Both concurrent candidates must match those files and
that same image ID. Rebuilding identical files is not equivalent. Warm gates
refuse implicit Docker builds/pulls and recheck the ID at each step and the end.
External same-uid commands can ignore these locks. Sage must exclude other
builders; this is test coordination, not a security boundary against that uid.
Only under an explicit image-build grant:
```bash
scripts/testing/gate-lane.sh prepare-image --lane a --candidate FULL_SHA \
--checkout /mnt/storage/scratch/ROW-PREP/wt \
--out /mnt/storage/scratch/ROW-PREP/out --grant SAGE_MESSAGE_ID
```
Preparation holds both lanes and the exclusive image lock. Its build log,
receipt, count and wall time are separate from warm gate timings. The current
Containerfile uses a mutable FROM tag and apt indexes. A missing base digest
refuses provenance publication. No credential file is copied or printed.
Run records are immutable JSON files published by link after fsync. Every step
has a log, UTC/monotonic times, exit code, pass/fail/skip counts and log hash.
The first failed step stops the gate. Cleanup touches only exact project labels,
recorded process identities and fixture paths. A process leak fails the gate
even when cleanup succeeds. Failed logs and temp roots remain for diagnosis.
A cleanup failure leaves the lane quarantined. GATE_PASSED requires all steps
and cleanup. Required prerequisite skips fail the run; optional skips remain
visible and require acceptance review.
Home metadata is evidence only. Assert only on entries attributable to this
run's nonce or fixture paths. Other sessions normally change ~/.claude, ~/.pi
and ~/.cache, so there is no global unchanged-home assertion.
The row 197 acceptance packet is `agents/herb/work/queue-197/`: two candidate
solo baselines followed by three overlapping pairs, lane assignment swapped in
pair two. Keep later paired results after adoption. Six green gates establish
the initial acceptance bar, not a reliable estimate of rare flakes.
The preflight unit fixture uses the canonical checkout's existing node_modules
at `/mnt/storage/src/mosaic-stack/node_modules` through the required plain
symlink. It does not install dependencies. Unit run roots use the `gt-` prefix;
real lane roots use `ga-` or `gb-`. Resource helper tests inside a lane lease only
that lane's band through MOSAIC_GATE_STATE, including their child test files.
The exhaustion probe temporarily narrows its process-local band to a port it
already leased, so it never reserves the whole shared band.
`closed` call-site options are accepted for compatibility; every dynamic lease
reserves an unbound endpoint. Listener fixtures decide when to bind and close.
Fixture child caches put TMPDIR under `tmp/` next to `jiti/` and `cache/`.
Outside a lane, the resource helper file uses lane a with the shared default
state `/mnt/storage/scratch/mosaic-gate-lanes`. It leaves stable lock files in
place. A single-file run therefore respects a live lane-a gate's closed leases.
Its unrelated-session probe bounds both polling children at five seconds.
+227
View File
@@ -0,0 +1,227 @@
import { createHash } from 'node:crypto';
import { realpathSync, existsSync, statSync, readdirSync } from 'node:fs';
import { join, resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { execFileSync } from 'node:child_process';
import { shortRoot, checkHost, hostFacts, refuse, within, SCRATCH, identity } from './lane-state.mjs';
const BUILDER=resolve(dirname(fileURLToPath(import.meta.url)),'../..');
const git=(root,...args)=>execFileSync('git',['-C',root,...args],{encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim();
export function validateRun(o){
if(!['a','b'].includes(o.lane))refuse('invalid lane');
if(typeof o.grant!=='string'||!o.grant.trim())refuse('missing grant reference');
for(const key of ['checkout','out','stateRoot'])if(typeof o[key]!=='string'||!o[key])refuse(`missing ${key}`);
const tempRoot=shortRoot(o.tempRoot);
const checkout=realpathSync(o.checkout);
if(checkout===BUILDER||checkout==='/mnt/storage/src/mosaic-stack'||!within(SCRATCH,checkout))refuse('canonical or builder checkout');
if(!/^[a-f0-9]{40}$/.test(o.candidate)||git(checkout,'rev-parse','HEAD')!==o.candidate)refuse('wrong candidate SHA');
const changed=git(checkout,'status','--porcelain','--untracked-files=normal').split('\n').filter(x=>x&&x!=='?? node_modules');
if(changed.length)refuse('dirty checkout');
if(!existsSync(join(checkout,'node_modules'))||!statSync(join(checkout,'node_modules')).isDirectory())refuse('missing node_modules');
const out=resolve(o.out);if(existsSync(out))refuse('output already exists');
if(!within(dirname(checkout),out)||!within(SCRATCH,realpathSync(dirname(out))))refuse('output escapes run scratch');
const stateRoot=resolve(o.stateRoot);if(!within(SCRATCH,stateRoot))refuse('state outside scratch');
checkHost(o.lane,o.hostFacts??hostFacts());
return {...o,tempRoot,checkout,out,stateRoot};
}
export function validateTooling(checkout){
for(const name of readdirSync(join(BUILDER,'scripts/testing')).filter(n=>/\.(mjs|sh)$/.test(n))){
const candidate=join(checkout,'scripts/testing',name),launcher=join(BUILDER,'scripts/testing',name);
if(!existsSync(candidate)||!readFileSync(candidate).equals(readFileSync(launcher)))refuse('candidate tooling differs from launcher');
}
}
export function discoverSteps(checkout,concurrency=2){
if(concurrency!==2)refuse('test concurrency must be 2');
const steps=[];
for(const p of readdirSync(join(checkout,'packages')).sort())if(p!=='queue'&&existsSync(join(checkout,'packages',p,'tests'))&&statSync(join(checkout,'packages',p,'tests')).isDirectory())steps.push({name:`pkg-${p}`,cwd:join(checkout,'packages',p),argv:['node','--test','--test-concurrency=2',...readdirSync(join(checkout,'packages',p,'tests')).filter(n=>n.endsWith('.test.mjs')).sort().map(n=>`tests/${n}`)]});
for(const f of readdirSync(join(checkout,'scripts')).sort())if(/^test-.+\.sh$/.test(f)&&statSync(join(checkout,'scripts',f)).isFile())steps.push({name:`script-${f.slice(5,-3)}`,cwd:checkout,argv:['bash',`scripts/${f}`]});
return steps;
}
export async function executeSteps(steps,{out,env,record,onChild=()=>{},signal}){
const {openSync,closeSync}=await import('node:fs');const {spawn}=await import('node:child_process');
for(const step of steps){
if(signal?.aborted)return {rc:130};
const begin=performance.now(),startMs=Date.now();const fd=openSync(join(out,`${step.name}.log`),'wx',0o600);
// Keep the supervisor private while matching the legacy test environment.
const child=spawn('/bin/bash',['-c','umask 022; exec "$@"','gate-step',...step.argv],{cwd:step.cwd,env,detached:true,stdio:['ignore',fd,fd]});closeSync(fd);
onChild(child);record({kind:'child',group:child.pid,owner:identity(child.pid)});
let escalation;
const abort=()=>{try{process.kill(-child.pid,'SIGTERM');}catch{};escalation=setTimeout(()=>{try{process.kill(-child.pid,'SIGKILL');}catch{}},3000);escalation.unref();};
signal?.addEventListener('abort',abort,{once:true});
const rc=await new Promise(resolve=>{child.once('error',()=>resolve(127));child.once('close',(code,sig)=>resolve(signal?.aborted?130:(code??(sig?128:1))));});
clearTimeout(escalation);signal?.removeEventListener('abort',abort);onChild(null);
const bytes=readFileSync(join(out,`${step.name}.log`)),text=bytes.toString('utf8');
const counts={};for(const name of ['pass','fail','skipped']){const m=text.match(new RegExp('^(?:ℹ |# )'+name+' (\\d+)','m'));if(m)counts[name]=Number(m[1]);}
if(counts.pass===undefined){const summaries=[...text.matchAll(/(\d+) passed, (\d+) failed/g)];const last=summaries.at(-1);if(last){counts.pass=Number(last[1]);counts.fail=Number(last[2]);}}
const requiredSkips=text.split('\n').filter(line=>/^skip\b/i.test(line)&&/(docker|daemon|sandbox|systemd|credential)/i.test(line));
record({kind:'step',name:step.name,startMs,endMs:Date.now(),wallMs:performance.now()-begin,rc,counts,requiredSkips,logSha256:createHash('sha256').update(bytes).digest('hex')});
if(rc!==0||requiredSkips.length)return {rc:rc||2};
}
return {rc:0};
}
export async function executePinnedSteps(steps,options,{receipt,checkout,inspect,afterStep=()=>{}}){
for(const step of steps){
verifyImage(receipt,checkout,inspect);
const result=await executeSteps([step],options);afterStep(step);
if(result.rc){verifyImage(receipt,checkout,inspect);return {...result,imageBuilds:0};}
}
verifyImage(receipt,checkout,inspect);return {rc:0,imageBuilds:0};
}
import { mkdirSync, lstatSync, fstatSync, mkdtempSync, writeFileSync, readFileSync, openSync, readlinkSync, rmdirSync } from 'node:fs';
import { pathToFileURL } from 'node:url';
import { spawnSync } from 'node:child_process';
import { status, appendRecord, runRecords, processInventory, sameProcess, nonce } from './lane-state.mjs';
import { verifyImage, imageFingerprint, inspectImage, prepareImage } from './lane-image.mjs';
import { cleanupProject } from './lane-docker.mjs';
import { homeMetadata, attributeEntries, socketInventory } from './lane-evidence.mjs';
function options(argv){
const result={verb:'run',stateRoot:'/mnt/storage/scratch/mosaic-gate-lanes',lane:'a',exclusive:false};
const names={'--state-root':'stateRoot','--lane':'lane','--candidate':'candidate','--checkout':'checkout','--out':'out','--temp-root':'tempRoot','--grant':'grant','--image-receipt':'imageReceipt','--run-id':'runId'};
const args=[...argv];if(args[0]&&!args[0].startsWith('--'))result.verb=args.shift();
if(!['run','status','recover','prepare-image','lock-dir'].includes(result.verb))refuse('unknown verb');
while(args.length){const key=args.shift();if(key==='--exclusive'){result.exclusive=true;continue;}if(!names[key]||!args.length)refuse('invalid or missing option');result[names[key]]=args.shift();}
return result;
}
function stateDirectory(path,create=false){
const root=resolve(path);if(!within(SCRATCH,root)||root===SCRATCH)refuse('state must be private scratch');
if(create){const parent=realpathSync(dirname(root));if(!within(SCRATCH,parent))refuse('state parent escapes scratch');mkdirSync(root,{recursive:true,mode:0o700});}
if(existsSync(root)){const st=lstatSync(root);if(st.isSymbolicLink()||!st.isDirectory()||st.uid!==process.getuid()||(st.mode&0o077))refuse('state is not a private owned directory');
for(const n of ['a.lock','b.lock','image.lock'])if(existsSync(join(root,n))&&!lstatSync(join(root,n)).isFile())refuse('lock is not an ordinary file');
}
return root;
}
export function verifyLocks(o){
for(const [fd,name] of o.exclusive?[[3,'a.lock'],[4,'b.lock'],[5,'image.lock']]:[[3,`${o.lane}.lock`],[5,'image.lock']]){
let opened,path;try{opened=fstatSync(fd);path=lstatSync(join(o.stateRoot,name));}catch{refuse('lock descriptors missing');}
if(!opened.isFile()||!path.isFile()||opened.ino!==path.ino||opened.dev!==path.dev||path.uid!==process.getuid())refuse('lock file replaced');
// A separate open must fail while our shared/exclusive lock is held.
const r=spawnSync('flock',['-n','-x',join(o.stateRoot,name),'true']);if(r.status!==1)refuse('lock descriptor is not locked');
}
}
export function activeConflicts(o,observations={}){
const current=status(o.stateRoot,{...observations,ignoreLocks:o.exclusive?['a','b','image']:[o.lane,'image']});
if(current.legacy.length)refuse('LEGACY BUSY: unmanaged gate, test or Docker process');
for(const lane of o.exclusive?['a','b']:[o.lane])if(current[lane].state!=='CLEAR')refuse(`${lane} ${current[lane].state}`);
for(const r of runRecords(o.stateRoot)){const start=r.records.find(e=>e.kind==='start');if(!r.records.some(e=>['terminal','recovered'].includes(e.kind)&&e.clean)&&start?.checkout===o.checkout)refuse('checkout already owned');}
}
export function cleanEnv(o,run,docker){
const kept=['PATH','HOME','USER','LOGNAME','SHELL','LANG','LC_ALL','LC_CTYPE','TZ','TERM','XDG_RUNTIME_DIR','DBUS_SESSION_BUS_ADDRESS','DOCKER_HOST','CHROMIUM'];
const env=Object.fromEntries(kept.filter(k=>typeof process.env[k]==='string').map(k=>[k,process.env[k]]));
Object.assign(env,{TMPDIR:o.tempRoot,TMP:o.tempRoot,TEMP:o.tempRoot,MOSAIC_GATE_LANE:o.lane,MOSAIC_GATE_STATE:o.stateRoot,MOSAIC_TEST_CONCURRENCY:'2',COMPOSE_PROJECT_NAME:run.project,JITI_FS_CACHE:join(o.tempRoot,'jiti'),XDG_CACHE_HOME:join(o.tempRoot,'cache'),MOSAIC_CONFIG:join(o.tempRoot,'missing-config.json'),MOSAIC_GATE_DOCKER_RECORD:join(o.out,'docker.json')});
env.PATH=`${join(o.out,'bin')}:${env.PATH??'/usr/bin:/bin'}`;
return env;
}
function fixtureProcesses(run){
const all=processInventory(),ancestors=new Set([process.pid]);let parent=process.pid;
while(parent){const p=all.find(p=>p.pid===parent);if(!p||ancestors.has(p.ppid))break;ancestors.add(p.ppid);parent=p.ppid;}
return all.filter(p=>{
if(ancestors.has(p.pid)||p.state==='Z')return false;
let cwd;try{cwd=readlinkSync(`/proc/${p.pid}/cwd`);}catch{}
return p.argv.some(a=>typeof a==='string'&&(a===run.tempRoot||a.startsWith(run.tempRoot+'/')))||cwd&&(within(run.tempRoot,cwd)||run.checkout&&within(run.checkout,cwd));
});
}
async function cleanProcesses(run,record){
const before=fixtureProcesses(run);
if(run.stateRoot&&run.id){
const procs=processInventory(),known=new Set(before.map(p=>p.pid));
const {records}=await import('./lane-state.mjs');
for(const child of records(join(run.stateRoot,'runs',run.id)).filter(e=>e.kind==='child')){
const members=procs.filter(p=>p.group===child.group&&p.state!=='Z');
if(members.length&&sameProcess(child.owner,procs.find(p=>p.pid===child.owner?.pid))){
try{process.kill(-child.group,'SIGKILL');}catch(e){if(e.code!=='ESRCH')throw e;}
}else if(members.some(p=>!known.has(p.pid)))refuse('unproven orphan process-group ownership');
}
}
record({kind:'leftover-processes',objects:before.map(({pid,start,boot})=>({pid,start,boot}))});
for(const p of before){if(!sameProcess(p))continue;let raw;try{raw=readFileSync(`/proc/${p.pid}/cgroup`,'utf8');}catch(e){if(e.code==='ENOENT')continue;throw e;}const scope=raw.trim().split('/').find(x=>/^mosaic-chat-[a-z0-9]+\.scope$/.test(x));
if(scope){const shown=execFileSync('systemctl',['--user','show',scope,'-p','InvocationID','--value'],{encoding:'utf8'}).trim();if(!/^[a-f0-9]{32}$/.test(shown))refuse('scope identity unknown');record({kind:'scope-cleanup',unit:scope,invocation:shown});execFileSync('systemctl',['--user','kill','--signal=SIGKILL',scope],{stdio:'pipe'});}
if(sameProcess(p))try{process.kill(p.pid,'SIGKILL');}catch(e){if(e.code!=='ESRCH')throw e;}
}
for(let n=0;n<30;n++){if(!fixtureProcesses(run).some(p=>p.state!=='Z'))return before.length===0;await new Promise(r=>setTimeout(r,100));}
refuse('owned fixture process remains');
}
async function recoverRun(o){
if(!o.grant)refuse('missing recovery grant');
if(!/^[a-f0-9]{12}$/.test(o.runId??''))refuse('invalid run ID');
const r=runRecords(o.stateRoot).find(r=>r.id===o.runId);if(!r)refuse('run not found');
const start=r.records.find(x=>x.kind==='start');if(start?.mode==='prepare-image'&&status(o.stateRoot).legacy.length)refuse('image builder still active or unknown');if(!start||sameProcess(start.owner))refuse('run owner live or unknown');
if(r.records.some(x=>['terminal','recovered'].includes(x.kind)&&x.clean))refuse('run already clean');
shortRoot(start.tempRoot);const record=e=>appendRecord(r.dir,e);
const procs=processInventory(),known=new Set(fixtureProcesses(start).map(p=>p.pid));
for(const event of r.records.filter(e=>e.kind==='child')){
const members=procs.filter(p=>p.group===event.group&&p.state!=='Z');
if(members.length&&!sameProcess(event.owner,procs.find(p=>p.pid===event.owner?.pid))&&members.some(p=>!known.has(p.pid)))refuse('orphan process-group ownership unknown');
if(members.length&&sameProcess(event.owner)){process.kill(-event.group,'SIGKILL');}
}
await cleanProcesses(start,record);cleanupProject(start,start.docker);
appendRecord(r.dir,{kind:'recovered',clean:true,grant:o.grant,owner:identity()});return {recovered:r.id};
}
async function runGate(input){
for(const key of ['checkout','out','candidate','grant','imageReceipt'])if(!input[key])refuse(`missing ${key}`);
const automatic=!input.tempRoot,tempRoot=input.tempRoot??mkdtempSync(`/mnt/storage/scratch/g${input.lane}-`);
let o,receipt,docker;
try{
o=validateRun({...input,tempRoot});
validateTooling(o.checkout);
activeConflicts(o);
receipt=JSON.parse(readFileSync(o.imageReceipt,'utf8'));verifyImage(receipt,o.checkout);
docker=execFileSync('which',['docker'],{encoding:'utf8'}).trim();
}catch(e){if(automatic)rmdirSync(tempRoot);throw e;}
const id=nonce(),run={kind:'start',id,stateRoot:o.stateRoot,lane:o.lane,exclusive:o.exclusive,owner:identity(),grant:o.grant,candidate:o.candidate,checkout:o.checkout,tempRoot:o.tempRoot,out:o.out,project:`mg197-${o.lane}-${id}`,tag:receipt.tag,imageId:receipt.imageId,docker};
const dir=join(o.stateRoot,'runs',id);appendRecord(dir,run);const record=e=>{appendRecord(dir,e);if(e.kind==='step')process.stdout.write(`${e.name} rc=${e.rc} wall_ms=${Math.round(e.wallMs)} pass=${e.counts.pass??'-'} fail=${e.counts.fail??'-'} skipped=${e.counts.skipped??'-'}\n`);};
const begin=performance.now(),startMs=Date.now();let rc=1,clean=false,current=null;
const aborter=new AbortController();const stop=()=>aborter.abort();for(const signal of ['SIGINT','SIGTERM','SIGHUP'])process.on(signal,stop);
try{
mkdirSync(o.out,{mode:0o700});mkdirSync(join(o.out,'bin'),{mode:0o700});
writeFileSync(join(o.out,'docker.json'),JSON.stringify({...run,docker}),{mode:0o600,flag:'wx'});
const guard=join(BUILDER,'scripts/testing/lane-docker.mjs');
// Launch the guard directly so it validates every real Docker invocation.
writeFileSync(join(o.out,'bin','docker'),`#!/bin/sh\nexec '${process.execPath.replaceAll("'","'\\''")}' '${guard.replaceAll("'","'\\''")}' "$@"\n`,{mode:0o700,flag:'wx'});
const steps=discoverSteps(o.checkout);record({kind:'plan',steps});
const before=homeMetadata(process.env.HOME);record({kind:'home-before',entries:before});
const env=cleanEnv(o,run,docker);
const result=await executePinnedSteps(steps,{out:o.out,env,record,onChild:c=>current=c,signal:aborter.signal},{receipt,checkout:o.checkout,afterStep:()=>record({kind:'sockets',entries:socketInventory(o.tempRoot)})});
rc=result.rc;
const after=homeMetadata(process.env.HOME);record({kind:'home-after',entries:after});
const prior=new Map(before.map(e=>[e.path,JSON.stringify(e)]));const changed=after.filter(e=>prior.get(e.path)!==JSON.stringify(e));
if(attributeEntries(changed,{...run,nonce:id,fixturePaths:[]}).owned.length)refuse('lane-attributed real HOME write');
if(git(o.checkout,'diff','--name-only'))refuse('tracked checkout changed during gate');
const noLeaks=await cleanProcesses(run,record);cleanupProject(run,docker);clean=true;if(!noLeaks&&rc===0)rc=1;
}catch(e){record({kind:'failure',message:e.message});process.stderr.write(`${e.message}\n`);rc=rc||1;
try{await cleanProcesses(run,record);cleanupProject(run,docker);clean=true;}catch(error){record({kind:'cleanup-failed',message:error.message});}
}finally{
if(current){try{process.kill(-current.pid,'SIGKILL');}catch{}}
for(const signal of ['SIGINT','SIGTERM','SIGHUP'])process.off(signal,stop);
record({kind:'terminal',clean,rc,startMs,endMs:Date.now(),wallMs:performance.now()-begin,imageBuilds:0});
}
if(rc===0&&clean)process.stdout.write('GATE_PASSED\n');return rc;
}
async function main(argv){
const locked=argv[0]==='--locked';if(locked)argv=argv.slice(1);
if(argv[0]==='lock-dir'){
const o=options(argv.slice(1));if(!o.grant)refuse('missing grant reference');if(!['a','b'].includes(o.lane))refuse('invalid lane');process.stdout.write(stateDirectory(o.stateRoot,true)+'\n');return 0;
}
const o=options(argv);o.stateRoot=stateDirectory(o.stateRoot);
if(o.verb==='status'){process.stdout.write(JSON.stringify(status(o.stateRoot))+'\n');return 0;}
if(!locked)refuse('use gate-lane.sh for locked operations');
if(['recover','prepare-image'].includes(o.verb))o.exclusive=true;
verifyLocks(o);
if(o.verb==='recover'){process.stdout.write(JSON.stringify(await recoverRun(o))+'\n');return 0;}
if(o.verb==='prepare-image'){
for(const key of ['checkout','out','candidate','grant'])if(!o[key])refuse(`missing ${key}`);
const checked=validateRun({...o,tempRoot:o.tempRoot??mkdtempSync('/mnt/storage/scratch/ga-')});activeConflicts(checked);
const id=nonce(),dir=join(checked.stateRoot,'runs',id),docker=execFileSync('which',['docker'],{encoding:'utf8'}).trim();
appendRecord(dir,{kind:'start',mode:'prepare-image',lane:checked.lane,exclusive:true,owner:identity(),grant:checked.grant,candidate:checked.candidate,checkout:checked.checkout,tempRoot:checked.tempRoot,out:checked.out,project:`mg197-${checked.lane}-${id}`,docker});
mkdirSync(checked.out,{mode:0o700});
try{
const receipt=prepareImage(checked.checkout,checked);
writeFileSync(join(checked.out,'image-receipt.json'),JSON.stringify(receipt,null,2)+'\n',{mode:0o600,flag:'wx'});
appendRecord(dir,{kind:'terminal',clean:true,rc:0,imageId:receipt.imageId,builds:1,wallMs:receipt.buildWallMs});
process.stdout.write(JSON.stringify({imageReceipt:join(checked.out,'image-receipt.json'),imageId:receipt.imageId,buildWallMs:receipt.buildWallMs})+'\n');return 0;
}catch(e){appendRecord(dir,{kind:'terminal',clean:false,rc:1,message:e.message});throw e;}
}
return runGate(o);
}
if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href)main(process.argv.slice(2)).then(rc=>process.exitCode=rc).catch(e=>{process.stderr.write(`${e.message}\n`);process.exitCode=2;});
+26
View File
@@ -0,0 +1,26 @@
#!/usr/bin/env bash
set -euo pipefail
umask 077
entry="$(cd "$(dirname "$0")" && pwd -P)/gate-lane.mjs"
verb="${1:-run}"
if [ "$verb" = status ]; then exec node "$entry" "$@"; fi
state="$(node "$entry" lock-dir "$@")"
lane=a
exclusive=0
args=("$@")
for ((i=0;i<${#args[@]};i++)); do
case "${args[i]}" in
--lane) lane="${args[i+1]:-}" ;;
--exclusive) exclusive=1 ;;
esac
done
case "$verb" in recover|prepare-image) exclusive=1;; esac
case "$lane" in a|b) ;; *) echo 'gate-lane: refused: invalid lane' >&2; exit 2;; esac
if [ "$exclusive" = 1 ]; then
exec 3>>"$state/a.lock" 4>>"$state/b.lock" 5>>"$state/image.lock"
flock -n 3 && flock -n 4 && flock -n -x 5 || { echo 'gate-lane: refused: lane or image lock busy' >&2; exit 2; }
else
exec 3>>"$state/$lane.lock" 5>>"$state/image.lock"
flock -n 3 && flock -n -s 5 || { echo 'gate-lane: refused: lane or image lock busy' >&2; exit 2; }
fi
exec node "$entry" --locked "$@"
+60
View File
@@ -0,0 +1,60 @@
import { execFileSync, spawnSync } from 'node:child_process';
import { readFileSync, writeFileSync, linkSync, unlinkSync, openSync, closeSync, fstatSync, constants } from 'node:fs';
import { join, isAbsolute } from 'node:path';
import { pathToFileURL } from 'node:url';
import { refuse, shortRoot, nonce } from './lane-state.mjs';
function composeFiles(run){
if(!/^sha256:[a-f0-9]{64}$/.test(run.imageId??''))refuse('invalid pinned image ID');
if(typeof run.checkout!=='string'||!isAbsolute(run.checkout))refuse('invalid candidate checkout');
return [join(run.checkout,'compose.yaml'),join(shortRoot(run.tempRoot),'compose-no-build.yaml')];
}
export function writeComposeOverride(run){
const [,file]=composeFiles(run);
const text=`services:\n mosaic-agent:\n build: !reset null\n image: ${JSON.stringify(run.imageId)}\n`;
// Publish a complete file without replacing another guard's override.
const pending=file+'.'+nonce();
try{
writeFileSync(pending,text,{mode:0o600,flag:'wx'});
try{linkSync(pending,file);}catch(e){if(e.code!=='EEXIST')throw e;}
}finally{try{unlinkSync(pending);}catch(e){if(e.code!=='ENOENT')throw e;}}
let fd;
try{
fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
const st=fstatSync(fd);
if(!st.isFile()||st.uid!==process.getuid()||(st.mode&0o777)!==0o600||st.size!==Buffer.byteLength(text)||readFileSync(fd,'utf8')!==text)
refuse('unsafe or changed Compose override');
}catch{refuse('unsafe or changed Compose override');}
finally{if(fd!==undefined)closeSync(fd);}
return file;
}
export function guardDocker(argv,run){
if(argv[0]==='info'&&argv.length===1)return argv;
if(argv[0]==='image'&&argv[1]==='inspect'&&argv[2]===run.tag&&argv.length===3)return argv;
if(argv[0]==='compose'&&argv[1]==='run'){
const service=argv.indexOf('mosaic-agent',2);
if(service<0||argv.slice(2,service).some(a=>!['--rm','-T','--no-deps','--interactive','-i'].includes(a)))refuse('Docker Compose run options not allowed');
const [base,override]=composeFiles(run);
return ['compose','-f',base,'-f',override,'run','--pull','never','--no-deps',...argv.slice(2)];
}
refuse('Docker mutation or unowned command');
}
export function cleanupProject(run,docker='docker'){
if(!/^mg197-[ab]-[a-f0-9]{12}$/.test(run.project))refuse('invalid Docker ownership project');
const invoke=typeof docker==='function'?docker:(args)=>execFileSync(docker,args,{encoding:'utf8',stdio:['ignore','pipe','pipe']});
const removed=[];
for(const [kind,list,filter] of [['container',['ps','-aq'],'com.docker.compose.project'],['network',['network','ls','-q'],'com.docker.compose.project']]){
const ids=invoke([...list,'--filter',`label=${filter}=${run.project}`]).trim().split(/\s+/).filter(Boolean);
for(const id of ids){if(!/^[a-f0-9]{12,64}$/.test(id))refuse('invalid Docker resource ID');
const label=invoke([kind,'inspect',id,'--format',`{{index .${kind==='container'?'Config.':''}Labels "${filter}"}}`]).trim();
if(label!==run.project)refuse('foreign Docker resource');
invoke(kind==='container'?['container','rm','-f',id]:['network','rm',id]);removed.push({kind,id});
}
const left=invoke([...list,'--filter',`label=${filter}=${run.project}`]).trim();if(left)refuse('Docker cleanup incomplete');
}
return {clean:true,removed};
}
if(process.argv[1]&&import.meta.url===pathToFileURL(process.argv[1]).href){
try{const run=JSON.parse(readFileSync(process.env.MOSAIC_GATE_DOCKER_RECORD,'utf8'));if(process.env.COMPOSE_PROJECT_NAME!==run.project)refuse('Compose project mismatch');
const argv=guardDocker(process.argv.slice(2),run);if(argv[0]==='compose')writeComposeOverride(run);const result=spawnSync(run.docker,argv,{stdio:'inherit'});process.exit(result.status??1);
}catch(e){process.stderr.write(`${e.message}\n`);process.exit(2);}
}
+37
View File
@@ -0,0 +1,37 @@
import { readdirSync, lstatSync, readlinkSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { within, refuse } from './lane-state.mjs';
export function attributeEntries(metadata,run){
const result={owned:[],unrelated:[],unknown:[]};
for(const e of metadata){const owns=e.path.includes(run.nonce)||e.link&&within(run.tempRoot,e.link)||(run.fixturePaths??[]).some(path=>within(path,e.path)||e.link&&within(path,e.link));result[owns?'owned':'unrelated'].push(e);}
return result;
}
export function homeMetadata(home){
const out=[];
for(const name of ['.claude','.pi','.cache']){
const root=join(home,name);if(!existsSync(root))continue;
// Two levels are evidence only. Never open or hash file contents.
const walk=(dir,depth)=>{for(const d of readdirSync(dir,{withFileTypes:true})){const path=join(dir,d.name);try{const st=lstatSync(path);out.push({path,size:st.size,mtime:st.mtimeMs,mode:st.mode,link:st.isSymbolicLink()?readlinkSync(path):null});if(d.isDirectory()&&depth)walk(path,depth-1);}catch{}}};
walk(root,1);
}
return out;
}
export function socketInventory(root){const out=[];const walk=dir=>{for(const d of readdirSync(dir,{withFileTypes:true})){const p=join(dir,d.name);if(d.isDirectory())walk(p);else if(d.isSocket()){const bytes=Buffer.byteLength(p);out.push({path:p,bytes});if(bytes>107)refuse('socket path exceeds 107 bytes');}}};walk(root);return out;}
export function summarizePairs(solos,pairs){
const byCandidate=new Map(solos.map(r=>[r.candidate,r]));
if(solos.length!==2||byCandidate.size!==2||solos.some(r=>!Number.isFinite(r.wallMs)||r.wallMs<=0))refuse('solo timing invalid');
if(pairs.length!==3)refuse('proof needs three pairs');
let first;
return pairs.map((pair,index)=>{
if(pair.length!==2||pair[0].candidate===pair[1].candidate||new Set(pair.map(r=>r.lane)).size!==2||pair.some(r=>!['a','b'].includes(r.lane)))refuse('pair needs different candidates and lanes');
for(const run of pair){
if(!run.clean||run.rc!==0||!byCandidate.has(run.candidate))refuse('proof gate failed');
if(!Number.isFinite(run.startMs)||!Number.isFinite(run.endMs)||run.endMs<=run.startMs)refuse('paired timing invalid');
}
if(index===0)first=new Map(pair.map(r=>[r.candidate,r.lane]));
if(index===1&&pair.some(r=>first.get(r.candidate)===r.lane))refuse('second pair must swap lanes');
if(Math.max(...pair.map(r=>r.startMs))>=Math.min(...pair.map(r=>r.endMs)))refuse('paired gates did not overlap');
const makespan=Math.max(...pair.map(r=>r.endMs))-Math.min(...pair.map(r=>r.startMs));
return {makespanMs:makespan,runs:pair.map(r=>({candidate:r.candidate,wallMs:r.endMs-r.startMs,slowdown:(r.endMs-r.startMs)/byCandidate.get(r.candidate).wallMs})),throughput:pair.reduce((n,r)=>n+byCandidate.get(r.candidate).wallMs,0)/makespan};
});
}
+33
View File
@@ -0,0 +1,33 @@
// Imported only by tests. The port holder lives until the fixture closes.
import { spawn } from 'node:child_process';
import { mkdirSync, realpathSync } from 'node:fs';
import { join } from 'node:path';
import { createServer } from 'node:net';
import { once } from 'node:events';
import { BANDS, within, SCRATCH, refuse } from './lane-state.mjs';
async function hold(file){
const child=spawn('flock',['-n','-E','73',file,'bash','-c','printf "held\\n"; IFS= read -r release'],{stdio:['pipe','pipe','pipe']});
let err='';child.stderr.on('data',c=>err+=c);const exited=once(child,'exit');
const ok=await new Promise((resolve,reject)=>{child.stdout.once('data',()=>resolve(true));child.once('exit',code=>code===73?resolve(false):reject(Error(`port lock holder exited ${code}: ${err}`)));child.once('error',reject);});
if(!ok)return null;
return async()=>{child.stdin.end('\n');await exited;};
}
async function probe(port){const s=createServer();try{await new Promise((resolve,reject)=>{s.once('error',reject);s.listen(port,'127.0.0.1',resolve);});const found=s.address().port;await new Promise(r=>s.close(r));return found;}catch(e){if(s.listening)await new Promise(r=>s.close(r));if(e.code==='EADDRINUSE')return null;throw e;}}
export async function leasePort(t,{lane=process.env.MOSAIC_GATE_LANE,stateRoot=process.env.MOSAIC_GATE_STATE}={}){
if(!lane){const port=await probe(0);return port;}
if(!BANDS[lane]||!stateRoot)refuse('invalid port lane state');
const state=realpathSync(stateRoot);if(!within(SCRATCH,state))refuse('port state outside scratch');
const dir=join(state,'ports',lane);mkdirSync(dir,{recursive:true,mode:0o700});
const [lo,hi]=BANDS[lane];
for(let port=lo;port<=hi;port++){
const release=await hold(join(dir,`${port}.lock`));if(!release)continue;
let actual;try{actual=await probe(port);}catch(e){await release();throw e;}
if(!actual){await release();continue;}
t.after(release);return port;
}
refuse('lane port band exhausted');
}
export function fixtureCacheEnv(root){
mkdirSync(root,{recursive:true,mode:0o700});const dir=realpathSync(root);for(const n of ['tmp','jiti','cache'])mkdirSync(join(dir,n),{recursive:true,mode:0o700});
return {TMPDIR:join(dir,'tmp'),JITI_FS_CACHE:join(dir,'jiti'),XDG_CACHE_HOME:join(dir,'cache')};
}
+44
View File
@@ -0,0 +1,44 @@
import { createHash } from 'node:crypto';
import { readFileSync, readdirSync, lstatSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
import { refuse } from './lane-state.mjs';
export function imageFingerprint(checkout){
const dockerfile=readFileSync(join(checkout,'Containerfile'),'utf8');
const copies=dockerfile.split('\n').filter(l=>/^\s*(COPY|ADD)\s/i.test(l)).map(l=>l.trim());
const expected=['COPY package.json package-lock.json ./','COPY contracts /opt/mosaic/contracts','COPY src /opt/mosaic/src','COPY adapters /opt/mosaic/adapters'];
if(JSON.stringify(copies)!==JSON.stringify(expected))refuse('image COPY inputs changed; manifest review required');
const hash=createHash('sha256');
const visit=rel=>{const path=join(checkout,rel),st=lstatSync(path);if(st.isSymbolicLink())refuse('image input is a symlink');hash.update(JSON.stringify([rel,st.mode&0o777,st.isDirectory()?'d':'f'])+'\n');if(st.isDirectory())for(const n of readdirSync(path).sort())visit(`${rel}/${n}`);else if(st.isFile())hash.update(readFileSync(path));else refuse('unsupported image input');};
for(const rel of ['Containerfile','package.json','package-lock.json','contracts','src','adapters'])visit(rel);
return hash.digest('hex');
}
export function inspectImage(tag,docker=process.env.MOSAIC_GATE_REAL_DOCKER??'docker'){
return JSON.parse(execFileSync(docker,['image','inspect',tag,'--format','{{json .}}'],{encoding:'utf8',stdio:['ignore','pipe','pipe']}));
}
export function verifyImage(receipt,checkout,inspect=inspectImage){
if(!receipt||!/^sha256:[a-f0-9]{64}$/.test(receipt.imageId??'')||!/^.+@sha256:[a-f0-9]{64}$/.test(receipt.baseDigest??'')||!/^linux\/[a-z0-9_]+$/.test(receipt.platform??'')||!/^mosaic-poc-agent:[A-Za-z0-9_.-]+$/.test(receipt.tag??''))refuse('image provenance receipt invalid');
if(receipt.inputDigest!==imageFingerprint(checkout))refuse('image inputs differ');
const actual=inspect(receipt.tag);
if(actual.Id!==receipt.imageId)refuse('pinned image ID differs');
if(`${actual.Os}/${actual.Architecture}`!==receipt.platform)refuse('image platform differs');
const release=readFileSync(join(checkout,'RELEASE'),'utf8').trim();const pkg=JSON.parse(readFileSync(join(checkout,'package.json'),'utf8'));
if(pkg.dependencies?.['@earendil-works/pi-coding-agent']&&receipt.tag!==`mosaic-poc-agent:${pkg.dependencies['@earendil-works/pi-coding-agent']}-r${release}`)refuse('image tag differs from release identity');
return receipt;
}
// Called by the CLI only while both lanes and the image lock are exclusive.
export function prepareImage(checkout,{grant,tempRoot,out},invoke){
if(!grant)refuse('missing image preparation grant');
const inputDigest=imageFingerprint(checkout);
const pkg=JSON.parse(readFileSync(join(checkout,'package.json'),'utf8'));
const release=readFileSync(join(checkout,'RELEASE'),'utf8').trim();
if(!/^\d+\.\d+\.\d+$/.test(release))refuse('invalid image release');
const tag=`mosaic-poc-agent:${pkg.dependencies['@earendil-works/pi-coding-agent']}-r${release}`;
const run=invoke??((args)=>execFileSync('docker',args,{cwd:checkout,encoding:'utf8',stdio:['ignore','pipe','pipe'],env:{PATH:process.env.PATH,HOME:process.env.HOME,...(process.env.DOCKER_HOST?{DOCKER_HOST:process.env.DOCKER_HOST}:{}),COMPOSE_PROJECT_NAME:'mg197-image-prepare',MOSAIC_IMAGE_TAG:tag,MOSAIC_DATA_ROOT:join(tempRoot,'data'),MOSAIC_PROVIDER:'fixture',MOSAIC_MODEL:'fixture',PI_AUTH_FILE:'/dev/null'}}));
const start=performance.now();let buildOutput;try{buildOutput=run(['compose','build']);}catch(e){if(out)writeFileSync(join(out,'image-build.log'),String(e.stdout??'')+String(e.stderr??''),{mode:0o600,flag:'wx'});throw e;}if(out)writeFileSync(join(out,'image-build.log'),buildOutput,{mode:0o600,flag:'wx'});const buildWallMs=performance.now()-start;
if(inputDigest!==imageFingerprint(checkout))refuse('image inputs changed while building');
const actual=JSON.parse(run(['image','inspect',tag,'--format','{{json .}}']));
const base=JSON.parse(run(['image','inspect','node:24-bookworm-slim','--format','{{json .}}']));
const receipt={inputDigest,imageId:actual.Id,tag,baseDigest:base.RepoDigests?.find(x=>/@sha256:[a-f0-9]{64}$/.test(x)),platform:`${actual.Os}/${actual.Architecture}`,grant,builds:1,buildWallMs,at:new Date().toISOString()};
verifyImage(receipt,checkout,()=>actual);return receipt;
}
+77
View File
@@ -0,0 +1,77 @@
// Scratch-only lane ownership. No live Mosaic state is read or written.
import { realpathSync, statSync, lstatSync, existsSync, readdirSync, readFileSync, mkdirSync, openSync, writeSync, fsyncSync, closeSync, linkSync, unlinkSync, renameSync } from 'node:fs';
import { resolve, join, dirname, relative, isAbsolute } from 'node:path';
import { execFileSync, spawnSync } from 'node:child_process';
import { randomBytes } from 'node:crypto';
export const SCRATCH='/mnt/storage/scratch';
export const BANDS={a:[61000,61127],b:[61128,61255]};
export function refuse(message){throw new Error(`gate-lane: refused: ${message}`);}
export function within(root,path){const r=relative(root,path);return r===''||(!r.startsWith('..')&&!isAbsolute(r));}
export function shortRoot(path){
let real;try{real=realpathSync(path);}catch{refuse('temporary root missing');}
if(real==='/tmp'||real.startsWith('/tmp/'))refuse('temporary root under /tmp');
if(Buffer.byteLength(real)>30)refuse('temporary root exceeds 30 bytes');
if(!within(SCRATCH,real)||!statSync(real).isDirectory()||statSync(real).uid!==process.getuid()||(statSync(real).mode&0o077))refuse('temporary root must be private owned scratch');
return real;
}
export function socketPath(path){if(Buffer.byteLength(path)>107)refuse('socket path exceeds 107 bytes');return path;}
export function hostFacts(){
const range=readFileSync('/proc/sys/net/ipv4/ip_local_port_range','utf8').trim().split(/\s+/).map(Number);
const unprivilegedPortStart=Number(readFileSync('/proc/sys/net/ipv4/ip_unprivileged_port_start','utf8').trim());
const text=execFileSync('ss',['-Hltn'],{encoding:'utf8'});
const listeners=text.trim().split('\n').filter(Boolean).map(line=>{const field=line.trim().split(/\s+/)[3];const m=field?.match(/^(.*):(\d+)$/);if(!m)refuse('unreadable listener inventory');return {address:m[1].replace(/^\[|\]$/g,''),port:Number(m[2])};});
return {ephemeral:range,unprivilegedPortStart,listeners};
}
export function checkHost(lane,facts){
if(!facts||!Array.isArray(facts.listeners)||facts.ephemeral?.length!==2||!facts.ephemeral.every(Number.isInteger))refuse('host inventory unavailable');
if(!Number.isInteger(facts.unprivilegedPortStart)||facts.unprivilegedPortStart<=9)refuse('unprivileged port range includes port 9');
if(facts.listeners.some(x=>x.port===9&&['127.0.0.1','0.0.0.0','*','::','::ffff:127.0.0.1'].includes(x.address.replace(/%[^%]+$/, ''))))refuse('live port 9 listener');
const [lo,hi]=BANDS[lane];const [first,last]=facts.ephemeral;
if(lo<=last&&hi>=first)refuse('lane port band overlaps ephemeral range');
if(facts.listeners.some(x=>x.port>=lo&&x.port<=hi))refuse('lane port band has a live listener');
}
export function identity(pid=process.pid){try{const s=readFileSync(`/proc/${pid}/stat`,'utf8');const f=s.slice(s.lastIndexOf(')')+2).split(' ');return {pid:Number(pid),start:f[19],boot:readFileSync('/proc/sys/kernel/random/boot_id','utf8').trim(),state:f[0]};}catch{return null;}}
export function sameProcess(a,b=identity(a?.pid)){return !!a&&!!b&&a.pid===b.pid&&a.start===b.start&&a.boot===b.boot&&b.state!=='Z';}
export function nonce(){return randomBytes(6).toString('hex');}
export function appendRecord(dir,record){
const publishedDir=dir;if(record.kind==='start'){if(existsSync(dir))refuse('run already exists');dir=dir+'.starting';}
mkdirSync(dir,{recursive:true,mode:0o700});
const file=join(dir,`${Date.now()}-${nonce()}-${record.kind}.json`);
const pending=file+'.pending',fd=openSync(pending,'wx',0o600);try{writeSync(fd,JSON.stringify({...record,at:new Date().toISOString()})+'\n');fsyncSync(fd);}finally{closeSync(fd);}
linkSync(pending,file);unlinkSync(pending);if(record.kind==='start')renameSync(dir,publishedDir);return join(publishedDir,file.split('/').at(-1));
}
export function records(dir){if(!existsSync(dir))return [];return readdirSync(dir).filter(n=>n.endsWith('.json')).sort().map(n=>{try{return JSON.parse(readFileSync(join(dir,n),'utf8'));}catch{refuse(`invalid run receipt ${n}`);}});}
export function runRecords(stateRoot){
const runs=join(stateRoot,'runs');if(!existsSync(runs))return [];
return readdirSync(runs).filter(id=>!id.endsWith('.starting')).map(id=>({id,dir:join(runs,id),records:records(join(runs,id))}));
}
export function processInventory(){
const out=[];
for(const pid of readdirSync('/proc').filter(n=>/^\d+$/.test(n))){try{const argv=readFileSync(`/proc/${pid}/cmdline`,'utf8').split('\0').filter(Boolean);const raw=readFileSync(`/proc/${pid}/stat`,'utf8');const f=raw.slice(raw.lastIndexOf(')')+2).split(' ');out.push({...identity(Number(pid)),ppid:Number(f[1]),group:Number(f[2]),argv});}catch{}}
return out;
}
export function status(stateRoot,observations={}){
const procs=observations.processes??processInventory();const runs=runRecords(stateRoot);
const answer={a:{state:'CLEAR'},b:{state:'CLEAR'},image:'free',legacy:[],at:new Date().toISOString()};
const owned=new Set();
for(const run of runs){const start=run.records.find(x=>x.kind==='start');if(!start)refuse('run receipt has no start');const clean=run.records.some(x=>['terminal','recovered'].includes(x.kind)&&x.clean===true);
if(clean)continue;
const live=procs.find(p=>sameProcess(start.owner,p));const state=live?'BUSY':'QUARANTINED';
for(const lane of start.exclusive?['a','b']:[start.lane]){if(!BANDS[lane])refuse('invalid lane receipt');answer[lane]={state,run:run.id};}
answer.image=start.exclusive?'exclusive':'shared';
if(live){owned.add(live.pid);let changed=true;while(changed){changed=false;for(const p of procs)if(owned.has(p.ppid)&&!owned.has(p.pid)){owned.add(p.pid);changed=true;}}}
}
for(const p of procs){if(p.state==='Z'||p.pid===process.pid||owned.has(p.pid))continue;
const args=p.argv??[];const executable=args[0]?.split('/').at(-1);
const test=(executable==='node'&&args.includes('--test'))||args.some(a=>/^(?:.*\/)?(?:gate\.sh|test-[a-z-]+\.sh)$/.test(a))||(executable==='docker'&&(args.includes('compose')||args.includes('build')))||args.some(a=>a.endsWith('/landing.mjs')&&args.includes('gate'))||args.some(a=>/(?:^|\/)[^/]*mutant[^/]*\.(?:mjs|py|sh)$/.test(a));
if(test)answer.legacy.push({pid:p.pid,start:p.start});
}
for(const lane of ['a','b','image']){
if(observations.ignoreLocks?.includes(lane)||!existsSync(join(stateRoot,`${lane}.lock`)))continue;
const lock=lstatSync(join(stateRoot,`${lane}.lock`));if(!lock.isFile())refuse('lock is not an ordinary file');
const probe=spawnSync('flock',['-n','-x',join(stateRoot,`${lane}.lock`),'true']);
if(probe.status!==0&&probe.status!==1)refuse('cannot inspect lane lock');
if(probe.status===1){if(lane==='image')answer.image=answer.image==='free'?'held':answer.image;else if(answer[lane].state==='CLEAR')answer[lane]={state:'BUSY',run:null};}
}
return answer;
}