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): wait queue + deadlock detection (#292) (#295)

Cobus Greyling1f3897acb4ba
diff --git a/README.md b/README.md
index 00f3619..8e4dcf6 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 21 scoped `good first issues` — comment *I'll take this* to get assigned |
| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |
| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices |
+| [npm update (Jul 16)](https://github.com/cobusgreyling/loop-engineering/discussions/294) | `loop-context` 1.2.0 + `loop-worktree` 1.1.0 — daily budget, path locks |
| [Maintenance (Jul 10)](https://github.com/cobusgreyling/loop-engineering/discussions/241) | Doc sync, branch prune, loop-audit 1.6.0 follow-up |
| [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server |
| [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.md
index e001ca0..5730676 100644
--- a/RELEASE_NOTES_DRAFT.md
+++ b/RELEASE_NOTES_DRAFT.md
@@ -1,97 +1,29 @@
-# Release notes draft — since `loop-context-v1.1.0`
+# Release notes draft — since `loop-context-v1.2.0`
-**Status:** Ready for human review (release prep [#272](https://github.com/cobusgreyling/loop-engineering/issues/272), 2026-07-15).
+**Status:** Stub for next changelog-drafter run.
-**Window:** 2026-07-13 → 2026-07-15 (tag `loop-context-v1.1.0` through maintainer batch)
+**Last published:** [Discussion #294](https://github.com/cobusgreyling/loop-engineering/discussions/294) (2026-07-16) — `loop-context` 1.2.0, `loop-worktree` 1.1.0.
+
+**Window:** 2026-07-16 → (next tag)
---
## Highlights
-### Published Jul 13 — npm batch
-
-| Package | Version | Tag | What shipped |
-|---------|---------|-----|--------------|
-| `@cobusgreyling/loop-cost` | **1.1.0** | `loop-cost-v1.1.0` | Multi-agent orchestration cost on the action path ([#256](https://github.com/cobusgreyling/loop-engineering/pull/256), @KhaiTrang1995) |
-| `@cobusgreyling/loop-context` | **1.1.0** | `loop-context-v1.1.0` | `--budget-from-pattern` resolves per-run token caps from `loop-cost` ([#258](https://github.com/cobusgreyling/loop-engineering/pull/258), @KhaiTrang1995) |
-| `@cobusgreyling/loop-init` | **1.4.0** | `loop-init-v1.4.0` | Dependency sync + maintenance publish ([#271](https://github.com/cobusgreyling/loop-engineering/pull/271)) |
-
-```bash
-npx @cobusgreyling/loop-context --check --ledger run.json \
- --budget-from-pattern ci-sweeper --budget-level L2
-npx @cobusgreyling/loop-cost --pattern ci-sweeper --level L2 --json
-```
+_(changelog-drafter will fill from merges since `loop-context-v1.2.0`)_
-### Next npm publish (merged 2026-07-15)
+### Pending npm publish
| Package | PR | What ships |
|---------|-----|------------|
-| `@cobusgreyling/loop-context` **1.2.0** | [#273](https://github.com/cobusgreyling/loop-engineering/pull/273) | Daily token spend tracking (`--daily-budget-from-pattern`), `--on-exceed` hook for `loop-budget.md` automation (@KhaiTrang1995) |
-| `@cobusgreyling/loop-worktree` **1.1.0** | [#274](https://github.com/cobusgreyling/loop-engineering/pull/274) | Advisory path locking (`lock` / `unlock` / `locks`) for multi-loop collision prevention (@KhaiTrang1995) |
-
-```bash
-# Daily cap across separate runs
-npx @cobusgreyling/loop-context --check --ledger run.json \
- --daily-budget-from-pattern ci-sweeper --on-exceed ./scripts/on-budget-exceed.sh
-
-# Multi-loop path coordination
-npx @cobusgreyling/loop-worktree lock --paths 'package-lock.json,pnpm-lock.yaml' --owner ci-sweeper
-npx @cobusgreyling/loop-worktree locks --json
-```
-
-### Infra
-
-- **Star-history CI** — `update-star-history.yml` now requires `STAR_HISTORY_TOKEN` (fine-grained PAT). `GITHUB_TOKEN` cannot list stargazers under GitHub's Jul 2026 API restriction. SVGs refreshed to ~7,928 stars.
-
----
-
-## Docs & examples (since prior draft)
-
-| PR | Contributor | What shipped |
-|----|-------------|--------------|
-| [#268](https://github.com/cobusgreyling/loop-engineering/pull/268) | @Mahizhan-S | Cursor post-merge cleanup example |
-| [#251](https://github.com/cobusgreyling/loop-engineering/pull/251) | @Mahizhan-S | Cursor dependency sweeper example |
-| [#247](https://github.com/cobusgreyling/loop-engineering/pull/247) | @AshayK003 | Hermes PR Babysitter example |
-| [#257](https://github.com/cobusgreyling/loop-engineering/pull/257) | @k-anushka14 | dependency-vs-ci-sweeper collision story |
-| [#249](https://github.com/cobusgreyling/loop-engineering/pull/249) | @Mahizhan-S | Codeium (Windsurf) primitives appendix |
-| [#263](https://github.com/cobusgreyling/loop-engineering/pull/263) | maintainer | `loop-sync` QUICKSTART subsection |
+| `@cobusgreyling/loop-worktree` **1.2.0** | [#292](https://github.com/cobusgreyling/loop-engineering/pull/292) | Wait queue (`--wait`) + deadlock detection on path locks (@THRISHAL12345) |
+| `@cobusgreyling/loop-gate` **1.0.0** | [#291](https://github.com/cobusgreyling/loop-engineering/pull/291) | Mechanical denylist + auto-merge allowlist from `gate.yaml` (@KhaiTrang1995) |
---
-## npm packages (current on main)
-
-| Package | Version | Notes |
-|---------|---------|-------|
-| `@cobusgreyling/loop-context` | 1.1.0 → **1.2.0** pending tag | Daily budget + on-exceed hook after #273 publish |
-| `@cobusgreyling/loop-worktree` | 1.0.0 → **1.1.0** pending tag | Path locking after #274 publish |
-| `@cobusgreyling/loop-cost` | **1.1.0** | Multi-agent orchestration estimates |
-| `@cobusgreyling/loop-init` | **1.4.0** | |
-| `@cobusgreyling/loop-audit` | **1.6.0** | No change this window |
-| `@cobusgreyling/loop-mcp-server` | 1.0.0 | No change |
-| `@cobusgreyling/loop-sync` | 1.0.0 | No change |
-| `@cobusgreyling/goal-audit` | 1.0.2 | Companion stack |
-
----
-
-## Suggested publish sequence
-
-After review, tag and push in dependency order:
-
-```bash
-git tag loop-context-v1.2.0 && git push origin loop-context-v1.2.0
-git tag loop-worktree-v1.1.0 && git push origin loop-worktree-v1.1.0
-```
-
-Then publish a GitHub Discussion (see prior drafts [#219](https://github.com/cobusgreyling/loop-engineering/discussions/219), [#241](https://github.com/cobusgreyling/loop-engineering/discussions/241)) and close [#272](https://github.com/cobusgreyling/loop-engineering/issues/272).
-
----
-
-## Try it in 5 minutes
+## Try it
```bash
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-audit . --suggest
-npx @cobusgreyling/loop-context --check --ledger run.json --budget-from-pattern daily-triage
-```
-
-Week two (L2): pair `loop-worktree` path locks with `loop-context --daily-budget-from-pattern` — see [QUICKSTART](docs/QUICKSTART.md).
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/STATE.md b/STATE.md
index a01bd2f..92ecf55 100644
--- a/STATE.md
+++ b/STATE.md
@@ -5,7 +5,7 @@ Last run: 2026-07-15T09:44:51Z (automated daily-triage workflow)
## High Priority (loop is acting or waiting on human)
- Maintain loop readiness score ≥ 58 (current: **100**, level **L3**).
-- Keep npm packages current after tool changes (tag `loop-audit-v*`, `loop-init-v*`, `loop-cost-v*`, `loop-context-v*`, `loop-worktree-v*` — see docs/RELEASE.md). **Pending publish:** `loop-context` 1.2.0, `loop-worktree` 1.1.0 (merged #273, #274).
+- Keep npm packages current after tool changes (tag `loop-audit-v*`, `loop-init-v*`, `loop-cost-v*`, `loop-context-v*`, `loop-worktree-v*`, `loop-gate-v*` — see docs/RELEASE.md). **Pending publish:** `loop-worktree` 1.2.0 (wait queue + deadlock detection, #292), `loop-gate` 1.0.0 (#291).
## Watch List
diff --git a/tools/loop-worktree/README.md b/tools/loop-worktree/README.md
index f910b07..2e0ba24 100644
--- a/tools/loop-worktree/README.md
+++ b/tools/loop-worktree/README.md
@@ -39,14 +39,15 @@ loop-worktree gc [--force] [--json]
loop-worktree list [--status active] [--json]
-loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h]
+loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h] [--wait 15m]
# advisory lock: fails if another (non-expired) owner already holds an overlapping path
+ # --wait queues instead of failing immediately; detects wait-for-graph deadlocks
loop-worktree unlock --owner <name>
# releases that owner's lock; no-op if it didn't hold one
loop-worktree locks [--sweep] [--force] [--json]
- # lists active locks; --sweep reports expired ones (report-only; --force deletes them)
+ # lists active locks and wait intents; --sweep reports expired ones (report-only; --force deletes them)
```
## Status
diff --git a/tools/loop-worktree/dist/cli.js b/tools/loop-worktree/dist/cli.js
index 4a401ae..c4ea421 100644
--- a/tools/loop-worktree/dist/cli.js
+++ b/tools/loop-worktree/dist/cli.js
@@ -1,6 +1,6 @@
#!/usr/bin/env node
import { createWorktree, markWorktree, cleanupWorktrees, gc, listWorktrees, VALID_STATUSES, } from './worktree.js';
-import { lockPaths, unlockOwner, listLocks, sweepExpiredLocks, isExpired } from './lock.js';
+import { lockPaths, unlockOwner, listLocks, sweepExpiredLocks, isExpired, listWaits, isWaitExpired } from './lock.js';
function parseFlags(argv) {
const flags = { root: process.cwd(), force: false, json: false, sweep: false };
for (let i = 0; i < argv.length; i++) {
@@ -27,6 +27,8 @@ function parseFlags(argv) {
flags.owner = argv[++i];
else if (a === '--ttl')
flags.ttl = argv[++i];
+ else if (a === '--wait')
+ flags.wait = argv[++i];
else if (a === '--sweep')
flags.sweep = true;
}
@@ -49,7 +51,7 @@ Usage:
loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]
loop-worktree gc [--force] [--json]
loop-worktree list [--status <s>] [--json]
- loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h]
+ loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h] [--wait 15m]
loop-worktree unlock --owner <name>
loop-worktree locks [--sweep] [--force] [--json]
@@ -63,6 +65,7 @@ Locking (advisory, not enforced by create -- pair it in your control script):
--paths <csv> Comma-separated path globs this owner is about to touch
--owner <name> Lock/unlock identity, typically the pattern name
--ttl <dur> Optional expiry (e.g. 30m, 6h, 1d); omit for no auto-expiry
+ --wait <dur> Wait up to this long for locks to clear instead of failing immediately (detects deadlocks)
locks --sweep Report expired locks (report-only; --force deletes them)
Worktrees live under .loop-worktrees/, tracked in .loop-worktrees/manifest.json.
@@ -154,7 +157,7 @@ async function main() {
throw new Error('lock requires --paths and --owner.');
}
const paths = flags.paths.split(',').map((p) => p.trim()).filter(Boolean);
- const entry = await lockPaths({ root: flags.root, owner: flags.owner, paths, ttl: flags.ttl });
+ const entry = await lockPaths({ root: flags.root, owner: flags.owner, paths, ttl: flags.ttl, wait: flags.wait });
console.log(`locked ${entry.paths.join(', ')} for ${entry.owner}` + (entry.expiresAt ? ` (expires ${entry.expiresAt})` : ''));
return 0;
}
@@ -176,23 +179,36 @@ async function main() {
for (const l of result.expired) {
console.log(result.removed.includes(l.owner) ? `removed expired lock ${l.owner}` : `expired lock ${l.owner}`);
}
- console.log(`locks --sweep: ${result.expired.length} expired` +
- (flags.force ? `, ${result.removed.length} removed` : ' (report-only; use --force to remove)'));
+ const expiredWaits = result.expiredWaits || [];
+ const removedWaits = result.removedWaits || [];
+ for (const w of expiredWaits) {
+ console.log(removedWaits.includes(w.owner) ? `removed expired wait ${w.owner}` : `expired wait ${w.owner}`);
+ }
+ console.log(`locks --sweep: ${result.expired.length} lock(s), ${expiredWaits.length} wait(s) expired` +
+ (flags.force ? `, ${result.removed.length + removedWaits.length} removed` : ' (report-only; use --force to remove)'));
return 0;
}
const locks = await listLocks(flags.root);
+ const waits = await listWaits(flags.root);
if (flags.json) {
- console.log(JSON.stringify(locks.map((l) => ({ ...l, expired: isExpired(l) })), null, 2));
+ console.log(JSON.stringify({
+ locks: locks.map((l) => ({ ...l, expired: isExpired(l) })),
+ waits: waits.map((w) => ({ ...w, expired: isWaitExpired(w) }))
+ }, null, 2));
return 0;
}
- if (locks.length === 0) {
- console.log('no active locks');
+ if (locks.length === 0 && waits.length === 0) {
+ console.log('no active locks or waits');
return 0;
}
for (const l of locks) {
const expiryNote = l.expiresAt ? `, expires ${l.expiresAt}${isExpired(l) ? ' (expired)' : ''}` : '';
console.log(`${l.owner} ${l.paths.join(', ')} (locked ${l.lockedAt}${expiryNote})`);
}
+ for (const w of waits) {
+ const expiryNote = w.expiresAt ? `, wait expires ${w.expiresAt}${isWaitExpired(w) ? ' (expired)' : ''}` : '';
+ console.log(`${w.owner} [WAITING ON: ${w.waitingOn.join(', ')}] ${w.paths.join(', ')} (requested ${w.requestedAt}${expiryNote})`);
+ }
return 0;
}
default:
diff --git a/tools/loop-worktree/dist/lock.d.ts b/tools/loop-worktree/dist/lock.d.ts
index e65d6ab..7be1d30 100644
--- a/tools/loop-worktree/dist/lock.d.ts
+++ b/tools/loop-worktree/dist/lock.d.ts
@@ -6,6 +6,15 @@ export interface LockEntry {
/** Absent means the lock never expires automatically; must be explicitly unlocked. */
expiresAt?: string;
}
+export interface WaitEntry {
+ owner: string;
+ paths: string[];
+ waitingOn: string[];
+ requestedAt: string;
+ expiresAt?: string;
+}
+export declare function listWaits(root: string): Promise<WaitEntry[]>;
+export declare function isWaitExpired(wait: WaitEntry, now?: number): boolean;
export declare function isExpired(lock: LockEntry, now?: number): boolean;
/**
* Two path globs "overlap" if, segment by segment, every position where both
@@ -25,6 +34,8 @@ export interface LockPathsInput {
paths: string[];
/** e.g. "6h" -- if omitted, the lock never expires automatically. */
ttl?: string;
+ /** e.g. "15m" -- wait duration if paths are locked. */
+ wait?: string;
}
/**
* Acquire an advisory lock on `paths` for `owner`. Fails if any *other*,
@@ -37,6 +48,8 @@ export declare function unlockOwner(root: string, owner: string): Promise<boolea
export interface SweepExpiredLocksResult {
expired: LockEntry[];
removed: string[];
+ expiredWaits?: WaitEntry[];
+ removedWaits?: string[];
}
/** Report (and, with force, delete) locks past their own TTL. Never touches an active lock. */
export declare function sweepExpiredLocks(root: string, opts?: {
diff --git a/tools/loop-worktree/dist/lock.js b/tools/loop-worktree/dist/lock.js
index 3138e17..c3e20f5 100644
--- a/tools/loop-worktree/dist/lock.js
+++ b/tools/loop-worktree/dist/lock.js
@@ -3,6 +3,71 @@ import path from 'node:path';
import { MANIFEST_DIR, parseDurationMs } from './worktree.js';
export const LOCKS_DIR = path.posix.join(MANIFEST_DIR, 'locks');
const MUTEX_FILE = path.posix.join(LOCKS_DIR, '.mutex');
+function waitFile(root, owner) {
+ return path.join(root, LOCKS_DIR, `${owner}.wait.json`);
+}
+async function readWait(root, owner) {
+ const file = waitFile(root, owner);
+ if (!(await exists(file)))
+ return null;
+ const raw = await readFile(file, 'utf8');
+ try {
+ return JSON.parse(raw);
+ }
+ catch {
+ throw new Error(`Corrupt wait file ${file}: not valid JSON. Inspect it and delete it manually if it's stale.`);
+ }
+}
+export async function listWaits(root) {
+ const files = await readdirSafely(path.join(root, LOCKS_DIR));
+ const waits = [];
+ for (const file of files) {
+ if (!file.endsWith('.wait.json'))
+ continue;
+ const wait = await readWait(root, file.slice(0, -'.wait.json'.length));
+ if (wait)
+ waits.push(wait);
+ }
+ return waits;
+}
+export function isWaitExpired(wait, now = Date.now()) {
+ return wait.expiresAt !== undefined && Date.parse(wait.expiresAt) <= now;
+}
+function detectDeadlock(owner, waitingOn, allWaits) {
+ const graph = new Map();
+ graph.set(owner, waitingOn);
+ for (const w of allWaits) {
+ if (w.owner !== owner) {
+ graph.set(w.owner, w.waitingOn);
+ }
+ }
+ const visited = new Set();
+ const stack = new Set();
+ const path = [];
+ function dfs(node) {
+ if (stack.has(node)) {
+ path.push(node);
+ return true;
+ }
+ if (visited.has(node))
+ return false;
+ visited.add(node);
+ stack.add(node);
+ path.push(node);
+ const neighbors = graph.get(node) || [];
+ for (const neighbor of neighbors) {
+ if (dfs(neighbor))
+ return true;
+ }
+ stack.delete(node);
+ path.pop();
+ return false;
+ }
+ if (dfs(owner)) {
+ const cycle = path.slice(path.indexOf(path[path.length - 1])).join(' -> ');
+ throw new Error(`Deadlock detected: ${cycle}`);
+ }
+}
const OWNER_PATTERN = /^[A-Za-z0-9._-]+$/;
function assertValidOwner(owner) {
if (!OWNER_PATTERN.test(owner)) {
@@ -81,7 +146,7 @@ export async function listLocks(root) {
const files = await readdirSafely(path.join(root, LOCKS_DIR));
const locks = [];
for (const file of files) {
- if (!file.endsWith('.json'))
+ if (!file.endsWith('.json') || file.endsWith('.wait.json'))
continue;
const lock = await readLock(root, file.slice(0, -'.json'.length));
if (lock)
@@ -130,48 +195,88 @@ async function withLocksMutex(root, fn) {
* same owner replaces that owner's own previous lock (paths and TTL both).
*/
export async function lockPaths(input) {
- const { root, owner, paths } = input;
+ const { root, owner, paths, wait, ttl } = input;
assertValidOwner(owner);
if (paths.length === 0) {
throw new Error('--paths requires at least one path or glob.');
}
- return withLocksMutex(root, async () => {
- const now = Date.now();
- for (const other of await listLocks(root)) {
- if (other.owner === owner || isExpired(other, now))
- continue;
- for (const p of paths) {
- const clash = other.paths.find((op) => pathsOverlap(p, op));
- if (clash) {
- throw new Error(`Path "${p}" is locked by owner "${other.owner}" (locked at ${other.lockedAt}` +
- (other.expiresAt ? `, expires at ${other.expiresAt}` : '') +
- `). Use --paths that don't overlap, or wait for the lock to clear.`);
+ const waitUntil = wait ? Date.now() + parseDurationMs(wait, '--wait') : undefined;
+ for (;;) {
+ const success = await withLocksMutex(root, async () => {
+ const now = Date.now();
+ const locks = await listLocks(root);
+ const blockingOwners = new Set();
+ const blockingErrors = [];
+ for (const other of locks) {
+ if (other.owner === owner || isExpired(other, now))
+ continue;
+ for (const p of paths) {
+ const clash = other.paths.find((op) => pathsOverlap(p, op));
+ if (clash) {
+ blockingOwners.add(other.owner);
+ blockingErrors.push(`Path "${p}" is locked by owner "${other.owner}" (locked at ${other.lockedAt}` +
+ (other.expiresAt ? `, expires at ${other.expiresAt}` : '') +
+ `).`);
+ }
}
}
+ if (blockingOwners.size > 0) {
+ if (!waitUntil) {
+ throw new Error(`${blockingErrors.join('\n')}\nUse --paths that don't overlap, or wait for the lock to clear.`);
+ }
+ if (Date.now() > waitUntil) {
+ await unlink(waitFile(root, owner)).catch(() => { });
+ throw new Error(`Timed out waiting for lock on paths: ${paths.join(', ')}`);
+ }
+ const allWaits = (await listWaits(root)).filter((w) => !isWaitExpired(w, now));
+ detectDeadlock(owner, Array.from(blockingOwners), allWaits);
+ const waitEntry = {
+ owner,
+ paths,
+ waitingOn: Array.from(blockingOwners),
+ requestedAt: new Date(now).toISOString(),
+ expiresAt: new Date(waitUntil).toISOString(),
+ };
+ await writeFile(waitFile(root, owner), `${JSON.stringify(waitEntry, null, 2)}\n`);
+ return false;
+ }
+ await unlink(waitFile(root, owner)).catch(() => { });
+ const entry = { owner, paths, lockedAt: new Date(now).toISOString() };
+ if (ttl) {
+ entry.expiresAt = new Date(now + parseDurationMs(ttl, '--ttl')).toISOString();
+ }
+ await writeFile(lockFile(root, owner), `${JSON.stringify(entry, null, 2)}\n`);
+ return entry;
+ });
+ if (success) {
+ return success;
}
- const entry = { owner, paths, lockedAt: new Date(now).toISOString() };
- if (input.ttl) {
- entry.expiresAt = new Date(now + parseDurationMs(input.ttl, '--ttl')).toISOString();
- }
- await writeFile(lockFile(root, owner), `${JSON.stringify(entry, null, 2)}\n`);
- return entry;
- });
+ await new Promise((resolve) => setTimeout(resolve, 2000 + Math.random() * 1000));
+ }
}
/** Release `owner`'s lock. Returns false (no-op) if it didn't hold one. */
export async function unlockOwner(root, owner) {
assertValidOwner(owner);
- const file = lockFile(root, owner);
- if (!(await exists(file)))
- return false;
- await unlink(file);
- return true;
+ const lFile = lockFile(root, owner);
+ const wFile = waitFile(root, owner);
+ let released = false;
+ if (await exists(lFile)) {
+ await unlink(lFile);
+ released = true;
+ }
+ if (await exists(wFile)) {
+ await unlink(wFile);
+ }
+ return released;
}
/** Report (and, with force, delete) locks past their own TTL. Never touches an active lock. */
export async function sweepExpiredLocks(root, opts = {}) {
return withLocksMutex(root, async () => {
const now = Date.now();
const expired = (await listLocks(root)).filter((l) => isExpired(l, now));
+ const expiredWaits = (await listWaits(root)).filter((w) => isWaitExpired(w, now));
const removed = [];
+ const removedWaits = [];
if (opts.force) {
for (const l of expired) {
try {
@@ -182,7 +287,16 @@ export async function sweepExpiredLocks(root, opts = {}) {
// Already gone; nothing to report.
}
}
+ for (const w of expiredWaits) {
+ try {
+ await unlink(waitFile(root, w.owner));
+ removedWaits.push(w.owner);
+ }
+ catch {
+ // Already gone
+ }
+ }
}
- return { expired, removed };
+ return { expired, removed, expiredWaits, removedWaits };
});
}
diff --git a/tools/loop-worktree/dist/worktree.js b/tools/loop-worktree/dist/worktree.js
index 73a8a2c..0db5d03 100644
--- a/tools/loop-worktree/dist/worktree.js
+++ b/tools/loop-worktree/dist/worktree.js
@@ -113,13 +113,13 @@ export async function markWorktree(input) {
}
/** Parse a duration like "30m", "24h", "7d" into milliseconds. Shared with lock.ts's --ttl. */
export function parseDurationMs(token, flag) {
- const m = /^(\d+)([mhd])$/.exec(token.trim());
+ const m = /^(\d+)([smhd])$/.exec(token.trim());
if (!m) {
- throw new Error(`Invalid ${flag} "${token}". Use e.g. 30m, 24h, 7d.`);
+ throw new Error(`Invalid ${flag} "${token}". Use e.g. 30s, 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;
+ const ms = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
return n * ms;
}
export async function cleanupWorktrees(input) {
diff --git a/tools/loop-worktree/package.json b/tools/loop-worktree/package.json
index 2fbe3d9..9dd0e4e 100644
--- a/tools/loop-worktree/package.json
+++ b/tools/loop-worktree/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-worktree",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Manage isolated git worktrees for loop engineering attempts: create, mark, cleanup, and reconcile one worktree per fix attempt.",
"type": "module",
"bin": {
diff --git a/tools/loop-worktree/src/cli.ts b/tools/loop-worktree/src/cli.ts
index a84f0ce..29f4dbb 100644
--- a/tools/loop-worktree/src/cli.ts
+++ b/tools/loop-worktree/src/cli.ts
@@ -8,7 +8,7 @@ import {
VALID_STATUSES,
type WorktreeStatus,
} from './worktree.js';
-import { lockPaths, unlockOwner, listLocks, sweepExpiredLocks, isExpired } from './lock.js';
+import { lockPaths, unlockOwner, listLocks, sweepExpiredLocks, isExpired, listWaits, isWaitExpired } from './lock.js';
interface Flags {
root: string;
@@ -22,6 +22,7 @@ interface Flags {
paths?: string;
owner?: string;
ttl?: string;
+ wait?: string;
sweep: boolean;
}
@@ -40,6 +41,7 @@ function parseFlags(argv: string[]): Flags {
else if (a === '--paths') flags.paths = argv[++i];
else if (a === '--owner') flags.owner = argv[++i];
else if (a === '--ttl') flags.ttl = argv[++i];
+ else if (a === '--wait') flags.wait = argv[++i];
else if (a === '--sweep') flags.sweep = true;
}
return flags;
@@ -63,7 +65,7 @@ Usage:
loop-worktree cleanup [--status rejected,escalated] [--older-than 24h] [--force]
loop-worktree gc [--force] [--json]
loop-worktree list [--status <s>] [--json]
- loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h]
+ loop-worktree lock --paths <glob1,glob2,...> --owner <name> [--ttl 6h] [--wait 15m]
loop-worktree unlock --owner <name>
loop-worktree locks [--sweep] [--force] [--json]
@@ -77,6 +79,7 @@ Locking (advisory, not enforced by create -- pair it in your control script):
--paths <csv> Comma-separated path globs this owner is about to touch
--owner <name> Lock/unlock identity, typically the pattern name
--ttl <dur> Optional expiry (e.g. 30m, 6h, 1d); omit for no auto-expiry
+ --wait <dur> Wait up to this long for locks to clear instead of failing immediately (detects deadlocks)
locks --sweep Report expired locks (report-only; --force deletes them)
Worktrees live under .loop-worktrees/, tracked in .loop-worktrees/manifest.json.
@@ -170,7 +173,7 @@ async function main(): Promise<number> {
throw new Error('lock requires --paths and --owner.');
}
const paths = flags.paths.split(',').map((p) => p.trim()).filter(Boolean);
- const entry = await lockPaths({ root: flags.root, owner: flags.owner, paths, ttl: flags.ttl });
+ const entry = await lockPaths({ root: flags.root, owner: flags.owner, paths, ttl: flags.ttl, wait: flags.wait });
console.log(`locked ${entry.paths.join(', ')} for ${entry.owner}` + (entry.expiresAt ? ` (expires ${entry.expiresAt})` : ''));
return 0;
}
@@ -192,25 +195,38 @@ async function main(): Promise<number> {
for (const l of result.expired) {
console.log(result.removed.includes(l.owner) ? `removed expired lock ${l.owner}` : `expired lock ${l.owner}`);
}
+ const expiredWaits = result.expiredWaits || [];
+ const removedWaits = result.removedWaits || [];
+ for (const w of expiredWaits) {
+ console.log(removedWaits.includes(w.owner) ? `removed expired wait ${w.owner}` : `expired wait ${w.owner}`);
+ }
console.log(
- `locks --sweep: ${result.expired.length} expired` +
- (flags.force ? `, ${result.removed.length} removed` : ' (report-only; use --force to remove)'),
+ `locks --sweep: ${result.expired.length} lock(s), ${expiredWaits.length} wait(s) expired` +
+ (flags.force ? `, ${result.removed.length + removedWaits.length} removed` : ' (report-only; use --force to remove)'),
);
return 0;
}
const locks = await listLocks(flags.root);
+ const waits = await listWaits(flags.root);
if (flags.json) {
- console.log(JSON.stringify(locks.map((l) => ({ ...l, expired: isExpired(l) })), null, 2));
+ console.log(JSON.stringify({
+ locks: locks.map((l) => ({ ...l, expired: isExpired(l) })),
+ waits: waits.map((w) => ({ ...w, expired: isWaitExpired(w) }))
+ }, null, 2));
return 0;
}
- if (locks.length === 0) {
- console.log('no active locks');
+ if (locks.length === 0 && waits.length === 0) {
+ console.log('no active locks or waits');
return 0;
}
for (const l of locks) {
const expiryNote = l.expiresAt ? `, expires ${l.expiresAt}${isExpired(l) ? ' (expired)' : ''}` : '';
console.log(`${l.owner} ${l.paths.join(', ')} (locked ${l.lockedAt}${expiryNote})`);
}
+ for (const w of waits) {
+ const expiryNote = w.expiresAt ? `, wait expires ${w.expiresAt}${isWaitExpired(w) ? ' (expired)' : ''}` : '';
+ console.log(`${w.owner} [WAITING ON: ${w.waitingOn.join(', ')}] ${w.paths.join(', ')} (requested ${w.requestedAt}${expiryNote})`);
+ }
return 0;
}
default:
diff --git a/tools/loop-worktree/src/lock.ts b/tools/loop-worktree/src/lock.ts
index 4f0d922..9bf692a 100644
--- a/tools/loop-worktree/src/lock.ts
+++ b/tools/loop-worktree/src/lock.ts
@@ -13,6 +13,86 @@ export interface LockEntry {
expiresAt?: string;
}
+export interface WaitEntry {
+ owner: string;
+ paths: string[];
+ waitingOn: string[];
+ requestedAt: string;
+ expiresAt?: string;
+}
+
+function waitFile(root: string, owner: string): string {
+ return path.join(root, LOCKS_DIR, `${owner}.wait.json`);
+}
+
+async function readWait(root: string, owner: string): Promise<WaitEntry | null> {
+ const file = waitFile(root, owner);
+ if (!(await exists(file))) return null;
+ const raw = await readFile(file, 'utf8');
+ try {
+ return JSON.parse(raw) as WaitEntry;
+ } catch {
+ throw new Error(
+ `Corrupt wait file ${file}: not valid JSON. Inspect it and delete it manually if it's stale.`,
+ );
+ }
+}
+
+export async function listWaits(root: string): Promise<WaitEntry[]> {
+ const files = await readdirSafely(path.join(root, LOCKS_DIR));
+ const waits: WaitEntry[] = [];
+ for (const file of files) {
+ if (!file.endsWith('.wait.json')) continue;
+ const wait = await readWait(root, file.slice(0, -'.wait.json'.length));
+ if (wait) waits.push(wait);
+ }
+ return waits;
+}
+
+export function isWaitExpired(wait: WaitEntry, now: number = Date.now()): boolean {
+ return wait.expiresAt !== undefined && Date.parse(wait.expiresAt) <= now;
+}
+
+function detectDeadlock(owner: string, waitingOn: string[], allWaits: WaitEntry[]): void {
+ const graph = new Map<string, string[]>();
+ graph.set(owner, waitingOn);
+ for (const w of allWaits) {
+ if (w.owner !== owner) {
+ graph.set(w.owner, w.waitingOn);
+ }
+ }
+
+ const visited = new Set<string>();
+ const stack = new Set<string>();
+ const path: string[] = [];
+
+ function dfs(node: string): boolean {
+ if (stack.has(node)) {
+ path.push(node);
+ return true;
+ }
+ if (visited.has(node)) return false;
+
+ visited.add(node);
+ stack.add(node);
+ path.push(node);
+
+ const neighbors = graph.get(node) || [];
+ for (const neighbor of neighbors) {
+ if (dfs(neighbor)) return true;
+ }
+
+ stack.delete(node);
+ path.pop();
+ return false;
+ }
+
+ if (dfs(owner)) {
+ const cycle = path.slice(path.indexOf(path[path.length - 1])).join(' -> ');
+ throw new Error(`Deadlock detected: ${cycle}`);
+ }
+}
+
const OWNER_PATTERN = /^[A-Za-z0-9._-]+$/;
function assertValidOwner(owner: string): void {
@@ -96,7 +176,7 @@ export async function listLocks(root: string): Promise<LockEntry[]> {
const files = await readdirSafely(path.join(root, LOCKS_DIR));
const locks: LockEntry[] = [];
for (const file of files) {
- if (!file.endsWith('.json')) continue;
+ if (!file.endsWith('.json') || file.endsWith('.wait.json')) continue;
const lock = await readLock(root, file.slice(0, -'.json'.length));
if (lock) locks.push(lock);
}
@@ -144,6 +224,8 @@ export interface LockPathsInput {
paths: string[];
/** e.g. "6h" -- if omitted, the lock never expires automatically. */
ttl?: string;
+ /** e.g. "15m" -- wait duration if paths are locked. */
+ wait?: string;
}
/**
@@ -152,50 +234,102 @@ export interface LockPathsInput {
* same owner replaces that owner's own previous lock (paths and TTL both).
*/
export async function lockPaths(input: LockPathsInput): Promise<LockEntry> {
- const { root, owner, paths } = input;
+ const { root, owner, paths, wait, ttl } = input;
assertValidOwner(owner);
if (paths.length === 0) {
throw new Error('--paths requires at least one path or glob.');
}
- return withLocksMutex(root, async () => {
- const now = Date.now();
- for (const other of await listLocks(root)) {
- if (other.owner === owner || isExpired(other, now)) continue;
- for (const p of paths) {
- const clash = other.paths.find((op) => pathsOverlap(p, op));
- if (clash) {
+ const waitUntil = wait ? Date.now() + parseDurationMs(wait, '--wait') : undefined;
+
+ for (;;) {
+ const success = await withLocksMutex(root, async () => {
+ const now = Date.now();
+ const locks = await listLocks(root);
+ const blockingOwners = new Set<string>();
+ const blockingErrors: string[] = [];
+
+ for (const other of locks) {
+ if (other.owner === owner || isExpired(other, now)) continue;
+ for (const p of paths) {
+ const clash = other.paths.find((op) => pathsOverlap(p, op));
+ if (clash) {
+ blockingOwners.add(other.owner);
+ blockingErrors.push(
+ `Path "${p}" is locked by owner "${other.owner}" (locked at ${other.lockedAt}` +
+ (other.expiresAt ? `, expires at ${other.expiresAt}` : '') +
+ `).`,
+ );
+ }
+ }
+ }
+
+ if (blockingOwners.size > 0) {
+ if (!waitUntil) {
throw new Error(
- `Path "${p}" is locked by owner "${other.owner}" (locked at ${other.lockedAt}` +
- (other.expiresAt ? `, expires at ${other.expiresAt}` : '') +
- `). Use --paths that don't overlap, or wait for the lock to clear.`,
+ `${blockingErrors.join('\n')}\nUse --paths that don't overlap, or wait for the lock to clear.`,
);
}
+ if (Date.now() > waitUntil) {
+ await unlink(waitFile(root, owner)).catch(() => {});
+ throw new Error(`Timed out waiting for lock on paths: ${paths.join(', ')}`);
+ }
+
+ const allWaits = (await listWaits(root)).filter((w) => !isWaitExpired(w, now));
+ detectDeadlock(owner, Array.from(blockingOwners), allWaits);
+
+ const waitEntry: WaitEntry = {
+ owner,
+ paths,
+ waitingOn: Array.from(blockingOwners),
+ requestedAt: new Date(now).toISOString(),
+ expiresAt: new Date(waitUntil).toISOString(),
+ };
+ await writeFile(waitFile(root, owner), `${JSON.stringify(waitEntry, null, 2)}\n`);
+
+ return false;
}
- }
- const entry: LockEntry = { owner, paths, lockedAt: new Date(now).toISOString() };
- if (input.ttl) {
- entry.expiresAt = new Date(now + parseDurationMs(input.ttl, '--ttl')).toISOString();
+ await unlink(waitFile(root, owner)).catch(() => {});
+
+ const entry: LockEntry = { owner, paths, lockedAt: new Date(now).toISOString() };
+ if (ttl) {
+ entry.expiresAt = new Date(now + parseDurationMs(ttl, '--ttl')).toISOString();
+ }
+
+ await writeFile(lockFile(root, owner), `${JSON.stringify(entry, null, 2)}\n`);
+ return entry;
+ });
+
+ if (success) {
+ return success;
}
- await writeFile(lockFile(root, owner), `${JSON.stringify(entry, null, 2)}\n`);
- return entry;
- });
+ await new Promise((resolve) => setTimeout(resolve, 2000 + Math.random() * 1000));
+ }
}
/** Release `owner`'s lock. Returns false (no-op) if it didn't hold one. */
export async function unlockOwner(root: string, owner: string): Promise<boolean> {
assertValidOwner(owner);
- const file = lockFile(root, owner);
- if (!(await exists(file))) return false;
- await unlink(file);
- return true;
+ const lFile = lockFile(root, owner);
+ const wFile = waitFile(root, owner);
+ let released = false;
+ if (await exists(lFile)) {
+ await unlink(lFile);
+ released = true;
+ }
+ if (await exists(wFile)) {
+ await unlink(wFile);
+ }
+ return released;
}
export interface SweepExpiredLocksResult {
expired: LockEntry[];
removed: string[];
+ expiredWaits?: WaitEntry[];
+ removedWaits?: string[];
}
/** Report (and, with force, delete) locks past their own TTL. Never touches an active lock. */
@@ -206,7 +340,9 @@ export async function sweepExpiredLocks(
return withLocksMutex(root, async () => {
const now = Date.now();
const expired = (await listLocks(root)).filter((l) => isExpired(l, now));
+ const expiredWaits = (await listWaits(root)).filter((w) => isWaitExpired(w, now));
const removed: string[] = [];
+ const removedWaits: string[] = [];
if (opts.force) {
for (const l of expired) {
try {
@@ -216,7 +352,15 @@ export async function sweepExpiredLocks(
// Already gone; nothing to report.
}
}
+ for (const w of expiredWaits) {
+ try {
+ await unlink(waitFile(root, w.owner));
+ removedWaits.push(w.owner);
+ } catch {
+ // Already gone
+ }
+ }
}
- return { expired, removed };
+ return { expired, removed, expiredWaits, removedWaits };
});
}
diff --git a/tools/loop-worktree/src/worktree.ts b/tools/loop-worktree/src/worktree.ts
index 5226cce..16b5ed6 100644
--- a/tools/loop-worktree/src/worktree.ts
+++ b/tools/loop-worktree/src/worktree.ts
@@ -159,13 +159,13 @@ export async function markWorktree(input: MarkInput): Promise<WorktreeEntry> {
/** Parse a duration like "30m", "24h", "7d" into milliseconds. Shared with lock.ts's --ttl. */
export function parseDurationMs(token: string, flag: string): number {
- const m = /^(\d+)([mhd])$/.exec(token.trim());
+ const m = /^(\d+)([smhd])$/.exec(token.trim());
if (!m) {
- throw new Error(`Invalid ${flag} "${token}". Use e.g. 30m, 24h, 7d.`);
+ throw new Error(`Invalid ${flag} "${token}". Use e.g. 30s, 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;
+ const ms = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
return n * ms;
}
diff --git a/tools/loop-worktree/test/cli.test.mjs b/tools/loop-worktree/test/cli.test.mjs
index 2e056be..a29865b 100644
--- a/tools/loop-worktree/test/cli.test.mjs
+++ b/tools/loop-worktree/test/cli.test.mjs
@@ -32,7 +32,7 @@ test('cli lock/locks/unlock round-trip', async () => {
const listed = runCli(['locks', '--json'], dir);
assert.equal(listed.status, 0);
- const locks = JSON.parse(listed.stdout);
+ const { locks } = JSON.parse(listed.stdout);
assert.equal(locks.length, 1);
assert.equal(locks[0].owner, 'dependency-sweeper');
@@ -41,7 +41,7 @@ test('cli lock/locks/unlock round-trip', async () => {
assert.match(unlocked.stdout, /unlocked dependency-sweeper/);
const listedAfter = runCli(['locks', '--json'], dir);
- assert.deepEqual(JSON.parse(listedAfter.stdout), []);
+ assert.deepEqual(JSON.parse(listedAfter.stdout).locks, []);
});
test('cli lock surfaces an overlap error from a different owner', () => {
diff --git a/tools/loop-worktree/test/lock.test.mjs b/tools/loop-worktree/test/lock.test.mjs
index 205368b..24c4717 100644
--- a/tools/loop-worktree/test/lock.test.mjs
+++ b/tools/loop-worktree/test/lock.test.mjs
@@ -156,3 +156,69 @@ test('sweepExpiredLocks removes with --force, leaves active locks untouched', as
const remaining = await listLocks(dir);
assert.deepEqual(remaining.map((l) => l.owner), ['dependency-sweeper']);
});
+
+test('lockPaths with --wait queues and acquires lock when released', async () => {
+ const dir = await freshDir();
+ await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
+
+ // Start a wait in the background
+ const p = lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'], wait: '10s' });
+
+ // Ensure the wait intent is written
+ await new Promise(r => setTimeout(r, 50));
+ const { listWaits } = await import('../dist/lock.js');
+ const waits = await listWaits(dir);
+ assert.equal(waits.length, 1);
+ assert.equal(waits[0].owner, 'dependency-sweeper');
+ assert.deepEqual(waits[0].waitingOn, ['ci-sweeper']);
+
+ // Release the lock
+ await unlockOwner(dir, 'ci-sweeper');
+
+ // Background lock should now succeed
+ const entry = await p;
+ assert.equal(entry.owner, 'dependency-sweeper');
+
+ // Wait intent should be cleaned up
+ assert.equal((await listWaits(dir)).length, 0);
+});
+
+test('lockPaths with --wait times out', async () => {
+ const dir = await freshDir();
+ await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
+
+ const start = Date.now();
+ await assert.rejects(
+ () => lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'], wait: '1s' }),
+ /Timed out waiting for lock on paths/
+ );
+ assert.ok(Date.now() - start >= 1000);
+
+ const { listWaits } = await import('../dist/lock.js');
+ assert.equal((await listWaits(dir)).length, 0);
+});
+
+test('lockPaths deadlock detection aborts cycle immediately', async () => {
+ const dir = await freshDir();
+
+ // A holds package.json
+ await lockPaths({ root: dir, owner: 'A', paths: ['package.json'] });
+ // B holds src/**
+ await lockPaths({ root: dir, owner: 'B', paths: ['src/**'] });
+
+ // A wants src/** and waits on B
+ const pA = lockPaths({ root: dir, owner: 'A', paths: ['src/**'], wait: '10s' });
+
+ await new Promise(r => setTimeout(r, 50));
+
+ // B wants package.json and waits on A - this should throw DeadlockError immediately
+ await assert.rejects(
+ () => lockPaths({ root: dir, owner: 'B', paths: ['package.json'], wait: '10s' }),
+ /Deadlock detected: B -> A -> B/
+ );
+
+ // A is still waiting, release B so A can finish
+ await unlockOwner(dir, 'B');
+ await pA;
+});
+