can1357/oh-my-pi · error · ToolError

Current git HEAD is unavailable. Pass `run` explicitly.

Error message

Current git HEAD is unavailable. Pass `run` explicitly.

What it means

requireCurrentGitHead resolves the current HEAD commit SHA from the local git repo and throws when it cannot (no repo, or headSha lookup failed). The message directs the caller to pass `run` explicitly since the SHA cannot be inferred.

Source

Thrown at packages/coding-agent/src/tools/gh-common.ts:125

export const PR_URL_PATTERN = /^https:\/\/([^/]+)\/([^/]+\/[^/]+)\/pull\/(\d+)(?:\/.*)?$/;
export const ISSUE_URL_PATTERN = /^https:\/\/([^/]+)\/([^/]+\/[^/]+)\/issues\/(\d+)(?:\/.*)?$/;

export async function requireCurrentGitBranch(cwd: string, signal?: AbortSignal): Promise<string> {
	const repo = vcs.git(cwd);
	const branch = repo ? await repo.currentBranch(signal).catch(() => null) : null;
	if (!branch) {
		throw new ToolError("Current git branch is unavailable. Pass `branch` or `run` explicitly.");
	}

	return branch;
}

export async function requireCurrentGitHead(cwd: string, signal?: AbortSignal): Promise<string> {
	const repo = vcs.git(cwd);
	const headSha = repo ? await repo.headSha(signal).catch(() => null) : null;
	if (!headSha) {
		throw new ToolError("Current git HEAD is unavailable. Pass `run` explicitly.");
	}

	return headSha;
}

export function formatAuthor(author: GhUser | null | undefined): string | undefined {
	if (!author) return undefined;
	if (author.login) return `@${author.login}`;
	if (author.name) return author.name;
	return undefined;
}

export function formatLabels(labels: GhLabel[] | undefined): string | undefined {
	const names = labels?.map(label => label.name).filter((value): value is string => Boolean(value)) ?? [];
	if (names.length === 0) return undefined;
	return names.join(", ");
}

View on GitHub (pinned to 9690622007)

Solutions

Pass the run explicitly (run URL or run id) instead of relying on HEAD resolution.
Run inside a git repository that has at least one commit.
Check `git rev-parse HEAD` manually to confirm HEAD is resolvable.

Example fix

// before
await executeRunWatch({ cwd });
// after
await executeRunWatch({ cwd, run: "https://github.com/owner/repo/actions/runs/123" });

Defensive patterns

Strategy: validation

Validate before calling

import { $ } from "bun";
const head = await $`git rev-parse HEAD`.cwd(cwd).quiet().nothrow();
if (head.exitCode !== 0) {
  // repo missing/empty: supply the run id explicitly
}

Try / catch

try {
  await executeRunWatch({ cwd });
} catch (err) {
  if (err instanceof ToolError && err.message.includes("Current git HEAD is unavailable")) {
    await executeRunWatch({ cwd, run: runUrlOrId });
  } else throw err;
}

Prevention

In CI or fresh clones, always pass the run identifier explicitly.
Ensure the repo has at least one commit before relying on HEAD inference.
Verify `git rev-parse HEAD` succeeds in the target directory.

When it happens

Trigger: executeRunWatch() (or similar gh run tooling) called without a run identifier in a directory where vcs.git(cwd) returns null or repo.headSha() rejects/returns null — non-repo cwd, empty repo with no commits, git failure.

Common situations: Watching a GitHub Actions run from a freshly initialized repo with zero commits; running outside a repo; detached/broken HEAD.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/10f40fbcba7e72af. Report an issue: GitHub.