Skip to content

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.

fix(loop-audit,loop-sandbox): correct gate.yaml auto-fix schema and Windows spawn ENOENT (#382)

JonyT Agentic5bd6c18244a2
diff --git a/tools/loop-audit/dist/autofixer.js b/tools/loop-audit/dist/autofixer.js
index 24f5efa..6cafa8d 100644
--- a/tools/loop-audit/dist/autofixer.js
+++ b/tools/loop-audit/dist/autofixer.js
@@ -147,13 +147,25 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md — Project Conventions
- Never auto-merge changes.
- Ensure all loops isolate their work in worktrees.
`;
-const GATE_YAML_TEMPLATE = `# gate.yaml - Explicit human approval gates
-
-gates:
- - name: "Auto-merge to main"
- description: "Never auto-merge changes to the main branch."
- required_approvers:
- - "human"
+const GATE_YAML_TEMPLATE = `# Machine-readable twin of docs/safety.md, enforced by \`loop-gate check\`.
+# See templates/gate.yaml.template in loop-engineering for the full reference.
+version: 1
+
+denylist:
+ - ".env"
+ - ".env.*"
+ - "**/secrets/**"
+ - "**/credentials/**"
+ - "**/*_key*"
+ - "**/*_secret*"
+
+# Escalate instead of auto-merging when a change touches more than this many files.
+maxFiles: 10
+
+# --action auto-merge only proceeds if every changed path matches one of these.
+autoMergeAllowlist:
+ - "docs/**"
+ - "**/*.md"
`;
export async function autoFixProject(target, result) {
const root = path.resolve(target);
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index df389a6..b4d6402 100644
--- a/tools/loop-audit/package.json
+++ b/tools/loop-audit/package.json
@@ -12,7 +12,7 @@
],
"scripts": {
"build": "tsc",
- "test": "npm run build && node --test test/auditor.test.mjs",
+ "test": "npm run build && node --test test/*.test.mjs",
"prepublishOnly": "npm test",
"start": "node dist/cli.js",
"audit": "npm run build && node dist/cli.js",
diff --git a/tools/loop-audit/src/autofixer.ts b/tools/loop-audit/src/autofixer.ts
index 9ade06d..48f45e0 100644
--- a/tools/loop-audit/src/autofixer.ts
+++ b/tools/loop-audit/src/autofixer.ts
@@ -156,13 +156,25 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md — Project Conventions
- Ensure all loops isolate their work in worktrees.
`;
-const GATE_YAML_TEMPLATE = `# gate.yaml - Explicit human approval gates
-
-gates:
- - name: "Auto-merge to main"
- description: "Never auto-merge changes to the main branch."
- required_approvers:
- - "human"
+const GATE_YAML_TEMPLATE = `# Machine-readable twin of docs/safety.md, enforced by \`loop-gate check\`.
+# See templates/gate.yaml.template in loop-engineering for the full reference.
+version: 1
+
+denylist:
+ - ".env"
+ - ".env.*"
+ - "**/secrets/**"
+ - "**/credentials/**"
+ - "**/*_key*"
+ - "**/*_secret*"
+
+# Escalate instead of auto-merging when a change touches more than this many files.
+maxFiles: 10
+
+# --action auto-merge only proceeds if every changed path matches one of these.
+autoMergeAllowlist:
+ - "docs/**"
+ - "**/*.md"
`;
export async function autoFixProject(target: string, result: AuditResult): Promise<void> {
diff --git a/tools/loop-audit/test/autofixer.test.mjs b/tools/loop-audit/test/autofixer.test.mjs
new file mode 100644
index 0000000..862f7b9
--- /dev/null
+++ b/tools/loop-audit/test/autofixer.test.mjs
@@ -0,0 +1,52 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { autoFixProject } from '../dist/autofixer.js';
+
+/** Signals with every fixable gap closed except gate.yaml, so autoFixProject
+ * writes only that file (and never shells out to loop-init). */
+function signalsMissingOnlyGateYaml() {
+ return {
+ stateFile: { present: true, paths: ['STATE.md'] },
+ loopConfig: { present: true },
+ skills: { count: 0, loopSkills: [] },
+ verifier: { present: false },
+ triage: { present: false },
+ agentsMd: { present: true },
+ patterns: { documented: false },
+ safety: { loopMdMentionsSafety: false, safetyDocPresent: true },
+ starters: { used: false },
+ github: { present: false, workflows: false },
+ mcp: { present: false },
+ worktreeEvidence: { present: false },
+ registry: { present: false },
+ constraints: { present: true, hasConstraintsSkill: false },
+ cost: { budgetDoc: true, runLog: true, loopMdBudget: false, budgetSkill: false },
+ governance: { toolScope: false, stallDetection: false, escalation: false, gateYaml: false },
+ loopActivity: { present: false, evidence: [] },
+ harness: { stack: true, lock: false, sessions: false, emit: false, host: false },
+ memory: { tiers: true, budget: false },
+ fleet: { registry: false, inbox: false },
+ };
+}
+
+test('autoFixProject writes a gate.yaml that loop-gate can actually load', async () => {
+ const root = await mkdtemp(path.join(tmpdir(), 'loop-audit-autofix-'));
+ try {
+ await autoFixProject(root, { score: 0, level: 'L0', signals: signalsMissingOnlyGateYaml() });
+
+ const written = await readFile(path.join(root, 'gate.yaml'), 'utf8');
+
+ // This is the schema tools/loop-gate/src/gate.ts's loadGateConfig actually
+ // requires -- { version: 1, denylist: string[], ... } -- not the
+ // { gates: [...] } shape this template used to emit, which loop-gate
+ // rejects outright.
+ assert.match(written, /version:\s*1/);
+ assert.match(written, /denylist:/);
+ assert.doesNotMatch(written, /^gates:/m);
+ } finally {
+ await rm(root, { recursive: true, force: true }).catch(() => {});
+ }
+});
diff --git a/tools/loop-sandbox/README.md b/tools/loop-sandbox/README.md
index 104f69f..beab86c 100644
--- a/tools/loop-sandbox/README.md
+++ b/tools/loop-sandbox/README.md
@@ -49,7 +49,7 @@ loop-sandbox <command> [options]
| Option | Description |
|--------|-------------|
-| `--shell` | Spawns the command using `shell: true` (for bash -c, etc.) |
+| `--shell` | Forces `shell: true` (for `bash -c`, etc.). On Windows, npm-installed `.cmd` shims (`npx`, `tsc`, ...) that fail with `ENOENT` are automatically retried through a shell, so this is rarely needed there. |
| `--base <branch>` | The base branch for the worktree (defaults to current HEAD) |
### Examples
diff --git a/tools/loop-sandbox/dist/cli.js b/tools/loop-sandbox/dist/cli.js
index 5721526..c80c100 100644
--- a/tools/loop-sandbox/dist/cli.js
+++ b/tools/loop-sandbox/dist/cli.js
@@ -95,7 +95,10 @@ Usage:
loop-sandbox review List isolated patches ready for human review.
Options for 'run':
- --shell Run the command inside a shell environment (shell: true)
+ --shell Force the command to run inside a shell environment
+ (needed for shell built-ins like "bash -c"; on Windows,
+ npm-installed .cmd shims like npx/tsc retry through a shell
+ automatically on ENOENT, so this is rarely needed there)
--base The base branch to branch the worktree from (default: current HEAD)
Examples:
diff --git a/tools/loop-sandbox/dist/sandbox.js b/tools/loop-sandbox/dist/sandbox.js
index 73d60a6..e007dbf 100644
--- a/tools/loop-sandbox/dist/sandbox.js
+++ b/tools/loop-sandbox/dist/sandbox.js
@@ -78,14 +78,42 @@ export async function runInSandbox(root, command, args, options = {}) {
try {
// 3. Execute the user's command
try {
- const child = spawn(command, args, {
- cwd: worktreeAbsPath,
- stdio: 'inherit',
- shell: options.shell ?? false
- });
exitCode = await new Promise((resolve) => {
- child.on('close', (code) => resolve(code));
- child.on('error', () => resolve(1));
+ // 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
+ });
+ child.on('close', (code) => {
+ if (!useShell && supersededByRetry)
+ return;
+ 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;
+ }
+ resolve(1);
+ });
+ };
+ attempt(options.shell ?? false);
});
}
catch (err) {
diff --git a/tools/loop-sandbox/src/cli.ts b/tools/loop-sandbox/src/cli.ts
index de04871..72f0d9e 100644
--- a/tools/loop-sandbox/src/cli.ts
+++ b/tools/loop-sandbox/src/cli.ts
@@ -106,7 +106,10 @@ Usage:
loop-sandbox review List isolated patches ready for human review.
Options for 'run':
- --shell Run the command inside a shell environment (shell: true)
+ --shell Force the command to run inside a shell environment
+ (needed for shell built-ins like "bash -c"; on Windows,
+ npm-installed .cmd shims like npx/tsc retry through a shell
+ automatically on ENOENT, so this is rarely needed there)
--base The base branch to branch the worktree from (default: current HEAD)
Examples:
diff --git a/tools/loop-sandbox/src/sandbox.ts b/tools/loop-sandbox/src/sandbox.ts
index 16e02a9..5c074a4 100644
--- a/tools/loop-sandbox/src/sandbox.ts
+++ b/tools/loop-sandbox/src/sandbox.ts
@@ -104,15 +104,42 @@ export async function runInSandbox(root: string, command: string, args: string[]
try {
// 3. Execute the user's command
try {
- const child = spawn(command, args, {
- cwd: worktreeAbsPath,
- stdio: 'inherit',
- shell: options.shell ?? false
- });
-
exitCode = await new Promise<number | null>((resolve) => {
- child.on('close', (code) => resolve(code));
- child.on('error', () => resolve(1));
+ // 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: boolean) => {
+ const child = spawn(command, args, {
+ cwd: worktreeAbsPath,
+ stdio: 'inherit',
+ shell: useShell
+ });
+
+ child.on('close', (code) => {
+ if (!useShell && supersededByRetry) return;
+ resolve(code);
+ });
+ child.on('error', (err: NodeJS.ErrnoException) => {
+ 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;
+ }
+ resolve(1);
+ });
+ };
+ attempt(options.shell ?? false);
});
} catch (err) {
console.error(`❌ Execution failed inside sandbox:`, err);