DanielC000/loom / packages/daemon/assets/skills/orchestrate
orchestrate
VerifiedThe operating doctrine for a Loom lead / orchestrator (manager) session. Load at the start of any orchestrator agent to run the lead-manages-workers loop — plan, decompose, delegate, review, merge, recycle — over the loom-orchestration tools. Your agent prompt supplies the project-specifics; this is the cross-project HOW.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.1 KB |
| references/deployed-instance-and-restart.md | markdown | 4.4 KB |
| references/live-verification.md | markdown | 1.8 KB |
| references/merge-and-gate.md | markdown | 14.6 KB |
| references/planning-and-kickoffs.md | markdown | 9.9 KB |
| references/project-memory.md | markdown | 4.5 KB |
| references/requests-inbox.md | markdown | 6.3 KB |
| references/resume-doc-and-memory.md | markdown | 5.0 KB |
| references/resume-doc-rotation.md | markdown | 4.3 KB |
| references/serving-and-capture.md | markdown | 7.6 KB |
| references/verification-discipline.md | markdown | 10.1 KB |
| references/worker-steering-and-recovery.md | markdown | 17.3 KB |
| scripts/dev-server.mjs | script | 37.3 KB |
| scripts/serve-static.mjs | script | 16.2 KB |
scripts/serve-static.mjs
View on GitHub#!/usr/bin/env node
// Serve a static directory over LOOPBACK so a Playwright-driven agent can eyeball an on-disk HTML
// artifact via http:// — Playwright's browser_navigate blocks file:// outright, and hand-rolling
// `python -m http.server` (or similar) every render cycle is wasted ceremony. Dependency-free: only
// node:http/node:fs/node:path/node:child_process/node:crypto/node:os/node:url, so it runs anywhere Node
// runs, no install step.
//
// Usage:
// node serve-static.mjs [dir] [port]
// Foreground mode (unchanged): serves <dir> (default: cwd) on <port> (default: 0 = OS picks a free
// port) and blocks in this process until Ctrl-C / SIGTERM or LOOM_SERVE_STATIC_TIMEOUT_MS elapses
// (default 30 minutes). Prints exactly one line once listening:
// Serving <dir> at http://127.0.0.1:<port>/
//
// node serve-static.mjs start <dir> [port]
// Spawns the server for <dir>, DETACHED so it outlives this launcher process, and prints:
// Serving <dir> at http://127.0.0.1:<port>/ (pid <pid>)
// Stop with: node serve-static.mjs stop <dir>
// Records {pid, port, dir, startedAt} to a tracking file keyed off <dir>'s absolute path (see
// trackingFilePath) so a LATER, separate `stop` invocation — even from a different shell — can find
// and kill EXACTLY this process. Refuses to start a second tracked server over an already-tracked,
// still-alive one for the same <dir>; stop the first one before starting another.
//
// node serve-static.mjs stop <dir>
// Reads the tracking file for <dir>, kills the tracked pid BY THAT EXACT PID, and removes the
// tracking file. A no-op (exit 0) if no tracked server is found for <dir> — this never enumerates
// processes and never searches by name or port.
//
// SAFETY (the reason start/stop exist): `stop` only ever acts on the pid THIS SAME HELPER recorded in
// `start` for that exact <dir> — never a name/port/netstat search. It never touches any process it
// didn't itself spawn. PID REUSE: if the tracked pid has since exited and the OS reused that number for an
// unrelated process, `stop` does not signal it — before killing, it re-reads that ONE pid's command line
// and requires the tracking-file path (passed to the server as `--track <file>`, unique to this <dir>) as a
// WHOLE argument; otherwise it refuses (nonzero exit, tracking file kept). Mirrors dev-server.mjs in this same scripts/ dir (single-purpose, no deps, tracked-pid
// start/stop, one printed line to act on) — keep the two in sync if either changes.
import { spawn, spawnSync } from "node:child_process";
import crypto from "node:crypto";
import http from "node:http";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
const SELF_PATH = fileURLToPath(import.meta.url);
const SELF = path.basename(SELF_PATH);
function usageAndExit() {
console.error(`Usage:\n node ${SELF} [dir] [port]\n node ${SELF} start <dir> [port]\n node ${SELF} stop <dir>`);
process.exit(1);
}
// Tracking file lives in the OS temp dir, keyed off the served dir's absolute path — never inside the
// served dir itself, so it's never mistaken for part of the artifact and survives independently of
// whether the dir is later removed. Distinct filename prefix from dev-server.mjs's own tracking files so
// the two helpers never collide when pointed at the same dir.
function trackingFilePath(absDir) {
const hash = crypto.createHash("sha256").update(absDir).digest("hex").slice(0, 16);
return path.join(os.tmpdir(), `loom-serve-static-${hash}.json`);
}
function readTracked(absDir) {
try {
const parsed = JSON.parse(fs.readFileSync(trackingFilePath(absDir), "utf8"));
if (parsed && typeof parsed.pid === "number" && typeof parsed.port === "number" && parsed.dir === absDir) return parsed;
return null;
} catch {
return null;
}
}
function writeTrackedAt(trackFile, record) {
fs.writeFileSync(trackFile, JSON.stringify(record), "utf8");
}
function removeTracked(absDir) {
try { fs.unlinkSync(trackingFilePath(absDir)); } catch { /* already gone */ }
}
function isAlive(pid) {
try { process.kill(pid, 0); return true; } catch { return false; }
}
// The command line of a live pid as `{ raw, argv }` (both null when gone/unreadable). `argv` is set only
// when it is an unambiguous argument array (linux /proc, win32's quoted command line); the unquoted POSIX
// `ps` text is `raw` only. Used ONLY to re-check a recorded pid before a kill — never to search for one.
function commandLineOf(pid) {
const none = { raw: null, argv: null };
try {
if (process.platform === "win32") {
const r = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`], { encoding: "utf8", timeout: 20000 });
const raw = (r.stdout || "").trim() || null;
if (!raw) return none;
return { raw, argv: splitQuotedArgs(raw) };
}
if (process.platform === "linux") {
try {
const argv = fs.readFileSync(`/proc/${Number(pid)}/cmdline`).toString("utf8").split("\0").filter((s) => s.length > 0);
return argv.length ? { raw: argv.join(" "), argv } : none;
} catch { return none; }
}
const r = spawnSync("ps", ["-ww", "-o", "args=", "-p", String(pid)], { encoding: "utf8", timeout: 10000 });
const raw = (r.stdout || "").trim() || null;
return raw ? { raw, argv: null } : none;
} catch {
return none;
}
}
// Splits a win32 command line into arguments, honoring double-quoted segments (a quoted path may hold
// spaces). Written as a char loop, not a regex, so the detached-console guard's lexer is not confused.
function splitQuotedArgs(line) {
const out = [];
let cur = "";
let has = false;
let inQuote = false;
for (const ch of line) {
if (ch === '"') { inQuote = !inQuote; has = true; continue; }
if (!inQuote && (ch === " " || ch === "\t")) {
if (has) { out.push(cur); cur = ""; has = false; }
continue;
}
cur += ch;
has = true;
}
if (has) out.push(cur);
return out;
}
const normPath = (s) => {
let c = s.split("\\").join("/");
while (c.includes("//")) c = c.split("//").join("/");
return process.platform === "win32" ? c.toLowerCase() : c;
};
// True iff the live command line carries `marker` as a WHOLE argument — never a substring, so a lookalike
// (`<marker>.bak`, `/elsewhere/<marker>`) does not match. Exact argv token when we have an argv array;
// otherwise a space-bounded match on the raw text; otherwise (unreadable) false.
function commandLineHasToken(info, marker) {
const want = normPath(marker);
if (info.argv) return info.argv.some((t) => normPath(t) === want);
if (!info.raw) return false;
const raw = normPath(info.raw);
for (let i = raw.indexOf(want); i !== -1; i = raw.indexOf(want, i + 1)) {
if ((i === 0 || raw[i - 1] === " ") && (i + want.length === raw.length || raw[i + want.length] === " ")) return true;
}
return false;
}
// True iff `pid` is still the server `start` launched for `absDir`: its command line carries this dir's
// tracking-file path as its own argument. Called immediately before any kill.
function isTrackedServer(pid, absDir) {
return commandLineHasToken(commandLineOf(pid), trackingFilePath(absDir));
}
// Kill exactly `pid` by that exact handle — never a name/port search. `taskkill /T /F` on win32 kills
// the tracked pid's whole subtree; POSIX kills the process group first (start() puts the child in its
// own group via `detached: true`) then the pid itself as a fallback.
function killTracked(pid) {
if (process.platform === "win32") {
try { spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" }); } catch { /* best effort */ }
return;
}
try { process.kill(-pid, "SIGKILL"); } catch { /* no such group / already gone */ }
try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
}
// Foreground serve — unchanged behavior for the plain `node serve-static.mjs [dir] [port]` form. When
// `trackFile` is set (only passed internally by `start`'s spawned child), also records the ACTUAL bound
// pid+port to it once listening, and removes it again on a clean shutdown.
function serve(dirArg, portArg, trackFile) {
// realpath'd at startup (not just path.resolve'd) so the per-request containment check below compares
// against the SAME real basis a symlinked-file target resolves onto — a `root` left un-realpath'd
// could itself sit behind a symlinked path segment and make an otherwise-contained real path look
// external. The tracking key (`absDir`) stays un-realpath'd so it matches what start()/stop() compute.
const absDir = path.resolve(dirArg || process.cwd());
const root = fs.realpathSync(absDir);
const requestedPort = Number(portArg || 0);
const TIMEOUT_MS = Number(process.env.LOOM_SERVE_STATIC_TIMEOUT_MS || 30 * 60 * 1000);
const MIME = {
".html": "text/html; charset=utf-8", ".htm": "text/html; charset=utf-8",
".css": "text/css; charset=utf-8",
".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
".json": "application/json; charset=utf-8",
".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
".gif": "image/gif", ".webp": "image/webp", ".ico": "image/x-icon",
".woff": "font/woff", ".woff2": "font/woff2",
".txt": "text/plain; charset=utf-8", ".pdf": "application/pdf",
};
const server = http.createServer((req, res) => {
let reqPath;
try {
reqPath = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
} catch {
res.writeHead(400).end("Bad request");
return;
}
if (reqPath.endsWith("/")) reqPath += "index.html";
// The WHATWG URL parser collapses UN-encoded ".." segments during parsing (a leading ".." at the
// root is dropped, never left in `pathname`) — but an ENCODED segment ("%2e%2e%2f") isn't split as a
// path boundary by the parser, so it survives into `reqPath` after decodeURIComponent and must be
// caught here, lexically, by resolving + checking containment before ever touching the filesystem.
const resolved = path.resolve(root, `.${reqPath}`);
if (resolved !== root && !resolved.startsWith(root + path.sep)) {
res.writeHead(403).end("Forbidden");
return;
}
// Lexical containment alone is NOT enough: `resolved` can be a symlink INSIDE root whose target sits
// OUTSIDE it (e.g. `<dir>/leak.html -> /etc/passwd`), which the check above never sees. Resolve
// symlinks (async — the handler must stay non-blocking) and re-assert containment against the REAL
// path before ever reading file contents.
fs.realpath(resolved, (err, real) => {
if (err) {
res.writeHead(404, { "Content-Type": "text/plain" }).end("Not found");
return;
}
if (real !== root && !real.startsWith(root + path.sep)) {
res.writeHead(403).end("Forbidden");
return;
}
fs.readFile(real, (err2, data) => {
if (err2) {
res.writeHead(404, { "Content-Type": "text/plain" }).end("Not found");
return;
}
const type = MIME[path.extname(resolved).toLowerCase()] || "application/octet-stream";
res.writeHead(200, { "Content-Type": type }).end(data);
});
});
});
server.listen(requestedPort, "127.0.0.1", () => {
const addr = server.address();
console.log(`Serving ${root} at http://127.0.0.1:${addr.port}/`);
if (trackFile) {
writeTrackedAt(trackFile, { pid: process.pid, port: addr.port, dir: absDir, startedAt: new Date().toISOString() });
}
});
const shutdown = () => {
if (trackFile) { try { fs.unlinkSync(trackFile); } catch { /* already gone */ } }
server.close(() => process.exit(0));
};
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);
if (TIMEOUT_MS > 0) setTimeout(shutdown, TIMEOUT_MS).unref();
}
async function start(dirArg, portArg) {
if (!dirArg) usageAndExit();
const absDir = path.resolve(dirArg);
if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
console.error(`start: not a directory: ${absDir}`);
process.exit(1);
}
const existing = readTracked(absDir);
if (existing && isAlive(existing.pid)) {
console.error(`start: a static server is already tracked for ${absDir} (pid ${existing.pid}). Stop it first: node ${SELF} stop ${dirArg}`);
process.exit(1);
}
removeTracked(absDir);
const trackFile = trackingFilePath(absDir);
const port = String(portArg || 0);
const child = spawn(process.execPath, [SELF_PATH, absDir, port, "--track", trackFile], {
// detached: own process group on POSIX (so killTracked's group-kill reaches it), and lets the child
// outlive this launcher process either way. stdio fully ignored — never a pipe left dangling once
// this launcher exits.
detached: true,
// detached:true alone opens a new visible console window on Windows; windowsHide:true hides
// only that window (no-op on POSIX).
windowsHide: true,
stdio: "ignore",
});
if (!child.pid) {
console.error("start: failed to spawn (no pid)");
process.exit(1);
}
child.unref();
// The child knows the ACTUAL bound port (0 means OS-assigned); wait for it to write that back to
// trackFile rather than guessing. Bounded so a broken child fails fast instead of hanging forever.
// Ceiling stays 5000ms (do not widen — a previous remedy for a sibling site was a
// widen that only held 12 days). The one real intermediate signal available here is the CHILD'S OWN
// LIVENESS: this launcher holds child.pid directly, so a crash before trackFile is written is an
// immediate, genuine terminal signal — distinct from "still starting, just slow under host load" —
// and there's no reason to burn the rest of the ceiling waiting on a process that's already gone.
const waitStartedAt = Date.now();
const deadline = waitStartedAt + 5000;
let record = null;
let childDied = false;
while (Date.now() < deadline) {
try {
const parsed = JSON.parse(fs.readFileSync(trackFile, "utf8"));
if (parsed && typeof parsed.pid === "number" && typeof parsed.port === "number") { record = parsed; break; }
} catch { /* not written yet */ }
if (!isAlive(child.pid)) { childDied = true; break; }
await new Promise((r) => setTimeout(r, 50));
}
if (!record) {
const waitedMs = Date.now() - waitStartedAt;
if (childDied) {
console.error(`start: child pid ${child.pid} exited before writing ${trackFile} (waited ${waitedMs}ms) for ${absDir}`);
} else {
console.error(`start: server did not come up within ${waitedMs}ms — still waiting on ${trackFile} from pid ${child.pid} for ${absDir}`);
}
// Only a child that is still alive AND still carries our marker is ours to kill: a child that already
// exited may have had its pid reused.
if (!childDied && isTrackedServer(child.pid, absDir)) { try { killTracked(child.pid); } catch { /* best effort */ } }
process.exit(1);
}
console.log(`Serving ${absDir} at http://127.0.0.1:${record.port}/ (pid ${record.pid})`);
console.log(`Stop with: node ${SELF} stop ${dirArg}`);
}
function stop(dirArg) {
if (!dirArg) usageAndExit();
const absDir = path.resolve(dirArg);
const tracked = readTracked(absDir);
if (!tracked) {
console.log(`stop: no tracked static server for ${absDir} (nothing to do)`);
return;
}
if (isAlive(tracked.pid)) {
// Re-verify identity right before the kill: the OS may have reused this pid for an unrelated process
// since `start`. Refuse and leave the tracking file so nothing else is touched.
if (!isTrackedServer(tracked.pid, absDir)) {
console.error(`stop: REFUSED — pid ${tracked.pid} is alive but its command line is not the static server this helper launched for ${absDir} (the pid was likely reused by an unrelated process, or its command line could not be read). Nothing was killed. Remove the stale tracking file ${trackingFilePath(absDir)} once you have confirmed the server is gone.`);
process.exit(1);
}
killTracked(tracked.pid);
}
removeTracked(absDir);
console.log(`Stopped pid ${tracked.pid} tracked for ${absDir}`);
}
const [, , a2, a3, a4, a5] = process.argv;
if (a2 === "start") {
await start(a3, a4);
} else if (a2 === "stop") {
stop(a3);
} else {
serve(a2, a3, a4 === "--track" ? a5 : null);
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |