@senad-d/branchme 0.3.13 → 0.3.14

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 0.3.14 - Unreleased
+
+- A Git mutation that fails because another git process holds `index.lock`, `HEAD.lock` or a ref lock is retried every 250 ms for up to 10 seconds, then fails with git's error plus "The lock was still held after waiting 10 s."; lock files are never removed, and cancellation interrupts the wait without another mutation attempt. Local Git reads (status and the other snapshot reads) time out after 30 seconds instead of 5, for slow or emulated git under parallel agents.
 ## 0.3.13 - Unreleased
 
 - Added optional `integrate_branch.keepConflicts` (default `false`). When true, a conflicted local integration returns `conflict_kept` with the merge left in progress for `conclude_merge` to finish after resolution or abort; default conflict handling still aborts and verifies restoration. Updated schemas, prompt guidance, documentation, and real-Git regression coverage.

package/README.md

@@ -303,7 +303,7 @@ Before each agent run, BranchMe appends an **Automatic Git Context** snapshot to
 - whether pull request field autofill is enabled;
 - up to 5 recent commits with short hash, date, and subject.
 
-Collection defaults are a 5-second timeout per local Git command, a 4-second related-PR lookup timeout, at most 512 characters per metadata value, and at most 4,000 characters for the rendered snapshot. GitHub response bodies are limited to 64 KiB. The formatter can further shorten values or omit entries to stay within the total limit.
+Collection defaults are a 30-second timeout per local Git read, a 4-second related-PR lookup timeout, at most 512 characters per metadata value, and at most 4,000 characters for the rendered snapshot. GitHub response bodies are limited to 64 KiB. The formatter can further shorten values or omit entries to stay within the total limit.
 
 The snapshot is fresh at agent start but is not live. A fetch, branch switch, pull, rebase, integration, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state. Its optional `ancestry` object requires exact `sourceBranch` and `targetBranch` fields together, captures both commit IDs, and reports `isAncestor`. Each endpoint may be an exact local branch or a remote-tracking ref such as `origin/main` (local branches take precedence), so a fetched `origin/main` can serve as a read-only containment proof after a pull request merges. This targeted proof is explicit only: automatic Git context remains unchanged. Run it after `integrate_branch` or `fetch_branch` completes, never in the same parallel tool batch.
 
@@ -466,7 +466,7 @@ Repository-configured `reference-transaction` hooks can run during `git update-r
 BranchMe operates only on the repository where pi is running:
 
 - Automatic collection and `branch_status` run bounded, read-only Git commands from the verified git root.
-- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root.
+- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root. A command that fails because another git process holds a lock (`index.lock`, `HEAD.lock`, a ref lock) is retried every 250 ms for up to 10 seconds, then fails with git's error plus a note that the lock was still held; BranchMe never removes a lock file.
 - `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
 - `fetch_branch` uses an explicit source-to-remote-tracking refspec with tags and submodule recursion disabled and does not change local branches or working-tree files. Without arguments it requires a configured upstream; with an explicit `branch` (and optional configured `remote`, default `origin`) it refreshes only `refs/remotes/<remote>/<branch>` and never touches upstream configuration.
 - `pull_branch` requires a clean worktree and configured upstream, updates only the current branch with `git pull --ff-only --no-rebase --no-autostash`, and has no branch, remote, force, or rebase input.

package/docs/STRUCTURE.md

@@ -55,7 +55,7 @@ src/
 - Slash commands are informational; tools perform repository initialization, branch, integration, retirement, worktree, push, and PR actions. Commands never initialize repositories, create/remove worktrees, merge or retire branches, change cwd, or start Pi sessions. There is no context command.
 - Every tool uses a strict TypeBox object schema with `additionalProperties: false`; `init_repository` accepts only optional `initialBranch`; `integrate_branch` requires exactly `sourceBranch` and `targetBranch` with optional boolean `keepConflicts`; `retire_branch` requires exactly `branchName`, full commit `expectedHead`, distinct `targetBranch`, and boolean `force`; `update_from_base` accepts optional boolean `keepConflicts`; `conclude_merge` requires exactly `action` (`conclude` or `abort`); worktree creation requires `worktreePath`, `branchName`, and `branchMode` with optional new-mode `baseRef`, listing is empty, and removal requires `worktreePath` with optional boolean `deleteIgnored`.
 - Every tool defines a description, `promptSnippet`, and tool-specific `promptGuidelines` that explicitly name the tool.
