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): wait queue + deadlock detection (#292) (#295)
Cobus Greyling1f3897acb4ba
diff --git a/README.md b/README.mdindex 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.mdindex 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```bashnpx @cobusgreyling/loop-init . --pattern daily-triage --tool groknpx @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 filediff --git a/STATE.md b/STATE.mdindex 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 Listdiff --git a/tools/loop-worktree/README.md b/tools/loop-worktree/README.mdindex 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 deadlocksloop-worktree unlock --owner <name># releases that owner's lock; no-op if it didn't hold oneloop-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)```## Statusdiff --git a/tools/loop-worktree/dist/cli.js b/tools/loop-worktree/dist/cli.jsindex 4a401ae..c4ea421 100644--- a/tools/loop-worktree/dist/cli.js+++ b/tools/loop-worktree/dist/cli.js@@ -1,6 +1,6 @@#!/usr/bin/env nodeimport { 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.tsindex 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<booleaexport 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.jsindex 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.jsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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', asconst 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;+});+