Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
import { spawn, execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { mkdir, writeFile, readdir, stat } from 'node:fs/promises';
import path from 'node:path';
import crypto from 'node:crypto';
import { createWorktree, isGitRepo, gc } from '@cobusgreyling/loop-worktree';
import { lockPaths, unlockOwner } from '@cobusgreyling/loop-worktree/lock';
const runExec = promisify(execFile);
/** Run a git command in cwd, returning stdout trimmed. Throws on error. */
async function git(args, cwd) {
const { stdout } = await runExec('git', args, { cwd, maxBuffer: 50 * 1024 * 1024 });
return stdout.trim();
}
/** Run a git command in cwd, returning raw untrimmed Buffer (for binary patches). Throws on error. */
async function gitRaw(args, cwd) {
return new Promise((resolve, reject) => {
execFile('git', args, { cwd, encoding: 'buffer', maxBuffer: 50 * 1024 * 1024 }, (err, stdout) => {
if (err)
reject(err);
else
resolve(stdout);
});
});
}
/**
* Wraps an agent command in a temporary git worktree sandbox.
* Returns the patch file path if changes were made.
*/
export async function runInSandbox(root, command, args, options = {}) {
if (!(await isGitRepo(root))) {
throw new Error('loop-sandbox must be run inside a git repository.');
}
const runId = `sandbox-${crypto.randomBytes(4).toString('hex')}`;
// 1. Setup paths
const sandboxDir = path.join(root, '.loop-sandbox');
const patchesDir = path.join(sandboxDir, 'patches');
await mkdir(patchesDir, { recursive: true });
const baseBranch = options.base || await git(['rev-parse', '--abbrev-ref', 'HEAD'], root).catch(() => 'main');
const lockOwner = options.lockOwner ?? runId;
// Whether a lock was *requested*, not whether it was confirmed acquired --
// lockPaths() can be interrupted mid-wait (e.g. by a signal during
// --lock-wait), leaving only a `<owner>.wait.json` file with no matching
// lock. unlockOwner() removes either or both and is a safe no-op if
// neither exists, so gating cleanup on the original request (rather than
// on successful acquisition) also sweeps up that stray wait file.
const lockRequested = Boolean(options.lockPaths && options.lockPaths.length > 0);
let worktreeAbsPath = null;
let extractionFailed = false;
let activeChild = null;
// Cleanup must run on every exit path, including Ctrl+C mid-run, and
// exactly once even if a signal lands twice: the previous shape re-invoked
// cleanup() on every signal and let it no-op past a boolean guard while
// still calling process.exit(1) right after -- a second Ctrl+C during a
// slow `git worktree remove` would exit before the *first* cleanup's lock
// release ever ran, stranding a no-TTL lock. Sharing one promise across
// every caller means every signal (first or repeated) waits on the same
// in-flight cleanup before exiting.
let cleanupPromise = null;
const cleanup = () => {
if (!cleanupPromise) {
cleanupPromise = (async () => {
// Stop the sandboxed command first so it can't keep writing into the
// worktree (or racing the lock's protected paths) after cleanup has
// started tearing things down around it.
activeChild?.kill();
// Release the lock before worktree teardown: it's the resource other
// loops are blocked on, and a slow worktree removal shouldn't delay
// it. Logged only once we know a lock (or stray wait file) actually
// existed -- lockRequested only means a lock was asked for, so
// logging unconditionally here would print "Releasing lock held by
// X" even when lockPaths() itself failed (e.g. blocked by another
// owner with no --wait) and no lock was ever acquired.
if (lockRequested) {
try {
const released = await unlockOwner(root, lockOwner);
if (released) {
console.log(`🔓 Released lock held by "${lockOwner}".`);
}
}
catch (err) {
console.error(`❌ Failed to release lock for "${lockOwner}". Run \`loop-worktree unlock --owner ${lockOwner}\` manually:`, err);
}
}
if (worktreeAbsPath) {
if (extractionFailed) {
console.log(`⚠️ Patch extraction failed. The worktree at ${worktreeAbsPath} and branch loop/${runId} were left on disk for manual recovery.`);
}
else {
console.log(`🧹 Cleaning up sandbox worktree...`);
try {
await git(['worktree', 'remove', '--force', worktreeAbsPath], root);
await git(['branch', '-D', `loop/${runId}`], root).catch(() => { });
await gc({ root, force: false });
}
catch (err) {
console.error(`❌ Failed to cleanup sandbox worktree. It may need manual removal:`, err);
process.exitCode = 1;
}
}
}
})();
}
return cleanupPromise;
};
const sigHandler = () => {
cleanup().finally(() => process.exit(1));
};
process.on('SIGINT', sigHandler);
process.on('SIGTERM', sigHandler);
try {
if (lockRequested) {
console.log(`\n🔒 Locking ${options.lockPaths.join(', ')} as "${lockOwner}"...`);
await lockPaths({ root, owner: lockOwner, paths: options.lockPaths, ttl: options.lockTtl, wait: options.lockWait });
}
console.log(`\n📦 Creating ephemeral worktree isolation: ${runId}`);
// 2. Create the worktree
const entry = await createWorktree({
root,
runId,
pattern: 'sandbox', // dummy pattern
base: baseBranch
});
worktreeAbsPath = path.resolve(root, entry.path);
console.log(`🚀 Executing inside sandbox: ${command} ${args.join(' ')}`);
let exitCode = null;
let hasChanges = false;
let patchFilePath = null;
// 3. Execute the user's command
try {
exitCode = await new Promise((resolve) => {
// On Windows, a failed spawn (ENOENT) still emits a 'close' event a
// few ms after 'error' with a synthetic exit code. Once the ENOENT
// retry below fires, this flag makes the first (non-shell) attempt's
// now-stale 'close'/'error' events no-ops instead of letting them win
// the resolve() race against the retry's real, later result.
let supersededByRetry = false;
const attempt = (useShell) => {
const child = spawn(command, args, {
cwd: worktreeAbsPath,
stdio: 'inherit',
shell: useShell
});
activeChild = child;
child.on('close', (code) => {
if (!useShell && supersededByRetry)
return;
activeChild = null;
resolve(code);
});
child.on('error', (err) => {
if (!useShell && supersededByRetry)
return;
// On Windows, npm-installed CLIs (npx, tsc, ...) are .cmd/.bat
// shims that spawn can't exec directly, and fail with ENOENT --
// retry once through a shell. Forcing shell: true unconditionally
// instead would break commands whose args rely on exact argv
// quoting (e.g. `node -e "..."`), so only fall back on the
// specific error this class of command actually produces.
if (!useShell && !options.shell && process.platform === 'win32' && err.code === 'ENOENT') {
supersededByRetry = true;
attempt(true);
return;
}
activeChild = null;
resolve(1);
});
};
attempt(options.shell ?? false);
});
}
catch (err) {
console.error(`❌ Execution failed inside sandbox:`, err);
exitCode = 1;
}
console.log(`\n🔍 Scanning sandbox for changes...`);
// 4. Extract diff as a patch
try {
await git(['add', '-A'], worktreeAbsPath);
const diffStat = await git(['diff', '--cached', '--stat'], worktreeAbsPath);
if (diffStat) {
hasChanges = true;
patchFilePath = path.join(patchesDir, `${runId}.patch`);
const diffOutput = await gitRaw(['diff', '--cached', '--binary'], worktreeAbsPath);
await writeFile(patchFilePath, diffOutput);
console.log(`✅ Sandbox changes captured to patch: ${patchFilePath}`);
}
else {
console.log(`ℹ️ No changes were made in the sandbox.`);
}
}
catch (err) {
console.error(`❌ Failed to extract patch from sandbox:`, err);
extractionFailed = true;
}
return {
runId,
patchFile: patchFilePath,
exitCode,
hasChanges
};
}
finally {
process.removeListener('SIGINT', sigHandler);
process.removeListener('SIGTERM', sigHandler);
await cleanup();
}
}
/** Lists all available patches in the .loop-sandbox/patches/ directory. */
export async function listPatches(root) {
const patchesDir = path.join(root, '.loop-sandbox', 'patches');
try {
const files = await readdir(patchesDir, { withFileTypes: true });
const patches = [];
for (const f of files) {
if (f.isFile() && f.name.endsWith('.patch')) {
const patchPath = path.join(patchesDir, f.name);
const s = await stat(patchPath);
patches.push({
patchName: f.name,
patchPath,
size: s.size
});
}
}
return patches;
}
catch {
return [];
}
}