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
feat(loop-worktree): manage isolated git worktrees per fix attempt (#190)
JonyT3eac4e70b6a1
diff --git a/.gitignore b/.gitignoreindex ff1a8f7..0d32bfe 100644--- a/.gitignore+++ b/.gitignore@@ -33,6 +33,7 @@ build/!tools/mcp-server/dist/!tools/loop-context/dist/!tools/goal-audit/dist/+!tools/loop-worktree/dist/*.egg-info/# State files that should not be committed in consumer projects (reference repo dogfoods STATE.md)diff --git a/README.md b/README.mdindex b6894d5..af4c94d 100644--- a/README.md+++ b/README.md@@ -91,6 +91,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` || [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` || [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server` |+| [loop-worktree](tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>` || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) || [Stories](stories/) | Real wins and honest failures || [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 12 scoped `good first issues` — comment *I'll take this* to get assigned |diff --git a/docs/primitives.md b/docs/primitives.mdindex 0a8105e..d743d85 100644--- a/docs/primitives.md+++ b/docs/primitives.md@@ -23,7 +23,7 @@ When two agents edit the same files at the same time you get merge hell. Git worIn Grok: pass `isolation: "worktree"` when spawning subagents, or use `--worktree` / dedicated sessions.-Cleanup is important — loops should delete the worktree when the task is done or handed off.+Cleanup is important — loops should delete the worktree when the task is done or handed off. The [loop-worktree](../tools/loop-worktree/) CLI makes this mechanical: one worktree per attempt, tracked in a manifest, swept on reject or escalation.## 3. Skillsdiff --git a/package.json b/package.jsonindex 127a53f..986c7b9 100644--- a/package.json+++ b/package.json@@ -11,8 +11,9 @@"test:loop-sync": "cd tools/loop-sync && npm test","test:loop-context": "cd tools/loop-context && npm test","test:mcp-server": "cd tools/mcp-server && npm test",- "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:loop-context && npm run test:mcp-server",- "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build",+ "test:loop-worktree": "cd tools/loop-worktree && npm test",+ "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:loop-context && npm run test:mcp-server && npm run test:loop-worktree",+ "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build && cd ../loop-worktree && npm run build","contributors:generate": "node scripts/generate-contributors.mjs","contributors:check": "node scripts/generate-contributors.mjs --check"},diff --git a/tools/loop-worktree/README.md b/tools/loop-worktree/README.mdnew file mode 100644index 0000000..0589488--- /dev/null+++ b/tools/loop-worktree/README.md@@ -0,0 +1,86 @@+# loop-worktree++Manage isolated [git worktrees](https://git-scm.com/docs/git-worktree) for loop engineering attempts. One worktree per fix attempt; mark it when the verifier rejects or a human escalates; sweep the discarded ones.++`LOOP.md` and `docs/primitives.md` describe this convention in prose ("one worktree per fix; discard after verifier REJECT or human escalation"). This tool is the code behind it: a shared place for worktrees to live, a manifest that tracks their status, and a reconciler that sweeps orphans.++## Install & Run++```bash+npx @cobusgreyling/loop-worktree create --run-id ci-sweeper-2026-07-07-01 --pattern ci-sweeper+npx @cobusgreyling/loop-worktree list+```++**From this repo:**++```bash+cd tools/loop-worktree+npm install+npm test+```++## Commands++```bash+loop-worktree create --run-id <id> --pattern <p> [--base main]+ # git worktree add -b loop/<id> .loop-worktrees/<id> <base>, records the manifest entry++loop-worktree mark --run-id <id> --status rejected+ # updates the manifest only (audit trail); does not delete the worktree++loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]+ # git worktree remove for matching entries, then prunes them from the manifest++loop-worktree gc [--force] [--json]+ # reconciles `git worktree list` against the manifest:+ # - on disk under .loop-worktrees/ but not in the manifest -> reported as an orphan+ # - in the manifest but not on disk -> dropped from the manifest+ # report-only by default; --force removes orphans++loop-worktree list [--status active] [--json]+```++## Status++An entry is one of: `active`, `rejected`, `escalated`, `merged`, `stale`.++`cleanup` sweeps `rejected` and `escalated` by default. `active` is never swept automatically.++## Safety++- `create` fails with a clear message (not a raw git error) if the directory is not a git repo, or if `--run-id` already has an active worktree.+- `cleanup` runs `git worktree remove` without `--force` first, so git refuses to delete a worktree with uncommitted or untracked changes; that entry is reported as skipped. Pass `--force` only when you accept the data loss.+- `gc` is report-only by default, matching the repo's convention that anything scanning broadly reports rather than acts.++## Pairing with loop-context++A loop's control script that calls [`loop-context`](../loop-context) `--check` and escalates should also mark its worktree:++```bash+loop-worktree mark --run-id "$RUN_ID" --status escalated+```++The two tools stay independent: `loop-worktree` does not read the ledger, and `loop-context` does not know about git.++## Manifest++`.loop-worktrees/manifest.json` (add `.loop-worktrees/` to `.gitignore`):++```json+{+ "version": 1,+ "worktrees": [+ {+ "id": "ci-sweeper-2026-07-07-01",+ "path": ".loop-worktrees/ci-sweeper-2026-07-07-01",+ "branch": "loop/ci-sweeper-2026-07-07-01",+ "baseBranch": "main",+ "pattern": "ci-sweeper",+ "createdAt": "2026-07-07T08:00:00.000Z",+ "status": "active"+ }+ ]+}+```++See [docs/primitives.md](../../docs/primitives.md) for where worktrees fit in the Five Building Blocks + Memory model.diff --git a/tools/loop-worktree/dist/cli.d.ts b/tools/loop-worktree/dist/cli.d.tsnew file mode 100644index 0000000..b798801--- /dev/null+++ b/tools/loop-worktree/dist/cli.d.ts@@ -0,0 +1,2 @@+#!/usr/bin/env node+export {};diff --git a/tools/loop-worktree/dist/cli.js b/tools/loop-worktree/dist/cli.jsnew file mode 100644index 0000000..87516cd--- /dev/null+++ b/tools/loop-worktree/dist/cli.js@@ -0,0 +1,142 @@+#!/usr/bin/env node+import { createWorktree, markWorktree, cleanupWorktrees, gc, listWorktrees, VALID_STATUSES, } from './worktree.js';+function parseFlags(argv) {+ const flags = { root: process.cwd(), force: false, json: false };+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--run-id')+ flags.runId = argv[++i];+ else if (a === '--pattern')+ flags.pattern = argv[++i];+ else if (a === '--base')+ flags.base = argv[++i];+ else if (a === '--status')+ flags.status = argv[++i];+ else if (a === '--older-than')+ flags.olderThan = argv[++i];+ else if (a === '--root')+ flags.root = argv[++i];+ else if (a === '--force')+ flags.force = true;+ else if (a === '--json')+ flags.json = true;+ }+ return flags;+}+function parseStatuses(csv) {+ return csv.split(',').map((s) => {+ const t = s.trim();+ if (!VALID_STATUSES.includes(t)) {+ throw new Error(`Invalid status "${t}". Use: ${VALID_STATUSES.join(', ')}.`);+ }+ return t;+ });+}+const HELP = `loop-worktree - manage isolated git worktrees for loop attempts++Usage:+ loop-worktree create --run-id <id> --pattern <p> [--base main]+ loop-worktree mark --run-id <id> --status <${VALID_STATUSES.join('|')}>+ loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]+ loop-worktree gc [--force] [--json]+ loop-worktree list [--status <s>] [--json]++Common flags:+ --root <dir> Repo root to operate in (default: cwd)+ --json Machine-readable output (list, gc)+ --force Allow removing worktrees with uncommitted changes / orphans++Worktrees live under .loop-worktrees/, tracked in .loop-worktrees/manifest.json.+Add .loop-worktrees/ to .gitignore.`;+async function main() {+ const argv = process.argv.slice(2);+ const command = argv[0];+ if (!command || command === '--help' || command === '-h') {+ console.log(HELP);+ return command ? 0 : 1;+ }+ const flags = parseFlags(argv.slice(1));+ switch (command) {+ case 'create': {+ if (!flags.runId || !flags.pattern) {+ throw new Error('create requires --run-id and --pattern.');+ }+ const entry = await createWorktree({+ root: flags.root,+ runId: flags.runId,+ pattern: flags.pattern,+ base: flags.base,+ });+ console.log(`created worktree ${entry.path} on branch ${entry.branch} (base ${entry.baseBranch})`);+ return 0;+ }+ case 'mark': {+ if (!flags.runId || !flags.status) {+ throw new Error('mark requires --run-id and --status.');+ }+ const entry = await markWorktree({+ root: flags.root,+ runId: flags.runId,+ status: flags.status,+ });+ console.log(`marked ${entry.id} as ${entry.status}`);+ return 0;+ }+ case 'cleanup': {+ const result = await cleanupWorktrees({+ root: flags.root,+ statuses: flags.status ? parseStatuses(flags.status) : undefined,+ olderThan: flags.olderThan,+ force: flags.force,+ });+ for (const e of result.removed)+ console.log(`removed ${e.path} (${e.status})`);+ for (const s of result.skipped)+ console.log(`skipped ${s.entry.path}: ${s.reason}`);+ console.log(`cleanup: ${result.removed.length} removed, ${result.skipped.length} skipped`);+ return 0;+ }+ case 'gc': {+ const result = await gc({ root: flags.root, force: flags.force });+ if (flags.json) {+ console.log(JSON.stringify(result, null, 2));+ return 0;+ }+ for (const o of result.orphans) {+ console.log(result.removedOrphans.includes(o) ? `removed orphan ${o}` : `orphan ${o}`);+ }+ for (const d of result.dropped)+ console.log(`dropped stale manifest entry ${d.id}`);+ console.log(`gc: ${result.orphans.length} orphan(s), ${result.dropped.length} dropped` ++ (flags.force ? `, ${result.removedOrphans.length} removed` : ' (report-only; use --force to remove orphans)'));+ return 0;+ }+ case 'list': {+ const entries = await listWorktrees({+ root: flags.root,+ status: flags.status,+ });+ if (flags.json) {+ console.log(JSON.stringify(entries, null, 2));+ return 0;+ }+ if (entries.length === 0) {+ console.log('no worktrees tracked');+ return 0;+ }+ for (const e of entries) {+ console.log(`${e.status.padEnd(9)} ${e.id} ${e.branch} (${e.pattern})`);+ }+ return 0;+ }+ default:+ console.error(`Unknown command "${command}".\n\n${HELP}`);+ return 1;+ }+}+main()+ .then((code) => process.exit(code))+ .catch((err) => {+ console.error(err instanceof Error ? err.message : String(err));+ process.exit(1);+});diff --git a/tools/loop-worktree/dist/worktree.d.ts b/tools/loop-worktree/dist/worktree.d.tsnew file mode 100644index 0000000..a27ee4c--- /dev/null+++ b/tools/loop-worktree/dist/worktree.d.ts@@ -0,0 +1,69 @@+export declare const MANIFEST_DIR = ".loop-worktrees";+export declare const MANIFEST_FILE: string;+export type WorktreeStatus = 'active' | 'rejected' | 'escalated' | 'merged' | 'stale';+export declare const VALID_STATUSES: WorktreeStatus[];+/** Terminal states cleanup discards by default; "active" is never swept automatically. */+export declare const CLEANUP_DEFAULT_STATUSES: WorktreeStatus[];+export interface WorktreeEntry {+ id: string;+ /** Repo-relative, posix-style path to the worktree. */+ path: string;+ branch: string;+ baseBranch: string;+ pattern: string;+ createdAt: string;+ status: WorktreeStatus;+}+export interface Manifest {+ version: 1;+ worktrees: WorktreeEntry[];+}+export declare function isGitRepo(cwd: string): Promise<boolean>;+export declare function readManifest(root: string): Promise<Manifest>;+export declare function writeManifest(root: string, manifest: Manifest): Promise<void>;+export interface CreateInput {+ root: string;+ runId: string;+ pattern: string;+ base?: string;+}+export declare function createWorktree(input: CreateInput): Promise<WorktreeEntry>;+export interface MarkInput {+ root: string;+ runId: string;+ status: WorktreeStatus;+}+export declare function markWorktree(input: MarkInput): Promise<WorktreeEntry>;+export interface CleanupInput {+ root: string;+ statuses?: WorktreeStatus[];+ olderThan?: string;+ force?: boolean;+}+export interface CleanupResult {+ removed: WorktreeEntry[];+ /** Entries git refused to remove (e.g. uncommitted changes) without --force. */+ skipped: {+ entry: WorktreeEntry;+ reason: string;+ }[];+}+export declare function cleanupWorktrees(input: CleanupInput): Promise<CleanupResult>;+export interface GcInput {+ root: string;+ force?: boolean;+}+export interface GcResult {+ /** On disk under .loop-worktrees but absent from the manifest. */+ orphans: string[];+ /** In the manifest but no longer on disk; dropped from the manifest. */+ dropped: WorktreeEntry[];+ /** Orphans actually removed (only when force is set). */+ removedOrphans: string[];+}+export declare function gc(input: GcInput): Promise<GcResult>;+export interface ListInput {+ root: string;+ status?: WorktreeStatus;+}+export declare function listWorktrees(input: ListInput): Promise<WorktreeEntry[]>;diff --git a/tools/loop-worktree/dist/worktree.js b/tools/loop-worktree/dist/worktree.jsnew file mode 100644index 0000000..b99428e--- /dev/null+++ b/tools/loop-worktree/dist/worktree.js@@ -0,0 +1,201 @@+import { execFile } from 'node:child_process';+import { promisify } from 'node:util';+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';+import path from 'node:path';+const run = promisify(execFile);+export const MANIFEST_DIR = '.loop-worktrees';+export const MANIFEST_FILE = path.posix.join(MANIFEST_DIR, 'manifest.json');+export const VALID_STATUSES = [+ 'active',+ 'rejected',+ 'escalated',+ 'merged',+ 'stale',+];+/** Terminal states cleanup discards by default; "active" is never swept automatically. */+export const CLEANUP_DEFAULT_STATUSES = ['rejected', 'escalated'];+function emptyManifest() {+ return { version: 1, worktrees: [] };+}+async function exists(p) {+ try {+ await access(p);+ return true;+ }+ catch {+ return false;+ }+}+/** Run git in `cwd`, returning trimmed stdout. Throws a clean Error on failure. */+async function git(args, cwd) {+ try {+ const { stdout } = await run('git', args, { cwd, maxBuffer: 10 * 1024 * 1024 });+ return stdout.trim();+ }+ catch (err) {+ const e = err;+ const detail = (e.stderr || e.message || '').trim();+ throw new Error(`git ${args.join(' ')} failed: ${detail}`);+ }+}+export async function isGitRepo(cwd) {+ try {+ const out = await git(['rev-parse', '--is-inside-work-tree'], cwd);+ return out === 'true';+ }+ catch {+ return false;+ }+}+async function assertGitRepo(root) {+ if (!(await isGitRepo(root))) {+ throw new Error(`Not a git repository: ${root}. loop-worktree manages git worktrees and must run inside a repo.`);+ }+}+export async function readManifest(root) {+ const file = path.join(root, MANIFEST_FILE);+ if (!(await exists(file)))+ return emptyManifest();+ const raw = await readFile(file, 'utf8');+ const parsed = JSON.parse(raw);+ if (parsed.version !== 1 || !Array.isArray(parsed.worktrees)) {+ throw new Error(`Invalid manifest at ${MANIFEST_FILE}: expected { version: 1, worktrees: [] }.`);+ }+ return parsed;+}+export async function writeManifest(root, manifest) {+ const dir = path.join(root, MANIFEST_DIR);+ await mkdir(dir, { recursive: true });+ const file = path.join(root, MANIFEST_FILE);+ await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`);+}+export async function createWorktree(input) {+ const { root, runId, pattern } = input;+ const base = input.base ?? 'main';+ await assertGitRepo(root);+ const manifest = await readManifest(root);+ const existing = manifest.worktrees.find((w) => w.id === runId);+ if (existing && existing.status === 'active') {+ throw new Error(`Run id "${runId}" already has an active worktree at ${existing.path}.`);+ }+ const relPath = path.posix.join(MANIFEST_DIR, runId);+ const branch = `loop/${runId}`;+ // `git worktree add -b <branch> <path> <base>` creates the branch and checks it+ // out in an isolated worktree. Forward-slash paths are accepted on all platforms.+ await git(['worktree', 'add', '-b', branch, relPath, base], root);+ const entry = {+ id: runId,+ path: relPath,+ branch,+ baseBranch: base,+ pattern,+ createdAt: new Date().toISOString(),+ status: 'active',+ };+ manifest.worktrees = manifest.worktrees.filter((w) => w.id !== runId);+ manifest.worktrees.push(entry);+ await writeManifest(root, manifest);+ return entry;+}+export async function markWorktree(input) {+ const { root, runId, status } = input;+ if (!VALID_STATUSES.includes(status)) {+ throw new Error(`Invalid status "${status}". Use one of: ${VALID_STATUSES.join(', ')}.`);+ }+ const manifest = await readManifest(root);+ const entry = manifest.worktrees.find((w) => w.id === runId);+ if (!entry) {+ throw new Error(`No worktree with run id "${runId}" in ${MANIFEST_FILE}.`);+ }+ entry.status = status;+ await writeManifest(root, manifest);+ return entry;+}+function parseInterval(token) {+ const m = /^(\d+)([mhd])$/.exec(token.trim());+ if (!m) {+ throw new Error(`Invalid --older-than "${token}". Use e.g. 30m, 24h, 7d.`);+ }+ const n = Number(m[1]);+ const unit = m[2];+ const ms = unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;+ return n * ms;+}+export async function cleanupWorktrees(input) {+ const { root } = input;+ await assertGitRepo(root);+ const statuses = input.statuses ?? CLEANUP_DEFAULT_STATUSES;+ const cutoff = input.olderThan ? Date.now() - parseInterval(input.olderThan) : undefined;+ const manifest = await readManifest(root);+ const removed = [];+ const skipped = [];+ for (const entry of manifest.worktrees) {+ if (!statuses.includes(entry.status))+ continue;+ if (cutoff !== undefined && Date.parse(entry.createdAt) > cutoff)+ continue;+ const args = ['worktree', 'remove', entry.path];+ if (input.force)+ args.push('--force');+ try {+ // Without --force, git refuses to remove a worktree with uncommitted or+ // untracked changes. We surface that refusal instead of forcing data loss.+ await git(args, root);+ removed.push(entry);+ }+ catch (err) {+ skipped.push({ entry, reason: err.message });+ }+ }+ const removedIds = new Set(removed.map((e) => e.id));+ manifest.worktrees = manifest.worktrees.filter((w) => !removedIds.has(w.id));+ await writeManifest(root, manifest);+ return { removed, skipped };+}+/** Paths (repo-relative, posix) of every worktree git currently knows about. */+async function gitWorktreePaths(root) {+ const out = await git(['worktree', 'list', '--porcelain'], root);+ const paths = [];+ for (const line of out.split('\n')) {+ if (!line.startsWith('worktree '))+ continue;+ const abs = line.slice('worktree '.length).trim();+ const rel = path.relative(root, abs).split(path.sep).join('/');+ paths.push(rel);+ }+ return paths;+}+export async function gc(input) {+ const { root } = input;+ await assertGitRepo(root);+ const manifest = await readManifest(root);+ const onDisk = await gitWorktreePaths(root);+ const managedOnDisk = onDisk.filter((p) => p.startsWith(`${MANIFEST_DIR}/`));+ const manifestPaths = new Set(manifest.worktrees.map((w) => w.path));+ const orphans = managedOnDisk.filter((p) => !manifestPaths.has(p));+ const dropped = manifest.worktrees.filter((w) => !onDisk.includes(w.path));+ const removedOrphans = [];+ if (input.force) {+ for (const orphan of orphans) {+ try {+ await git(['worktree', 'remove', '--force', orphan], root);+ removedOrphans.push(orphan);+ }+ catch {+ // Leave it reported as an orphan if git still refuses.+ }+ }+ }+ if (dropped.length > 0) {+ const droppedIds = new Set(dropped.map((e) => e.id));+ manifest.worktrees = manifest.worktrees.filter((w) => !droppedIds.has(w.id));+ await writeManifest(root, manifest);+ }+ return { orphans, dropped, removedOrphans };+}+export async function listWorktrees(input) {+ const manifest = await readManifest(input.root);+ if (!input.status)+ return manifest.worktrees;+ return manifest.worktrees.filter((w) => w.status === input.status);+}diff --git a/tools/loop-worktree/package-lock.json b/tools/loop-worktree/package-lock.jsonnew file mode 100644index 0000000..b227b85--- /dev/null+++ b/tools/loop-worktree/package-lock.json@@ -0,0 +1,54 @@+{+ "name": "@cobusgreyling/loop-worktree",+ "version": "1.0.0",+ "lockfileVersion": 3,+ "requires": true,+ "packages": {+ "": {+ "name": "@cobusgreyling/loop-worktree",+ "version": "1.0.0",+ "license": "MIT",+ "bin": {+ "loop-worktree": "dist/cli.js"+ },+ "devDependencies": {+ "@types/node": "^20.0.0",+ "typescript": "^5.0.0"+ },+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@types/node": {+ "version": "20.19.43",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",+ "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },+ "node_modules/typescript": {+ "version": "5.9.3",+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "tsc": "bin/tsc",+ "tsserver": "bin/tsserver"+ },+ "engines": {+ "node": ">=14.17"+ }+ },+ "node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "dev": true,+ "license": "MIT"+ }+ }+}diff --git a/tools/loop-worktree/package.json b/tools/loop-worktree/package.jsonnew file mode 100644index 0000000..2c1181b--- /dev/null+++ b/tools/loop-worktree/package.json@@ -0,0 +1,50 @@+{+ "name": "@cobusgreyling/loop-worktree",+ "version": "1.0.0",+ "description": "Manage isolated git worktrees for loop engineering attempts: create, mark, cleanup, and reconcile one worktree per fix attempt.",+ "type": "module",+ "bin": {+ "loop-worktree": "dist/cli.js"+ },+ "files": [+ "dist",+ "README.md"+ ],+ "scripts": {+ "build": "tsc && chmod +x dist/cli.js",+ "test": "npm run build && node --test test/worktree.test.mjs",+ "prepublishOnly": "npm test",+ "start": "node dist/cli.js"+ },+ "engines": {+ "node": ">=18"+ },+ "keywords": [+ "loop-engineering",+ "ai-agents",+ "coding-agents",+ "git-worktree",+ "worktree",+ "claude-code",+ "grok",+ "devtools"+ ],+ "author": "Cobus Greyling",+ "license": "MIT",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",+ "directory": "tools/loop-worktree"+ },+ "homepage": "https://cobusgreyling.github.io/loop-engineering/",+ "bugs": {+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"+ },+ "publishConfig": {+ "access": "public"+ },+ "devDependencies": {+ "@types/node": "^20.0.0",+ "typescript": "^5.0.0"+ }+}diff --git a/tools/loop-worktree/src/cli.ts b/tools/loop-worktree/src/cli.tsnew file mode 100644index 0000000..8510aaa--- /dev/null+++ b/tools/loop-worktree/src/cli.ts@@ -0,0 +1,159 @@+#!/usr/bin/env node+import {+ createWorktree,+ markWorktree,+ cleanupWorktrees,+ gc,+ listWorktrees,+ VALID_STATUSES,+ type WorktreeStatus,+} from './worktree.js';++interface Flags {+ root: string;+ runId?: string;+ pattern?: string;+ base?: string;+ status?: string;+ olderThan?: string;+ force: boolean;+ json: boolean;+}++function parseFlags(argv: string[]): Flags {+ const flags: Flags = { root: process.cwd(), force: false, json: false };+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--run-id') flags.runId = argv[++i];+ else if (a === '--pattern') flags.pattern = argv[++i];+ else if (a === '--base') flags.base = argv[++i];+ else if (a === '--status') flags.status = argv[++i];+ else if (a === '--older-than') flags.olderThan = argv[++i];+ else if (a === '--root') flags.root = argv[++i];+ else if (a === '--force') flags.force = true;+ else if (a === '--json') flags.json = true;+ }+ return flags;+}++function parseStatuses(csv: string): WorktreeStatus[] {+ return csv.split(',').map((s) => {+ const t = s.trim() as WorktreeStatus;+ if (!VALID_STATUSES.includes(t)) {+ throw new Error(`Invalid status "${t}". Use: ${VALID_STATUSES.join(', ')}.`);+ }+ return t;+ });+}++const HELP = `loop-worktree - manage isolated git worktrees for loop attempts++Usage:+ loop-worktree create --run-id <id> --pattern <p> [--base main]+ loop-worktree mark --run-id <id> --status <${VALID_STATUSES.join('|')}>+ loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]+ loop-worktree gc [--force] [--json]+ loop-worktree list [--status <s>] [--json]++Common flags:+ --root <dir> Repo root to operate in (default: cwd)+ --json Machine-readable output (list, gc)+ --force Allow removing worktrees with uncommitted changes / orphans++Worktrees live under .loop-worktrees/, tracked in .loop-worktrees/manifest.json.+Add .loop-worktrees/ to .gitignore.`;++async function main(): Promise<number> {+ const argv = process.argv.slice(2);+ const command = argv[0];+ if (!command || command === '--help' || command === '-h') {+ console.log(HELP);+ return command ? 0 : 1;+ }++ const flags = parseFlags(argv.slice(1));++ switch (command) {+ case 'create': {+ if (!flags.runId || !flags.pattern) {+ throw new Error('create requires --run-id and --pattern.');+ }+ const entry = await createWorktree({+ root: flags.root,+ runId: flags.runId,+ pattern: flags.pattern,+ base: flags.base,+ });+ console.log(`created worktree ${entry.path} on branch ${entry.branch} (base ${entry.baseBranch})`);+ return 0;+ }+ case 'mark': {+ if (!flags.runId || !flags.status) {+ throw new Error('mark requires --run-id and --status.');+ }+ const entry = await markWorktree({+ root: flags.root,+ runId: flags.runId,+ status: flags.status as WorktreeStatus,+ });+ console.log(`marked ${entry.id} as ${entry.status}`);+ return 0;+ }+ case 'cleanup': {+ const result = await cleanupWorktrees({+ root: flags.root,+ statuses: flags.status ? parseStatuses(flags.status) : undefined,+ olderThan: flags.olderThan,+ force: flags.force,+ });+ for (const e of result.removed) console.log(`removed ${e.path} (${e.status})`);+ for (const s of result.skipped) console.log(`skipped ${s.entry.path}: ${s.reason}`);+ console.log(`cleanup: ${result.removed.length} removed, ${result.skipped.length} skipped`);+ return 0;+ }+ case 'gc': {+ const result = await gc({ root: flags.root, force: flags.force });+ if (flags.json) {+ console.log(JSON.stringify(result, null, 2));+ return 0;+ }+ for (const o of result.orphans) {+ console.log(result.removedOrphans.includes(o) ? `removed orphan ${o}` : `orphan ${o}`);+ }+ for (const d of result.dropped) console.log(`dropped stale manifest entry ${d.id}`);+ console.log(+ `gc: ${result.orphans.length} orphan(s), ${result.dropped.length} dropped` ++ (flags.force ? `, ${result.removedOrphans.length} removed` : ' (report-only; use --force to remove orphans)'),+ );+ return 0;+ }+ case 'list': {+ const entries = await listWorktrees({+ root: flags.root,+ status: flags.status as WorktreeStatus | undefined,+ });+ if (flags.json) {+ console.log(JSON.stringify(entries, null, 2));+ return 0;+ }+ if (entries.length === 0) {+ console.log('no worktrees tracked');+ return 0;+ }+ for (const e of entries) {+ console.log(`${e.status.padEnd(9)} ${e.id} ${e.branch} (${e.pattern})`);+ }+ return 0;+ }+ default:+ console.error(`Unknown command "${command}".\n\n${HELP}`);+ return 1;+ }+}++main()+ .then((code) => process.exit(code))+ .catch((err) => {+ console.error(err instanceof Error ? err.message : String(err));+ process.exit(1);+ });diff --git a/tools/loop-worktree/src/worktree.ts b/tools/loop-worktree/src/worktree.tsnew file mode 100644index 0000000..2fb8c05--- /dev/null+++ b/tools/loop-worktree/src/worktree.ts@@ -0,0 +1,284 @@+import { execFile } from 'node:child_process';+import { promisify } from 'node:util';+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';+import path from 'node:path';++const run = promisify(execFile);++export const MANIFEST_DIR = '.loop-worktrees';+export const MANIFEST_FILE = path.posix.join(MANIFEST_DIR, 'manifest.json');++export type WorktreeStatus = 'active' | 'rejected' | 'escalated' | 'merged' | 'stale';++export const VALID_STATUSES: WorktreeStatus[] = [+ 'active',+ 'rejected',+ 'escalated',+ 'merged',+ 'stale',+];++/** Terminal states cleanup discards by default; "active" is never swept automatically. */+export const CLEANUP_DEFAULT_STATUSES: WorktreeStatus[] = ['rejected', 'escalated'];++export interface WorktreeEntry {+ id: string;+ /** Repo-relative, posix-style path to the worktree. */+ path: string;+ branch: string;+ baseBranch: string;+ pattern: string;+ createdAt: string;+ status: WorktreeStatus;+}++export interface Manifest {+ version: 1;+ worktrees: WorktreeEntry[];+}++function emptyManifest(): Manifest {+ return { version: 1, worktrees: [] };+}++async function exists(p: string): Promise<boolean> {+ try {+ await access(p);+ return true;+ } catch {+ return false;+ }+}++/** Run git in `cwd`, returning trimmed stdout. Throws a clean Error on failure. */+async function git(args: string[], cwd: string): Promise<string> {+ try {+ const { stdout } = await run('git', args, { cwd, maxBuffer: 10 * 1024 * 1024 });+ return stdout.trim();+ } catch (err) {+ const e = err as { stderr?: string; message?: string };+ const detail = (e.stderr || e.message || '').trim();+ throw new Error(`git ${args.join(' ')} failed: ${detail}`);+ }+}++export async function isGitRepo(cwd: string): Promise<boolean> {+ try {+ const out = await git(['rev-parse', '--is-inside-work-tree'], cwd);+ return out === 'true';+ } catch {+ return false;+ }+}++async function assertGitRepo(root: string): Promise<void> {+ if (!(await isGitRepo(root))) {+ throw new Error(+ `Not a git repository: ${root}. loop-worktree manages git worktrees and must run inside a repo.`,+ );+ }+}++export async function readManifest(root: string): Promise<Manifest> {+ const file = path.join(root, MANIFEST_FILE);+ if (!(await exists(file))) return emptyManifest();+ const raw = await readFile(file, 'utf8');+ const parsed = JSON.parse(raw) as Manifest;+ if (parsed.version !== 1 || !Array.isArray(parsed.worktrees)) {+ throw new Error(`Invalid manifest at ${MANIFEST_FILE}: expected { version: 1, worktrees: [] }.`);+ }+ return parsed;+}++export async function writeManifest(root: string, manifest: Manifest): Promise<void> {+ const dir = path.join(root, MANIFEST_DIR);+ await mkdir(dir, { recursive: true });+ const file = path.join(root, MANIFEST_FILE);+ await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`);+}++export interface CreateInput {+ root: string;+ runId: string;+ pattern: string;+ base?: string;+}++export async function createWorktree(input: CreateInput): Promise<WorktreeEntry> {+ const { root, runId, pattern } = input;+ const base = input.base ?? 'main';+ await assertGitRepo(root);++ const manifest = await readManifest(root);+ const existing = manifest.worktrees.find((w) => w.id === runId);+ if (existing && existing.status === 'active') {+ throw new Error(`Run id "${runId}" already has an active worktree at ${existing.path}.`);+ }++ const relPath = path.posix.join(MANIFEST_DIR, runId);+ const branch = `loop/${runId}`;+ // `git worktree add -b <branch> <path> <base>` creates the branch and checks it+ // out in an isolated worktree. Forward-slash paths are accepted on all platforms.+ await git(['worktree', 'add', '-b', branch, relPath, base], root);++ const entry: WorktreeEntry = {+ id: runId,+ path: relPath,+ branch,+ baseBranch: base,+ pattern,+ createdAt: new Date().toISOString(),+ status: 'active',+ };+ manifest.worktrees = manifest.worktrees.filter((w) => w.id !== runId);+ manifest.worktrees.push(entry);+ await writeManifest(root, manifest);+ return entry;+}++export interface MarkInput {+ root: string;+ runId: string;+ status: WorktreeStatus;+}++export async function markWorktree(input: MarkInput): Promise<WorktreeEntry> {+ const { root, runId, status } = input;+ if (!VALID_STATUSES.includes(status)) {+ throw new Error(`Invalid status "${status}". Use one of: ${VALID_STATUSES.join(', ')}.`);+ }+ const manifest = await readManifest(root);+ const entry = manifest.worktrees.find((w) => w.id === runId);+ if (!entry) {+ throw new Error(`No worktree with run id "${runId}" in ${MANIFEST_FILE}.`);+ }+ entry.status = status;+ await writeManifest(root, manifest);+ return entry;+}++function parseInterval(token: string): number {+ const m = /^(\d+)([mhd])$/.exec(token.trim());+ if (!m) {+ throw new Error(`Invalid --older-than "${token}". Use e.g. 30m, 24h, 7d.`);+ }+ const n = Number(m[1]);+ const unit = m[2];+ const ms = unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;+ return n * ms;+}++export interface CleanupInput {+ root: string;+ statuses?: WorktreeStatus[];+ olderThan?: string;+ force?: boolean;+}++export interface CleanupResult {+ removed: WorktreeEntry[];+ /** Entries git refused to remove (e.g. uncommitted changes) without --force. */+ skipped: { entry: WorktreeEntry; reason: string }[];+}++export async function cleanupWorktrees(input: CleanupInput): Promise<CleanupResult> {+ const { root } = input;+ await assertGitRepo(root);+ const statuses = input.statuses ?? CLEANUP_DEFAULT_STATUSES;+ const cutoff = input.olderThan ? Date.now() - parseInterval(input.olderThan) : undefined;++ const manifest = await readManifest(root);+ const removed: WorktreeEntry[] = [];+ const skipped: { entry: WorktreeEntry; reason: string }[] = [];++ for (const entry of manifest.worktrees) {+ if (!statuses.includes(entry.status)) continue;+ if (cutoff !== undefined && Date.parse(entry.createdAt) > cutoff) continue;++ const args = ['worktree', 'remove', entry.path];+ if (input.force) args.push('--force');+ try {+ // Without --force, git refuses to remove a worktree with uncommitted or+ // untracked changes. We surface that refusal instead of forcing data loss.+ await git(args, root);+ removed.push(entry);+ } catch (err) {+ skipped.push({ entry, reason: (err as Error).message });+ }+ }++ const removedIds = new Set(removed.map((e) => e.id));+ manifest.worktrees = manifest.worktrees.filter((w) => !removedIds.has(w.id));+ await writeManifest(root, manifest);+ return { removed, skipped };+}++/** Paths (repo-relative, posix) of every worktree git currently knows about. */+async function gitWorktreePaths(root: string): Promise<string[]> {+ const out = await git(['worktree', 'list', '--porcelain'], root);+ const paths: string[] = [];+ for (const line of out.split('\n')) {+ if (!line.startsWith('worktree ')) continue;+ const abs = line.slice('worktree '.length).trim();+ const rel = path.relative(root, abs).split(path.sep).join('/');+ paths.push(rel);+ }+ return paths;+}++export interface GcInput {+ root: string;+ force?: boolean;+}++export interface GcResult {+ /** On disk under .loop-worktrees but absent from the manifest. */+ orphans: string[];+ /** In the manifest but no longer on disk; dropped from the manifest. */+ dropped: WorktreeEntry[];+ /** Orphans actually removed (only when force is set). */+ removedOrphans: string[];+}++export async function gc(input: GcInput): Promise<GcResult> {+ const { root } = input;+ await assertGitRepo(root);+ const manifest = await readManifest(root);+ const onDisk = await gitWorktreePaths(root);+ const managedOnDisk = onDisk.filter((p) => p.startsWith(`${MANIFEST_DIR}/`));+ const manifestPaths = new Set(manifest.worktrees.map((w) => w.path));++ const orphans = managedOnDisk.filter((p) => !manifestPaths.has(p));+ const dropped = manifest.worktrees.filter((w) => !onDisk.includes(w.path));++ const removedOrphans: string[] = [];+ if (input.force) {+ for (const orphan of orphans) {+ try {+ await git(['worktree', 'remove', '--force', orphan], root);+ removedOrphans.push(orphan);+ } catch {+ // Leave it reported as an orphan if git still refuses.+ }+ }+ }++ if (dropped.length > 0) {+ const droppedIds = new Set(dropped.map((e) => e.id));+ manifest.worktrees = manifest.worktrees.filter((w) => !droppedIds.has(w.id));+ await writeManifest(root, manifest);+ }++ return { orphans, dropped, removedOrphans };+}++export interface ListInput {+ root: string;+ status?: WorktreeStatus;+}++export async function listWorktrees(input: ListInput): Promise<WorktreeEntry[]> {+ const manifest = await readManifest(input.root);+ if (!input.status) return manifest.worktrees;+ return manifest.worktrees.filter((w) => w.status === input.status);+}diff --git a/tools/loop-worktree/test/worktree.test.mjs b/tools/loop-worktree/test/worktree.test.mjsnew file mode 100644index 0000000..9ee1791--- /dev/null+++ b/tools/loop-worktree/test/worktree.test.mjs@@ -0,0 +1,182 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdtemp, rm, writeFile, access } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { execFile } from 'node:child_process';+import { promisify } from 'node:util';++import {+ createWorktree,+ markWorktree,+ cleanupWorktrees,+ gc,+ listWorktrees,+ readManifest,+ isGitRepo,+} from '../dist/worktree.js';++const run = promisify(execFile);++async function git(args, cwd) {+ await run('git', args, { cwd });+}++async function initRepo() {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-worktree-'));+ await git(['init', '-b', 'main'], dir);+ await git(['config', 'user.email', '[email protected]'], dir);+ await git(['config', 'user.name', 'Test'], dir);+ await git(['commit', '--allow-empty', '-m', 'init'], dir);+ return dir;+}++async function exists(p) {+ try {+ await access(p);+ return true;+ } catch {+ return false;+ }+}++test('create records a manifest entry and checks out the worktree', async () => {+ const dir = await initRepo();+ try {+ const entry = await createWorktree({ root: dir, runId: 'run-1', pattern: 'ci-sweeper' });+ assert.equal(entry.status, 'active');+ assert.equal(entry.branch, 'loop/run-1');+ assert.equal(entry.baseBranch, 'main');+ assert.equal(entry.path, '.loop-worktrees/run-1');+ assert.ok(await exists(path.join(dir, '.loop-worktrees', 'run-1')));++ const manifest = await readManifest(dir);+ assert.equal(manifest.version, 1);+ assert.equal(manifest.worktrees.length, 1);+ assert.equal(manifest.worktrees[0].id, 'run-1');+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('create rejects a duplicate active run id', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'dup', pattern: 'ci-sweeper' });+ await assert.rejects(+ () => createWorktree({ root: dir, runId: 'dup', pattern: 'ci-sweeper' }),+ /already has an active worktree/,+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('create fails cleanly outside a git repo', async () => {+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-worktree-nogit-'));+ try {+ assert.equal(await isGitRepo(dir), false);+ await assert.rejects(+ () => createWorktree({ root: dir, runId: 'x', pattern: 'ci-sweeper' }),+ /Not a git repository/,+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('mark updates status; list filters by status', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'a', pattern: 'ci-sweeper' });+ await createWorktree({ root: dir, runId: 'b', pattern: 'pr-babysitter' });+ await markWorktree({ root: dir, runId: 'a', status: 'rejected' });++ const active = await listWorktrees({ root: dir, status: 'active' });+ assert.deepEqual(active.map((w) => w.id), ['b']);+ const rejected = await listWorktrees({ root: dir, status: 'rejected' });+ assert.deepEqual(rejected.map((w) => w.id), ['a']);++ await assert.rejects(+ () => markWorktree({ root: dir, runId: 'missing', status: 'merged' }),+ /No worktree with run id/,+ );+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('cleanup removes rejected/escalated and prunes the manifest (round-trip)', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'keep', pattern: 'ci-sweeper' });+ await createWorktree({ root: dir, runId: 'drop', pattern: 'ci-sweeper' });+ await markWorktree({ root: dir, runId: 'drop', status: 'rejected' });++ const result = await cleanupWorktrees({ root: dir });+ assert.deepEqual(result.removed.map((e) => e.id), ['drop']);+ assert.equal(result.skipped.length, 0);+ assert.equal(await exists(path.join(dir, '.loop-worktrees', 'drop')), false);++ const manifest = await readManifest(dir);+ assert.deepEqual(manifest.worktrees.map((w) => w.id), ['keep']);++ const clean = await gc({ root: dir });+ assert.equal(clean.orphans.length, 0);+ assert.equal(clean.dropped.length, 0);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('cleanup skips a dirty worktree without --force, removes it with --force', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'dirty', pattern: 'ci-sweeper' });+ await markWorktree({ root: dir, runId: 'dirty', status: 'rejected' });+ // Untracked file makes the worktree dirty; git refuses removal without --force.+ await writeFile(path.join(dir, '.loop-worktrees', 'dirty', 'scratch.txt'), 'wip');++ const skip = await cleanupWorktrees({ root: dir });+ assert.equal(skip.removed.length, 0);+ assert.equal(skip.skipped.length, 1);+ assert.equal(skip.skipped[0].entry.id, 'dirty');+ assert.ok(await exists(path.join(dir, '.loop-worktrees', 'dirty')));++ const forced = await cleanupWorktrees({ root: dir, force: true });+ assert.deepEqual(forced.removed.map((e) => e.id), ['dirty']);+ assert.equal(await exists(path.join(dir, '.loop-worktrees', 'dirty')), false);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('gc drops manifest entries whose worktree was removed out of band', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'gone', pattern: 'ci-sweeper' });+ // Remove the worktree behind loop-worktree's back.+ await git(['worktree', 'remove', '--force', '.loop-worktrees/gone'], dir);++ const result = await gc({ root: dir });+ assert.deepEqual(result.dropped.map((e) => e.id), ['gone']);+ const manifest = await readManifest(dir);+ assert.equal(manifest.worktrees.length, 0);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test('cleanup honors --older-than', async () => {+ const dir = await initRepo();+ try {+ await createWorktree({ root: dir, runId: 'fresh', pattern: 'ci-sweeper' });+ await markWorktree({ root: dir, runId: 'fresh', status: 'rejected' });+ // Just created, so a 1h floor should skip it.+ const result = await cleanupWorktrees({ root: dir, olderThan: '1h' });+ assert.equal(result.removed.length, 0);+ assert.ok(await exists(path.join(dir, '.loop-worktrees', 'fresh')));+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});diff --git a/tools/loop-worktree/tsconfig.json b/tools/loop-worktree/tsconfig.jsonnew file mode 100644index 0000000..ef0f184--- /dev/null+++ b/tools/loop-worktree/tsconfig.json@@ -0,0 +1,13 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "outDir": "dist",+ "rootDir": "src",+ "strict": true,+ "skipLibCheck": true,+ "declaration": true+ },+ "include": ["src/**/*"]+}