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.

feat(loop-worktree): manage isolated git worktrees per fix attempt (#190)

JonyT3eac4e70b6a1
diff --git a/.gitignore b/.gitignore
index 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.md
index 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.md
index 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 wor
In 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. Skills
diff --git a/package.json b/package.json
index 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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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.json
new file mode 100644
index 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/**/*"]
+}