-- Git commands use argv arrays with cwd, signal, and timeout; network calls use the transport wrapper's absolute executable and child environment, while other commands use `pi.exec("git", args, { cwd, signal, timeout })`; `init_repository` uses Pi's file-mutation queue for the new `.git` entry and queues on the canonical target directory, and repository mutations run from verified locations and same-repository mutation/PR windows are serialized per repository. Retirement uses one canonical-active-worktree-keyed queue window from preflight through final verification. The queue is process-local and does not lock a different active worktree, another Pi process, or an external Git process.
+- Git commands use argv arrays with cwd, signal, and timeout; network calls use the transport wrapper's absolute executable and child environment, while other commands use `pi.exec("git", args, { cwd, signal, timeout })`; `runGit` retries a command that failed on another process's `*.lock` every 250 ms for up to 10 s and never touches the lock; `init_repository` uses Pi's file-mutation queue for the new `.git` entry and queues on the canonical target directory, and repository mutations run from verified locations and same-repository mutation/PR windows are serialized per repository. Retirement uses one canonical-active-worktree-keyed queue window from preflight through final verification. The queue is process-local and does not lock a different active worktree, another Pi process, or an external Git process.
 - Worktree results expose serializable requested and verified before/after state. Create returns `handoff: { cwd: <absolute>, branch, head, ready: true, summary }`; remove returns the retained branch/HEAD with `cwd: null` and `ready: false`.
 - Tool details avoid token values, abort signals, runtime objects, and unbounded raw command/API output.
 - Automatic and explicit context include branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged/untracked entries, related open PR state, and up to 5 recent commits. Explicit `branch_status` may additionally verify one strict local or remote-tracking source/target ancestry query; automatic context never does. Metadata values default to 512 characters and rendered context to 4,000 characters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/constants.ts

@@ -56,7 +56,11 @@ export const BRANCHME_TOOL_NAMES = [
   REMOVE_WORKTREE_TOOL_NAME,
 ] as const;
 
-export const GIT_STATUS_TIMEOUT_MS = 5_000;
+// Emulated git (e.g. Rosetta in a container) under parallel agents needs far more than 5 s for a status read.
+export const GIT_STATUS_TIMEOUT_MS = 30_000;
+// A mutation that finds another git process's *.lock retries every interval until the wait ends.
+export const GIT_LOCK_RETRY_INTERVAL_MS = 250;
+export const GIT_LOCK_WAIT_MS = 10_000;
 export const GIT_MUTATION_TIMEOUT_MS = 30_000;
 export const GIT_FETCH_TIMEOUT_MS = 120_000;
 export const GIT_PULL_TIMEOUT_MS = 120_000;

package/src/git.ts

@@ -1,5 +1,6 @@
 import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   GIT_BRANCH_ENTRY_LIMIT,
@@ -9,6 +10,8 @@ import {
   GIT_CONTEXT_RECENT_COMMIT_LIMIT,
   GIT_CONTEXT_VALUE_LIMIT_CHARS,
   GIT_FETCH_TIMEOUT_MS,
+  GIT_LOCK_RETRY_INTERVAL_MS,
+  GIT_LOCK_WAIT_MS,
   GIT_MUTATION_TIMEOUT_MS,
   GIT_PULL_TIMEOUT_MS,
   GIT_PUSH_TIMEOUT_MS,
@@ -128,17 +131,41 @@ export function formatGitFailure(args: readonly string[], result: GitExecResult,
   return `${safeCommandLabel(args, tokens)} failed${killed}: ${reason}`;
 }
 
-export async function runGit(
+// git's "Unable to create '<path>.lock': File exists" for index.lock, HEAD.lock
+// and ref locks: another git process holds the lock.
+const GIT_LOCK_HELD_PATTERN = /Unable to create '[^'\n]*\.lock': File exists/u;
+
+async function runGitWithLockRetry(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   args: string[],
-  options: GitRunOptions = {},
+  options: GitRunOptions,
+  deadline: number,
 ): Promise<GitExecResult> {
   const result = await pi.exec("git", args, {
     cwd: ctx.cwd,
     signal: options.signal,
     timeout: options.timeout ?? GIT_STATUS_TIMEOUT_MS,
   });
+  // Retries depend on the previous failure and must never run concurrently.
+  // The lock belongs to another git process and is never touched here.
+  if (result.killed || result.code === 0 || !GIT_LOCK_HELD_PATTERN.test(result.stderr) || options.signal?.aborted) {
+    return result;
+  }
+  if (Date.now() >= deadline) {
+    return { ...result, stderr: `${result.stderr.trimEnd()}\nThe lock was still held after waiting ${GIT_LOCK_WAIT_MS / 1000} s.` };
+  }
+  await sleep(GIT_LOCK_RETRY_INTERVAL_MS, undefined, { signal: options.signal });
+  return runGitWithLockRetry(pi, ctx, args, options, deadline);
+}
+
+export async function runGit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  args: string[],
+  options: GitRunOptions = {},
+): Promise<GitExecResult> {
+  const result = await runGitWithLockRetry(pi, ctx, args, options, Date.now() + GIT_LOCK_WAIT_MS);
 
   if (result.killed) {
     throw new Error(formatGitFailure(args, result, options.tokens));