Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/usr/bin/env node
/**
* skills/replica/scripts/run-bg.mjs
*
* Run an instrument in the background and wait for it in bounded slices, so
* that no single agent step blocks for longer than a few minutes and no
* step returns an instrument's whole output into the agent's context.
*
* Why: in a hands-off replica session (2026-09-18, 26-page site, 1440+360)
* one gate batch was launched as three parallel shell steps — each
* `sleep 5|10|15;` then two gate rounds and a content-diff — and the next
* model call came 15 minutes later. The agent's prompt cache lives five
* minutes from the start of the last call, so that call re-wrote the whole
* 513k-token context at the cache-write price: $6.30 for one silent gap, more
* than the gate rounds it waited for. Every other gap in that session stayed
* under 184 s and the session ran a 96% cache-hit ratio. The rule that falls out:
* an instrument may run as long as it needs, but the STEP that waits for it
* must return inside the cache lifetime, and must return a verdict summary —
* the full output belongs in a log file the agent reads by `log --grep`.
*
* Usage:
* node run-bg.mjs start --name <job> [--timeout <s>] [--slots <n>] -- <cmd> [args…]
* node run-bg.mjs wait [--max <s>] [--tail <n>] [--grep <re>] [<job>…]
* node run-bg.mjs status [--tail <n>] [--grep <re>] [<job>…]
* node run-bg.mjs log <job> [--tail <n>] [--grep <re>]
* node run-bg.mjs clean [--all]
* (every form: [--dir <d>], default stardust/.work/replica/bg, env RUN_BG_DIR)
* A value flag (--name --dir --timeout --slots --max --tail --grep) followed by
* nothing or by another --flag is a usage error (exit 125) naming the flag —
* never a silently swallowed value.
*
* start returns at once. The job runs detached under run-capped.mjs
* (default --timeout 900 s — a background job without a deadline is the
* hang class run-capped exists for; 0 disables) in its own process
* group, stdout+stderr in <dir>/<job>.log, state in <dir>/<job>.json.
* --slots (default 3; env RUN_BG_SLOTS, else STARDUST_BROWSER_SLOTS) is a
* soft concurrency cap: a job waits, first come first served, until fewer
* than that many jobs are running. Both sides of the number: each capture
* is a Chromium and one `gate.sh --full` round holds three of them at its
* peak (the three probes run in parallel), so the cap bounds the Chromiums
* at three per slot; yet at 3 slots a recorded hands-off fan-out (several
* subagents and the main agent on one pool) still queued 84 of its 272 jobs
* for more than 10 s (90th percentile 78 s, longest 210 s) with no memory
* pressure. So 3 is the default; RUN_BG_SLOTS lowers it on a small machine
* or raises it on a large one. Start the jobs all at once and let the
* slots pace them — no `sleep N;` staggering.
* wait polls until the named jobs (default: every job unfinished when the
* wait began; if none, the latest batch — jobs ended within 10 min of the
* newest; --all: every job on disk) have ended, or --max seconds pass
* (default 100; clamped to 110 — the agent's shell tool's default timeout
* is about two minutes and applies only to a call that declares none, so
* 110 s returns inside that default even when the agent forgets to declare
* one; a declared longer timeout is honoured — a recorded run completed
* waits of 179–181 s under a declared 200 s. 110 s also leaves node
* startup and the report their room, and still returns well inside the
* context cache's five minutes from the start of the previous model
* request), then prints
* one line per job and, for ended jobs, its verdict lines: log lines
* matching --grep (default: the gate instruments' verdict vocabulary),
* else the last --tail (8) lines.
* Exit 0 = every named job ended; 75 = some still queued/running —
* run `wait` again as your NEXT step. Never loop on it inside one
* command; that recreates the blocked step this tool removes.
* status one pass of the same report, without waiting.
* log a bounded view of one job's log: the last --tail lines (default
* 40) or the --grep matches (at most 200).
* clean deletes ended and lost jobs' files; --all also stops queued/running
* jobs: SIGTERM to the wrapper (run-capped forwards it to the
* instrument's process group and escalates to SIGKILL after 3 s), then
* after a 4 s grace SIGKILL to the wrapper's whole process group and to
* the instrument's, and the files go only once the wrapper is gone. A
* lost job (wrapper gone) whose instrument still runs is stopped the same
* way through the recorded childPid. Nothing is ever signalled unless its
* identity matches (below).
*
* Liveness: a job's state records the wrapper pid AND its process start time
* (`ps -o lstart`, the same on macOS and procps Linux) — a bare pid names a
* recycled process after a reboot or a busy day, and EPERM answers for a
* process that is not ours. A job counts as alive only when the pid exists, is
* not a zombie, and its start time is the recorded one (state files from before
* the identity was recorded fall back to the command line containing
* `run-bg.mjs __run … --name <job>`). Anything else is `lost`: it blocks no
* FIFO slot, never refuses its name to a new `start`, and is never signalled.
* After spawn the wrapper is the state file's only writer (the starter writes
* it once before spawn; the wrapper's first act is to write its own pid + start
* time — a state younger than 15 s without a pid is still spawning). When the
* wrapper launches the instrument it records childPid + childStart, found by
* `ps` as its own child (run-capped's API does not expose the pid); where `ps`
* is unavailable (and no /proc) they stay null and `clean --all` cannot reach
* an orphaned instrument — the wrapper's own group is still killed.
*
* Per-job exit codes are the instrument's (gate.sh: 0 PASS, 2 FAIL, 3 bot
* challenge, 4 identity, 1 error); 124 = deadline, no verdict — re-run.
*
* Also importable: start(), wait(), status(), alive(), phase(), report helpers — see the tests.
*/
/* eslint-disable no-restricted-syntax, brace-style, object-curly-newline, max-len */
import { spawn, spawnSync } from 'node:child_process';
import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, realpathSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { DEADLINE_EXIT, runCapped } from './run-capped.mjs';
export const DEFAULT_DIR = 'stardust/.work/replica/bg';
export const DEFAULT_TIMEOUT_SEC = 900;
// Each capture is a Chromium and a `gate.sh --full` round holds three at its peak, so the cap bounds the Chromiums at
// three per slot — yet at 3 slots a recorded hands-off fan-out still queued 84 of 272 jobs for more than 10 s (90th
// percentile 78 s), so 3 is the default. RUN_BG_SLOTS, else STARDUST_BROWSER_SLOTS, lowers it on a small machine or
// raises it on a large one.
export const DEFAULT_SLOTS = 3;
export const DEFAULT_MAX_SEC = 100;
// The agent's shell tool's default timeout is about two minutes and applies only to a call that declares none: 110 s
// returns inside that default even when the agent forgets to declare one, and a declared longer timeout is honoured
// (a recorded run completed waits of 179–181 s under a declared 200 s). 110 s also leaves node startup and the report
// their room, and still returns inside the context cache's five minutes from the start of the previous model request.
export const MAX_CEILING_SEC = 110;
export const DEFAULT_TAIL = 8;
export const STILL_RUNNING_EXIT = 75;
// With nothing going and no names given, `wait`/`status` report the latest batch: jobs that ended
// within this window of the newest ending. Earlier sessions' jobs stay on disk (their logs are
// evidence) but out of the report — one session's wait had dumped every prior session's summary.
export const RECENT_WINDOW_SEC = 600;
// The starter writes the state without a pid; the wrapper's first act is to write its own. A pid-less state
// younger than this is still spawning (node startup on a loaded machine), older is lost.
export const SPAWN_GRACE_SEC = 15;
// clean --all: SIGTERM first (run-capped forwards it to the instrument's group and SIGKILLs that after 3 s), then
// SIGKILL whatever is left after this grace.
const CLEAN_GRACE_MS = 4000;
// One `ps` snapshot serves a whole report/poll pass.
const PROC_TTL_MS = 250;
// The gate instruments' verdict vocabulary: pixel-compare's size/height/percentage/band lines,
// stitch-shot's completion line, gate.sh's fail-loud prefixes, run-capped's deadline notice,
// content-diff's structural count, motion-compare's SUMMARY, the browser-lock's wait/hold notices.
// Override with --grep for another instrument.
export const VERDICT_RE = /differing pixels|height delta|hot band|\bPASS\b|\bFAIL(?:ED)?\b|WARNING|\berror\b|exceeded|IDENTITY|reaped|stitched \S+:|structural|🔴|run-capped:|gate\.sh:|\b(?:content-diff|visual-diff|chrome-parity|evidence): |DEADLINE|BLOCKED|ERROR \(exit|delta\(s\)|advisory|motion summary:|SUMMARY|browser-lock:/;
const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
const POLL_MS = Number(process.env.RUN_BG_POLL_MS) || 2000;
const SELF = fileURLToPath(import.meta.url);
const HELP = `Usage:
node run-bg.mjs start --name <job> [--timeout <s>=${DEFAULT_TIMEOUT_SEC}] [--slots <n>=${DEFAULT_SLOTS}] -- <cmd> [args…]
node run-bg.mjs wait [--max <s>=${DEFAULT_MAX_SEC}] [--tail <n>=${DEFAULT_TAIL}] [--grep <re>] [--all] [<job>…]
node run-bg.mjs status [--tail <n>] [--grep <re>] [--all] [<job>…]
node run-bg.mjs log <job> [--tail <n>=40] [--grep <re>]
node run-bg.mjs clean [--all]
(all: [--dir <d>], default ${DEFAULT_DIR})`;
class UsageError extends Error { constructor(msg, code = 125) { super(msg); this.code = code; } }
const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
const statePath = (dir, name) => join(dir, `${name}.json`);
export const logPath = (dir, name) => join(dir, `${name}.log`);
const secondsBetween = (a, b) => Math.max(0, Math.round((new Date(b || Date.now()) - new Date(a)) / 1000));
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
export function readState(dir, name) { try { return JSON.parse(readFileSync(statePath(dir, name), 'utf8')); } catch { return null; } }
function writeState(dir, st) { const p = statePath(dir, st.name); const tmp = `${p}.${process.pid}.tmp`; writeFileSync(tmp, JSON.stringify(st, null, 1)); renameSync(tmp, p); return st; }
export function listJobs(dir) { if (!existsSync(dir)) return []; return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readState(dir, f.slice(0, -5))).filter(Boolean); }
// ---- process identity --------------------------------------------------------------------------
// pid → { ppid, state, start, command } from one `ps` run (cached PROC_TTL_MS); null when ps is unusable.
// lstart is 5 whitespace tokens ("Wed Sep 23 07:59:27 2026") on macOS and procps alike; -ww: never truncate.
let procCache = { at: 0, table: null };
function procTable({ fresh = false } = {}) {
if (!fresh && Date.now() - procCache.at < PROC_TTL_MS) return procCache.table;
let table = null;
const r = spawnSync('ps', ['-e', '-ww', '-o', 'pid=,ppid=,state=,lstart=,command='], { encoding: 'utf8' });
if (r.status === 0 && r.stdout) {
table = new Map();
for (const line of r.stdout.split('\n')) {
const t = line.trim().split(/\s+/);
if (t.length < 9) continue;
table.set(Number(t[0]), { ppid: Number(t[1]), state: t[2], start: t.slice(3, 8).join(' '), command: t.slice(8).join(' ') });
}
}
procCache = { at: Date.now(), table };
return table;
}
// One process's identity: the ps snapshot, else /proc (Linux without ps: start = kernel start ticks), else null.
export function procInfo(pid, opts) {
const t = procTable(opts);
if (t) return t.get(Number(pid)) || null;
try {
const stat = readFileSync(`/proc/${pid}/stat`, 'utf8'); const f = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
return { ppid: Number(f[1]), state: f[0], start: `ticks:${f[19]}`, command: readFileSync(`/proc/${pid}/cmdline`, 'latin1').split('\0').join(' ').trim() };
} catch { return null; }
}
// A pid alone is not a job: pids recycle, and EPERM answers for a process that is not ours. Ours = the pid exists,
// is not a zombie (a dead wrapper lingers as one under a PID 1 that does not reap), and its start time is the one
// recorded at spawn — or, for state files without one, its command line is this script's `__run --name <job>`.
export function alive(pid, { start = null, name = null } = {}, opts) {
if (!pid) return false;
try { process.kill(pid, 0); } catch { return false; }
const p = procInfo(pid, opts);
if (!p || /^[ZX]/.test(p.state)) return false;
if (start) return p.start === start;
return Boolean(name) && new RegExp(`run-bg\\.mjs __run\\b.* --name ${escapeRe(name)}(?: |$)`).test(p.command);
}
const wrapperAlive = (st, opts) => alive(st.wrapperPid, { start: st.wrapperStart, name: st.name }, opts);
const childAlive = (st, opts) => Boolean(st.childStart) && alive(st.childPid, { start: st.childStart }, opts);
// The wrapper's own child right after runCapped spawned it (ps itself excluded) — run-capped does not expose the pid.
function childOf(ppid) {
const t = procTable({ fresh: true }); if (!t) return null;
for (const [pid, p] of t) if (p.ppid === ppid && !/^(?:\S*\/)?ps(?: |$)/.test(p.command)) return { pid, start: p.start };
return null;
}
function signal(pid, sig, { group = false } = {}) { try { process.kill(group && process.platform !== 'win32' ? -pid : pid, sig); return true; } catch { return false; } }
// queued: waiting for a slot (or still spawning) · running · ended: wrote an exit · lost: the wrapper died without
// writing one (kill -9, reboot) or the stored pid now names some other process.
export function phase(st) {
if (st.endedAt) return 'ended';
if (!st.wrapperPid) return secondsBetween(st.queuedAt) < SPAWN_GRACE_SEC ? 'queued' : 'lost';
if (!wrapperAlive(st)) return 'lost';
return st.launchedAt ? 'running' : 'queued';
}
const isPending = (st) => ['queued', 'running'].includes(phase(st));
// lost, but the instrument the wrapper launched is still running.
const isOrphan = (st) => phase(st) === 'lost' && childAlive(st);
// ---- start -------------------------------------------------------------------------------------
export function start(dir, name, cmd, args, { timeoutSec = DEFAULT_TIMEOUT_SEC, slots = DEFAULT_SLOTS } = {}) {
if (!name || !NAME_RE.test(name)) throw new UsageError(`run-bg: --name must match ${NAME_RE} (got "${name}")\n${HELP}`);
if (!cmd) throw new UsageError(`run-bg: start needs a command after --\n${HELP}`);
if (!Number.isFinite(timeoutSec) || timeoutSec < 0) throw new UsageError(`run-bg: --timeout must be a number of seconds (0 disables)\n${HELP}`);
if (!Number.isInteger(slots) || slots < 1) throw new UsageError(`run-bg: --slots must be a positive integer\n${HELP}`);
mkdirSync(dir, { recursive: true });
const prev = readState(dir, name);
if (prev && isPending(prev)) throw new UsageError(`run-bg: ${name} is still ${phase(prev)} (wrapper pid ${prev.wrapperPid}) — pick another --name, or \`clean --all\` to stop it`, 2);
// Written once, before the spawn; from here on the wrapper is the file's only writer.
const st = { name, cmd, args, cwd: process.cwd(), timeoutSec, slots, queuedAt: new Date().toISOString(), wrapperPid: null, wrapperStart: null, launchedAt: null, childPid: null, childStart: null, endedAt: null, exit: null, timedOut: false };
writeState(dir, st);
const fd = openSync(logPath(dir, name), 'w');
const child = spawn(process.execPath, [SELF, '__run', '--dir', dir, '--name', name], { detached: true, stdio: ['ignore', fd, fd], cwd: process.cwd(), env: process.env });
closeSync(fd);
child.unref();
return { name, log: logPath(dir, name), wrapperPid: child.pid };
}
// The detached wrapper: record its identity, take a slot (FIFO), run the command under run-capped, record the exit.
async function runWrapper(dir, name) {
let st = readState(dir, name);
if (!st) throw new Error(`run-bg: state for ${name} vanished from ${dir}`);
st = writeState(dir, { ...st, wrapperPid: process.pid, wrapperStart: procInfo(process.pid, { fresh: true })?.start ?? null });
for (;;) {
const others = listJobs(dir).filter((j) => j.name !== name);
const running = others.filter((j) => phase(j) === 'running').length;
const ahead = others.filter((j) => phase(j) === 'queued' && (j.queuedAt < st.queuedAt || (j.queuedAt === st.queuedAt && j.name < name))).length;
if (running < st.slots && ahead === 0) break;
await sleep(Math.min(POLL_MS, 1000));
}
const run = runCapped(st.cmd, st.args, { timeoutSec: st.timeoutSec, label: name }); // spawns synchronously
const child = childOf(process.pid);
st = writeState(dir, { ...st, launchedAt: new Date().toISOString(), childPid: child?.pid ?? null, childStart: child?.start ?? null });
console.log(`run-bg: ${name} launched ${st.launchedAt} (timeout ${st.timeoutSec || 'none'}s): ${[st.cmd, ...st.args].join(' ')}`);
const code = await run;
writeState(dir, { ...st, endedAt: new Date().toISOString(), exit: code, timedOut: code === DEADLINE_EXIT });
console.log(`run-bg: ${name} ended exit=${code}`);
process.exitCode = code;
}
// ---- report ------------------------------------------------------------------------------------
export function verdictLines(p, { tail = DEFAULT_TAIL, grep = null } = {}) {
let text; try { text = readFileSync(p, 'utf8'); } catch { return ['(no log)']; }
const own = /^run-bg: /;
const all = text.split('\n').filter((l) => l.trim() && !own.test(l));
const re = grep || VERDICT_RE;
const hits = all.filter((l) => re.test(l));
const pick = hits.length ? hits : all;
const out = pick.slice(-tail).map((l) => (l.length > 240 ? `${l.slice(0, 237)}…` : l));
if (pick.length > tail) out.unshift(`… ${pick.length - tail} earlier ${hits.length ? 'verdict ' : ''}lines in ${p}`);
if (!hits.length && all.length) out.unshift(`(no verdict-vocabulary line; last ${Math.min(tail, all.length)} lines — \`log --grep <re>\` for more)`);
return out;
}
export function describe(st) {
const ph = phase(st);
if (ph === 'queued') return `${st.name} queued ${secondsBetween(st.queuedAt)}s (waiting for a slot)`;
if (ph === 'running') return `${st.name} running ${secondsBetween(st.launchedAt)}s`;
if (ph === 'lost') return `${st.name} lost — wrapper gone without an exit (kill -9? reboot?)${isOrphan(st) ? `; its instrument (pid ${st.childPid}) still runs — \`clean --all\` stops it` : ''} — re-run`;
const took = st.launchedAt ? ` in ${secondsBetween(st.launchedAt, st.endedAt)}s` : '';
return st.timedOut ? `${st.name} deadline ${st.timeoutSec}s exceeded (exit ${DEADLINE_EXIT}: no verdict — re-run, or raise --timeout for a legitimately huge page)${took}` : `${st.name} done exit=${st.exit}${took}`;
}
export function report(dir, names, { tail = DEFAULT_TAIL, grep = null, hidden = 0, elapsedSec = 0, ceilingSec = 0 } = {}) {
const lines = []; let pending = 0;
for (const name of names) {
const st = readState(dir, name);
if (!st) { lines.push(`${name} no such job in ${dir}`); continue; }
if (isPending(st)) pending += 1;
lines.push(describe(st));
if (!isPending(st)) for (const l of verdictLines(logPath(dir, name), { tail, grep })) lines.push(` ${l}`);
}
if (!names.length) lines.push(`run-bg: no jobs in ${dir}`);
else if (pending) lines.push(`run-bg: ${names.length - pending}/${names.length} ended, ${pending} still going${elapsedSec ? ` after ${Math.round(elapsedSec)}s (ceiling ${ceilingSec}s)` : ''} — run \`wait\` again as your next step; logs: ${dir}/<job>.log`);
else lines.push(`run-bg: all ${names.length} ended — full output per job: \`log <job> --grep <re>\` (${dir}/<job>.log)`);
if (hidden) lines.push(`run-bg: ${hidden} earlier job(s) not shown — \`status --all\``);
return { text: lines.join('\n'), pending };
}
function pickNames(dir, requested, { all = false } = {}) {
if (requested.length) return { names: requested, hidden: 0 };
const jobs = listJobs(dir).sort((a, b) => (a.queuedAt < b.queuedAt ? -1 : 1));
const unfinished = jobs.filter(isPending);
if (unfinished.length) return { names: unfinished.map((j) => j.name), hidden: 0 };
if (all || !jobs.length) return { names: jobs.map((j) => j.name), hidden: 0 };
const at = (j) => new Date(j.endedAt || j.queuedAt).getTime();
const newest = Math.max(...jobs.map(at));
const recent = jobs.filter((j) => newest - at(j) <= RECENT_WINDOW_SEC * 1000);
return { names: recent.map((j) => j.name), hidden: jobs.length - recent.length };
}
export async function wait(dir, requested, { maxSec = DEFAULT_MAX_SEC, tail, grep, all = false } = {}) {
if (!Number.isFinite(maxSec) || maxSec < 0) throw new UsageError(`run-bg: --max must be a number of seconds\n${HELP}`);
let ceilingSec = maxSec;
if (maxSec > MAX_CEILING_SEC) { ceilingSec = MAX_CEILING_SEC; console.error(`run-bg: --max ${maxSec} clamped to ${MAX_CEILING_SEC}s — the agent's shell tool's default timeout is about two minutes and applies to a call that declares none; ${MAX_CEILING_SEC} s returns inside it and leaves startup and the report their room (a declared longer timeout is honoured, but a step must still return before the context cache expires)`); }
const { names, hidden } = pickNames(dir, requested, { all });
const t0 = Date.now();
for (;;) {
const pending = names.map((n) => readState(dir, n)).filter((st) => st && isPending(st));
if (!pending.length || (Date.now() - t0) / 1000 >= ceilingSec) break;
await sleep(Math.min(POLL_MS, Math.max(50, ceilingSec * 1000 - (Date.now() - t0))));
}
return report(dir, names, { tail, grep, hidden, elapsedSec: (Date.now() - t0) / 1000, ceilingSec });
}
export function status(dir, requested, { tail, grep, all = false } = {}) { const { names, hidden } = pickNames(dir, requested, { all }); return report(dir, names, { tail, grep, hidden }); }
export function showLog(dir, name, { tail = 40, grep = null } = {}) {
if (!name) throw new UsageError(`run-bg: log needs a <job>\n${HELP}`);
const p = logPath(dir, name);
let text; try { text = readFileSync(p, 'utf8'); } catch { throw new UsageError(`run-bg: no log for ${name} at ${p}`, 2); }
const all = text.split('\n'); if (all.length && all[all.length - 1] === '') all.pop();
const pick = grep ? all.filter((l) => grep.test(l)) : all;
const cap = grep ? Math.min(200, Math.max(tail, 1)) : tail;
const out = pick.slice(-cap);
const head = `${p}: ${all.length} lines${grep ? `, ${pick.length} match ${grep}` : ''}${pick.length > cap ? `, showing the last ${cap}` : ''}`;
return `${head}\n${out.join('\n')}`;
}
// Without --all: ended and lost jobs' files go; queued/running jobs, and lost jobs whose instrument still runs, stay.
// With --all: every live wrapper (own group) and every identity-matched instrument (own group) is stopped — SIGTERM,
// grace, SIGKILL — and a job's files go only once nothing of it is left alive.
export async function clean(dir, { all = false } = {}) {
const out = []; const targets = new Map(); // name → [{ pid, ident, what }]
for (const j of listJobs(dir)) {
const pending = isPending(j); const orphan = !pending && isOrphan(j);
if (!pending && !orphan) continue;
if (!all) { out.push(`run-bg: keeping ${j.name} (${pending ? phase(j) : `lost, instrument pid ${j.childPid} still running`}) — \`clean --all\` stops it`); continue; }
const t = [];
if (pending) t.push({ pid: j.wrapperPid, ident: { start: j.wrapperStart, name: j.name }, what: 'wrapper' });
if (childAlive(j)) t.push({ pid: j.childPid, ident: { start: j.childStart }, what: 'instrument' });
targets.set(j.name, t);
for (const x of t) signal(x.pid, 'SIGTERM', { group: x.what === 'instrument' });
}
const left = () => [...targets.values()].flat().filter((x) => alive(x.pid, x.ident, { fresh: true }));
if (targets.size) {
const t0 = Date.now();
while (left().length && Date.now() - t0 < CLEAN_GRACE_MS) await sleep(100);
for (const x of left()) signal(x.pid, 'SIGKILL', { group: true });
if (left().length) await sleep(200);
}
const survivors = new Set(left().map((x) => x.pid));
for (const [name, t] of targets) {
const stuck = t.filter((x) => survivors.has(x.pid));
out.push(stuck.length ? `run-bg: could not stop ${name} (${stuck.map((x) => `${x.what} pid ${x.pid}`).join(', ')} survived SIGKILL) — files kept` : `run-bg: stopped ${name}`);
}
for (const j of listJobs(dir)) {
if ((isPending(j) || isOrphan(j)) && (!all || (targets.get(j.name) || []).some((x) => survivors.has(x.pid)))) continue;
for (const p of [statePath(dir, j.name), logPath(dir, j.name)]) { try { unlinkSync(p); } catch { /* gone */ } }
if (!targets.has(j.name)) out.push(`run-bg: removed ${j.name}`);
}
return out.join('\n');
}
// ---- cli ---------------------------------------------------------------------------------------
function parse(argv) {
const [sub, ...rest] = argv;
const o = { dir: process.env.RUN_BG_DIR || DEFAULT_DIR, names: [], name: null, timeoutSec: DEFAULT_TIMEOUT_SEC, slots: Number(process.env.RUN_BG_SLOTS) || Number(process.env.STARDUST_BROWSER_SLOTS) || DEFAULT_SLOTS, maxSec: DEFAULT_MAX_SEC, tail: undefined, grep: null, all: false, cmd: [] };
const num = (flag, v) => { const n = Number(v); if (!Number.isFinite(n)) throw new UsageError(`run-bg: ${flag} needs a number (got ${v})\n${HELP}`); return n; };
for (let i = 0; i < rest.length; i += 1) {
const a = rest[i];
// A value flag never swallows a following flag (or nothing) as its value.
const value = () => { const v = rest[i + 1]; if (v === undefined || v.startsWith('--')) throw new UsageError(`run-bg: ${a} needs a value${v === undefined ? '' : ` (got ${v})`}\n${HELP}`); i += 1; return v; };
if (a === '--') { o.cmd = rest.slice(i + 1); break; }
if (a === '--dir') o.dir = value();
else if (a === '--name') o.name = value();
else if (a === '--timeout') o.timeoutSec = num(a, value());
else if (a === '--slots') o.slots = num(a, value());
else if (a === '--max') o.maxSec = num(a, value());
else if (a === '--tail') o.tail = num(a, value());
else if (a === '--grep') { const v = value(); try { o.grep = new RegExp(v); } catch (e) { throw new UsageError(`run-bg: bad --grep ${v}: ${e.message}`); } }
else if (a === '--all') o.all = true;
else if (a.startsWith('--')) throw new UsageError(`run-bg: unknown flag ${a}\n${HELP}`);
else o.names.push(a);
}
if (!o.dir) throw new UsageError(`run-bg: --dir needs a path\n${HELP}`);
o.dir = resolve(o.dir);
return { sub, o };
}
async function cli(argv) {
if (!argv.length || argv.includes('--help') || argv.includes('-h')) { console.log(HELP); return 0; }
const { sub, o } = parse(argv);
switch (sub) {
case 'start': {
const [cmd, ...args] = o.cmd;
const r = start(o.dir, o.name, cmd, args, { timeoutSec: o.timeoutSec, slots: o.slots });
console.log(`run-bg: queued ${r.name} → ${r.log} (next step: node stardust/scripts/replica/run-bg.mjs wait)`);
return 0;
}
case 'wait': { const r = await wait(o.dir, o.names, { maxSec: o.maxSec, tail: o.tail, grep: o.grep, all: o.all }); console.log(r.text); return r.pending ? STILL_RUNNING_EXIT : 0; }
case 'status': { const r = status(o.dir, o.names, { tail: o.tail, grep: o.grep, all: o.all }); console.log(r.text); return 0; }
case 'log': console.log(showLog(o.dir, o.names[0], { tail: o.tail ?? 40, grep: o.grep })); return 0;
case 'clean': console.log(await clean(o.dir, { all: o.all })); return 0;
case '__run': await runWrapper(o.dir, o.name); return process.exitCode ?? 0;
default: throw new UsageError(`run-bg: unknown command "${sub}"\n${HELP}`);
}
}
// Compare by real path: a symlinked checkout or temp dir must not turn the CLI into a silent no-op.
function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && SELF === safeRealpath(process.argv[1])) {
// exitCode, not process.exit(): see run-capped.mjs — a forced exit can hang Node's platform shutdown.
cli(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e instanceof UsageError ? e.message : `run-bg: ${e.stack || e.message}`); process.exitCode = e instanceof UsageError ? e.code : 1; });
}.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference