@senad-d/branchme 0.3.14 → 0.3.16

package/src/git-revert.ts

@@ -0,0 +1,67 @@
+import { inspectIndex, requireSimpleIndex } from "./git-index.ts";
+import { getGitStatus } from "./git-status.ts";
+import { boundedGitText, OBJECT_ID, openGitReader, readGit, errorText, validateKeys, type GitAPI, type GitReader } from "./git-read.ts";
+import { getCurrentBranch, getGitOperationState, isCommitAncestor, runGit, withRepositoryMutationQueue, type GitCommandContext } from "./git.ts";
+
+export interface RevertInput { commit: string; expectedHead: string; expectedIndex: string; worktreePath?: string }
+async function revertInside(host: GitAPI, reader: GitReader, input: RevertInput) {
+  await requireSimpleIndex(reader);
+  const before = await getGitStatus(reader.pi, reader.ctx, {}, reader.signal, reader.tokens);
+  if (before.head !== input.expectedHead || before.index !== input.expectedIndex || before.hasChanges) throw new Error("No-commit revert requires fresh HEAD/index expectations and a clean idle checkout.");
+  if ((await readGit(reader, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"])).stdout) throw new Error("No-commit revert refuses ignored local-only files; preserve them outside the checkout first.");
+  const metadata = (await readGit(reader, ["rev-list", "--parents", "-n", "1", input.commit, "--"])).stdout.trim().split(" ");
+  if (metadata[0] !== input.commit || metadata.length > 2 || !metadata.every(validOid) || !(await isCommitAncestor(reader.pi, reader.ctx, input.commit, input.expectedHead, reader.signal))) throw new Error("Revert requires one non-merge commit already contained in current HEAD.");
+  if (metadata[1]) {
+    const tree = await readGit(reader, ["ls-tree", "-r", "--format=%(objectmode)", metadata[1]]);
+    if (tree.stdout.split("\n").includes("160000")) throw new Error("Reverts introducing gitlinks are unsupported.");
+  }
+  const branch = (await getCurrentBranch(reader.pi, reader.ctx, reader.signal)).currentBranch;
+  const refs = (await readGit(reader, ["show-ref"])).stdout;
+  const config = (await readGit(reader, ["config", "--null", "--list"])).stdout;
+  await inspectIndex(reader);
+  const immediate = await getGitStatus(reader.pi, reader.ctx, {}, reader.signal, reader.tokens);
+  if (immediate.head !== before.head || immediate.index !== before.index || immediate.hasChanges) throw new Error("Checkout changed during revert preparation; inspect git_status again.");
+  reader.signal?.throwIfAborted();
+  let failure: unknown;
+  try { await runGit(host, reader.ctx, ["--no-lazy-fetch", "-c", "rerere.enabled=false", "revert", "--no-commit", input.commit], { signal: reader.signal, timeout: 120000, tokens: reader.tokens }); }
+  catch (error) { failure = error; }
+  const final = { ...reader, signal: undefined };
+  if (failure) {
+    await recoverRevert(host, final, input, before, branch, refs, config);
+    throw new Error(`Revert failed; automatic abort/restoration was verified. ${boundedGitText(errorText(failure), reader.tokens, 2000).text}`);
+  }
+  return verifyRevert(host, final, input, before, branch, refs, config);
+}
+type RevertStatus = Awaited<ReturnType<typeof getGitStatus>>;
+async function recoverRevert(host: GitAPI, final: GitReader, input: RevertInput, before: RevertStatus, branch: string | null, refs: string, config: string) {
+  try {
+    const operation = await getGitOperationState(final.pi, final.ctx);
+    if (operation.active.includes("revert")) {
+      const reverting = (await readGit(final, ["rev-parse", "--verify", "REVERT_HEAD"])).stdout.trim();
+      if (reverting !== input.commit || (await getGitStatus(final.pi, final.ctx)).head !== input.expectedHead) throw new Error("Revert state is not owned by this request.");
+      await runGit(host, final.ctx, ["revert", "--abort"], { timeout: 30000, tokens: final.tokens });
+    }
+    const restored = await getGitStatus(final.pi, final.ctx);
+    if (restored.head !== before.head || restored.index !== before.index || restored.hasChanges || restored.operations.length || (await getCurrentBranch(final.pi, final.ctx)).currentBranch !== branch || (await readGit(final, ["show-ref"])).stdout !== refs || (await readGit(final, ["config", "--null", "--list"])).stdout !== config) throw new Error("Restoration was not verified.");
+  } catch { throw new Error("Revert recovery is uncertain; stop mutations and inspect git_status/git_conflicts. A person must reconcile the checkout; no reset/stash rollback was attempted."); }
+}
+async function verifyRevert(host: GitAPI, final: GitReader, input: RevertInput, before: RevertStatus, branch: string | null, refs: string, config: string) {
+  const applied = await getGitStatus(final.pi, final.ctx, {}, undefined, final.tokens);
+  if (applied.operations.includes("revert")) {
+    const reverting = (await readGit(final, ["rev-parse", "--verify", "REVERT_HEAD"])).stdout.trim();
+    if (reverting !== input.commit || applied.head !== before.head) throw new Error("Successful inverse has uncertain operation ownership; inspect git_status before continuing.");
+    // --no-commit may leave REVERT_HEAD even after a successful application.
+    // Quit only the owned operation; unlike abort this preserves the staged inverse.
+    await runGit(host, final.ctx, ["revert", "--quit"], { timeout: 30000, tokens: final.tokens });
+  }
+  const after = await getGitStatus(final.pi, final.ctx, {}, undefined, final.tokens);
+  if (after.index !== applied.index || after.head !== before.head || after.operations.length || (await getCurrentBranch(final.pi, final.ctx)).currentBranch !== branch || (await readGit(final, ["show-ref"])).stdout !== refs || (await readGit(final, ["config", "--null", "--list"])).stdout !== config) throw new Error("Revert postconditions are uncertain; inspect git_status before another mutation.");
+  return { action: "revert_changes", commit: input.commit, head: after.head, index: after.index, committed: false, stagedPaths: after.entries.map((entry) => entry.path), pathsComplete: after.complete, note: "Inverse changes are staged, not committed. Enumerate git_status for all paths; ordinary commit creation is a separate explicit workflow." };
+}
+function validOid(value: string): boolean { return OBJECT_ID.test(value); }
+export async function revertChanges(host: GitAPI, ctx: GitCommandContext, input: RevertInput, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateKeys(input, ["commit", "expectedHead", "expectedIndex", "worktreePath"]);
+  if (typeof input.commit !== "string" || !OBJECT_ID.test(input.commit) || typeof input.expectedHead !== "string" || !OBJECT_ID.test(input.expectedHead) || !/^[a-f0-9]{64}$/u.test(input.expectedIndex)) throw new TypeError("Require a full commit identity and fresh HEAD/index expectations from git_status.");
+  const reader = await openGitReader(host, ctx, input.worktreePath, signal, tokens);
+  return withRepositoryMutationQueue(reader.ctx.cwd, revertInside.bind(undefined, host, reader, input));
+}

package/src/git-status.ts

@@ -0,0 +1,346 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readlink } from "node:fs/promises";
+import { isAbsolute, join, win32 } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  GIT_CONTEXT_VALUE_LIMIT_CHARS, GIT_DIFF_PATH_LIMIT, GIT_STATUS_CURSOR_LIMIT_CHARS,
+  GIT_STATUS_FILE_LIMIT_BYTES, GIT_STATUS_PAGE_BYTES, GIT_STATUS_PAGE_LIMIT,
+  GIT_STATUS_RAW_LIMIT_BYTES, GIT_WORKTREE_PATH_LIMIT_CHARS,
+} from "./constants.ts";
+import { getCanonicalGitWorktreeRoot, getGitOperationState, resolveRepositoryWorktreeCwd, runGit, type GitCommandContext } from "./git.ts";
+import { redactSecrets } from "./redaction.ts";
+import type { GitStatusDetails, GitStatusEntry, GitStatusToolInput } from "./types.ts";
+
+type GitAPI = Pick<ExtensionAPI, "exec">;
+interface StatusRecord {
+  kind: GitStatusEntry["kind"];
+  path: string;
+  originalPath?: string;
+  indexStatus: string;
+  worktreeStatus: string;
+  submodule: string;
+}
+interface Observation {
+  head: string | null;
+  branch: string | null;
+  detached: boolean;
+  records: StatusRecord[];
+  index: string;
+  snapshot: string;
+  operations: string[];
+}
+const CONTROL = /[\p{Cc}\p{Cf}\u2028\u2029\ufffd]/u;
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+
+function digest(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function safeText(value: string, tokens: readonly string[]): string {
+  return redactSecrets(value, tokens).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeControl);
+}
+
+function escapeControl(character: string): string {
+  return String.raw`\u${character.codePointAt(0)!.toString(16).padStart(4, "0")}`;
+}
+
+function display(value: string, tokens: readonly string[]): string {
+  const safe = safeText(value, tokens);
+  if (safe.length <= GIT_CONTEXT_VALUE_LIMIT_CHARS) return safe;
+  const end = GIT_CONTEXT_VALUE_LIMIT_CHARS - ((safe.codePointAt(GIT_CONTEXT_VALUE_LIMIT_CHARS - 1) ?? 0) > 0xffff ? 1 : 0);
+  return `${safe.slice(0, end)}…`;
+}
+
+function escapeErrorControl(character: string): string {
+  return character === "\n" ? character : escapeControl(character);
+}
+
+function validPath(value: unknown): value is string {
+  return typeof value === "string" && Boolean(value.trim()) && value.length <= GIT_WORKTREE_PATH_LIMIT_CHARS &&
+    !isAbsolute(value) && !win32.isAbsolute(value) && !value.includes("\\") && !CONTROL.test(value) &&
+    !value.split("/").some((part) => part === ".." || part.toLowerCase() === ".git");
+}
+
+function validateInput(input: GitStatusToolInput): void {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["paths", "worktreePath", "after"].includes(key))) {
+    throw new TypeError("git_status accepts only paths, worktreePath, and after.");
+  }
+  if (input.paths !== undefined && (!Array.isArray(input.paths) || !input.paths.length || input.paths.length > GIT_DIFF_PATH_LIMIT || !input.paths.every(validPath))) {
+    throw new TypeError("git_status paths must be 1–25 literal root-relative paths without traversal, .git, backslashes, or controls.");
+  }
+  if (input.worktreePath !== undefined && (typeof input.worktreePath !== "string" || !isAbsolute(input.worktreePath) || input.worktreePath.length > GIT_WORKTREE_PATH_LIMIT_CHARS || CONTROL.test(input.worktreePath))) {
+    throw new TypeError("git_status worktreePath must be a bounded absolute worktree root.");
+  }
+  if (input.after !== undefined && (typeof input.after !== "string" || input.after.length > GIT_STATUS_CURSOR_LIMIT_CHARS || !/^v1\.[a-f0-9]{64}\.[1-9]\d{0,8}$/u.test(input.after))) {
+    throw new TypeError("git_status after must be an unchanged continuation returned by git_status.");
+  }
+}
+
+async function execStatusRead(host: GitAPI, tokens: readonly string[], command: string, args: string[], options: Parameters<GitAPI["exec"]>[2]) {
+  const result = await host.exec(command, ["--no-optional-locks", "--no-lazy-fetch", "--no-pager", "-c", "core.fsmonitor=false", ...args], options);
+  if (result.killed) throw new Error("git_status local read was killed or timed out. Retry once; if repeated, report a local Git inspection failure.");
+  if (result.code !== 0) {
+    if (/unknown option[^\n]*no-lazy-fetch/iu.test(result.stderr)) throw new Error("git_status requires Git with --no-lazy-fetch support; update Git rather than disabling safeguards.");
+    return { ...result, stdout: display(result.stdout, tokens), stderr: display(result.stderr, tokens) };
+  }
+  if (Buffer.byteLength(result.stdout, "utf8") > GIT_STATUS_RAW_LIMIT_BYTES) {
+    throw new Error("git_status raw inspection exceeded the 4 MiB safety limit; complete checkout inspection is unavailable. No partial cleanliness claim is possible.");
+  }
+  return result;
+}
+
+function parseTracked(record: string): StatusRecord {
+  const fields = record.split(" ");
+  const type = fields[0];
+  const count = ({ "1": 8, "2": 9 } as Record<string, number>)[type] ?? 10;
+  const path = fields.slice(count).join(" ");
+  const modeStart = 3;
+  const modeCount = type === "u" ? 4 : 3;
+  const ids = fields.slice(modeStart + modeCount, type === "u" ? 10 : 8);
+  if (!path || !/^[.MADRCUT]{2}$/u.test(fields[1] ?? "") || !/^(?:N\.\.\.|S[.C][.M][.U])$/u.test(fields[2] ?? "") ||
+      !fields.slice(modeStart, modeStart + modeCount).every((mode) => /^[0-7]{6}$/u.test(mode)) ||
+      ids.length !== (type === "u" ? 3 : 2) || !ids.every((id) => OID.test(id)) ||
+      (type === "2" && !/^[RC]\d{1,3}$/u.test(fields[8] ?? ""))) {
+    throw new Error("git_status received malformed tracked-file metadata.");
+  }
+  return { kind: type === "u" ? "conflict" : "tracked", path, indexStatus: fields[1][0], worktreeStatus: fields[1][1], submodule: fields[2] };
+}
+
+function appendStatusRecord(parts: string[], i: number, records: StatusRecord[]): number {
+  const part = parts[i];
+  if (part.startsWith("? ")) {
+    if (part.length === 2) throw new Error("git_status received an empty untracked path.");
+    records.push({ kind: "untracked", path: part.slice(2), indexStatus: "?", worktreeStatus: "?", submodule: "N..." });
+    return i;
+  }
+  if (!/^[12u] /u.test(part)) throw new Error("git_status received unknown porcelain metadata.");
+  const entry = parseTracked(part);
+  if (part.startsWith("2 ")) {
+    const original = parts[++i];
+    if (!original) throw new Error("git_status received an incomplete rename record.");
+    entry.originalPath = original;
+  }
+  records.push(entry);
+  return i;
+}
+
+function parseStatus(raw: string): Pick<Observation, "records" | "head" | "branch" | "detached"> {
+  if (!raw.endsWith("\0")) throw new Error("git_status received incomplete porcelain output.");
+  const parts = raw.slice(0, -1).split("\0");
+  const records: StatusRecord[] = [];
+  let head: string | null | undefined;
+  let branch: string | null | undefined;
+  let i = 0;
+  while (i < parts.length) {
+    const part = parts[i];
+    if (part.startsWith("# branch.oid ")) {
+      head = parseHeadMetadata(part, head);
+    } else if (part.startsWith("# branch.head ")) {
+      branch = parseBranchMetadata(part, branch);
+    } else if (part.startsWith("# branch.upstream ") || part.startsWith("# branch.ab ")) {
+      // Tracking metadata is owned by branch_status, not this file inventory.
+    } else i = appendStatusRecord(parts, i, records);
+    i++;
+  }
+  if (head === undefined || branch === undefined || branch === "") throw new Error("git_status did not receive branch/HEAD metadata.");
+  if (new Set(records.map(recordIdentity)).size !== records.length) throw new Error("git_status received duplicate file records.");
+  records.sort(compareRecords);
+  return { records, head, branch, detached: branch === null };
+}
+
+function parseBranchMetadata(part: string, previous: string | null | undefined): string | null {
+  if (previous !== undefined) throw new Error("git_status received duplicate branch metadata.");
+  return part.slice(14) === "(detached)" ? null : part.slice(14);
+}
+function parseHeadMetadata(part: string, previous: string | null | undefined): string | null {
+  const value = part.slice(13);
+  if (previous !== undefined || (value !== "(initial)" && !OID.test(value))) throw new Error("git_status received invalid HEAD metadata.");
+  return value === "(initial)" ? null : value;
+}
+function recordIdentity(record: StatusRecord): string { return `${record.kind}:${record.path}`; }
+function compareRecords(a: StatusRecord, b: StatusRecord): number {
+  if (a.path < b.path) return -1;
+  return a.path > b.path ? 1 : 0;
+}
+function missing(error: unknown): boolean { return (error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR"; }
+
+/** Never traverse an existing symlink ancestor while fingerprinting a Git path. */
+export async function checkedFilePath(root: string, path: string): Promise<string | null> {
+  if (!validPath(path)) return null;
+  const segments = path.split("/").filter((segment) => segment && segment !== ".");
+  let parent = root;
+  for (const segment of segments.slice(0, -1)) {
+    parent = join(parent, segment);
+    try {
+      const info = await lstat(parent);
+      if (!info.isDirectory() || info.isSymbolicLink()) return null;
+    } catch (error) {
+      if (missing(error)) return join(root, ...segments);
+      throw new Error("git_status could not inspect a working-file ancestor.");
+    }
+  }
+  return join(root, ...segments);
+}
+
+async function metadata(root: string, path: string): Promise<string> {
+  const file = await checkedFilePath(root, path);
+  if (file === null) return "unsupported-path";
+  try {
+    const info = await lstat(file, { bigint: true });
+    return [info.dev, info.ino, info.mode, info.size, info.mtimeNs, info.ctimeNs].join(":");
+  } catch (error) {
+    if (missing(error)) return "missing";
+    throw new Error("git_status could not inspect working-file metadata; checkout state is unknown.");
+  }
+}
+
+async function observe(pi: GitAPI, ctx: GitCommandContext, signal?: AbortSignal): Promise<Observation> {
+  signal?.throwIfAborted();
+  const status = await runGit(pi, ctx, ["-c", "status.relativePaths=false", "status", "--porcelain=v2", "-z", "--branch", "--no-ahead-behind", "--untracked-files=all", "--ignore-submodules=dirty", "--find-renames=50%"], { signal });
+  const parsed = parseStatus(status.stdout);
+  const index = await runGit(pi, ctx, ["ls-files", "--stage", "-v", "-z"], { signal });
+  const operations = await getGitOperationState(pi, ctx, signal);
+  const hash = createHash("sha256").update(JSON.stringify([ctx.cwd, status.stdout, index.stdout, operations]));
+  // Bound filesystem concurrency even for an inventory near the 4 MiB limit.
+  for await (const observations of metadataBatches(ctx.cwd, signal, parsed.records)) {
+    for (const observation of observations) for (const value of observation) hash.update(value);
+  }
+  return { ...parsed, index: digest(index.stdout), snapshot: hash.digest("hex"), operations: operations.active };
+}
+
+async function* metadataBatches(root: string, signal: AbortSignal | undefined, records: StatusRecord[]) {
+  for (let offset = 0; offset < records.length; offset += 25) {
+    yield Promise.all(records.slice(offset, offset + 25).map(recordMetadata.bind(undefined, root, signal)));
+  }
+}
+async function recordMetadata(root: string, signal: AbortSignal | undefined, entry: StatusRecord): Promise<string[]> {
+  signal?.throwIfAborted();
+  const paths = entry.originalPath ? [entry.path, entry.originalPath] : [entry.path];
+  return Promise.all(paths.map(pathMetadata.bind(undefined, root)));
+}
+async function pathMetadata(root: string, path: string): Promise<string> { return JSON.stringify([path, await metadata(root, path)]); }
+
+function normalizeFilter(path: string): string {
+  return path.split("/").filter((part) => part && part !== ".").join("/");
+}
+function matchesPath(path: string, filter: string): boolean { return filter === "" || path === filter || path.startsWith(`${filter}/`); }
+function matchesRecord(filters: string[], entry: StatusRecord): boolean {
+  return filters.length === 0 || filters.some((filter) => matchesPath(entry.path, filter) || (entry.originalPath !== undefined && matchesPath(entry.originalPath, filter)));
+}
+
+export async function fileExpectation(root: string, path: string, signal?: AbortSignal): Promise<NonNullable<GitStatusEntry["worktreeExpectation"]>> {
+  const file = await checkedFilePath(root, path);
+  if (file === null) return { fingerprint: null, reason: "Unsafe path or symlink ancestor; no reusable content expectation." };
+  const before = await metadata(root, path);
+  if (before === "missing") return { fingerprint: digest("missing") };
+  const info = await lstat(file);
+  signal?.throwIfAborted();
+  let hash: string;
+  if (info.isSymbolicLink()) hash = digest(Buffer.concat([Buffer.from("symlink:"), await readlink(file, { encoding: "buffer" })]));
+  else if (!info.isFile()) return { fingerprint: null, reason: "Not a regular file or symlink; no content expectation." };
+  else if (info.size > GIT_STATUS_FILE_LIMIT_BYTES) return { fingerprint: null, reason: "File exceeds the 8 MiB content-expectation limit." };
+  else hash = await regularFileFingerprint(file, info, signal);
+  signal?.throwIfAborted();
+  if (before !== await metadata(root, path)) throw new Error("git_status working file changed during inspection.\nResolve: Restart git_status without after.");
+  return { fingerprint: hash };
+}
+
+async function regularFileFingerprint(file: string, info: Awaited<ReturnType<typeof lstat>>, signal?: AbortSignal): Promise<string> {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > GIT_STATUS_FILE_LIMIT_BYTES) throw new Error("git_status working file changed during inspection.\nResolve: Restart git_status without after.");
+    const buffer = Buffer.alloc(opened.size + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      signal?.throwIfAborted();
+      const chunk = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (!chunk.bytesRead) break;
+      bytesRead += chunk.bytesRead;
+    }
+    if (bytesRead !== opened.size) throw new Error("git_status working file changed during inspection.\nResolve: Restart git_status without after.");
+    return digest(Buffer.concat([Buffer.from(`file:${opened.mode}:`), buffer.subarray(0, bytesRead)]));
+  } finally { await handle.close(); }
+}
+
+function displayedEntry(record: StatusRecord, tokens: readonly string[]): GitStatusEntry {
+  const path = display(record.path, tokens);
+  const originalPath = record.originalPath === undefined ? undefined : display(record.originalPath, tokens);
+  return {
+    ...record, path, ...(originalPath === undefined ? {} : { originalPath }),
+    reusablePath: path === record.path && validPath(path) && (record.originalPath === undefined || (originalPath === record.originalPath && validPath(originalPath))),
+  };
+}
+
+async function inspectDisplayedEntry(root: string, record: StatusRecord, includeExpectation: boolean, signal: AbortSignal | undefined, tokens: readonly string[]) {
+  const entry = displayedEntry(record, tokens);
+  entry.reusablePath &&= await checkedFilePath(root, record.path) !== null;
+  if (entry.reusablePath && record.originalPath) entry.reusablePath = await checkedFilePath(root, record.originalPath) !== null;
+  if (includeExpectation && entry.reusablePath) entry.worktreeExpectation = await fileExpectation(root, record.path, signal);
+  return entry;
+}
+
+async function collectStatus(host: GitAPI, ctx: GitCommandContext, input: GitStatusToolInput, signal: AbortSignal | undefined, tokens: readonly string[]): Promise<GitStatusDetails> {
+  const pi = { exec: execStatusRead.bind(undefined, host, tokens) };
+  const cwd = input.worktreePath === undefined ? ctx.cwd : await resolveRepositoryWorktreeCwd(pi, ctx, input.worktreePath, signal);
+  const root = await getCanonicalGitWorktreeRoot(pi, { cwd }, signal);
+  const rootCtx = { cwd: root };
+  const before = await observe(pi, rootCtx, signal);
+  const filters = [...new Set((input.paths ?? []).map(normalizeFilter))].sort((a, b) => a.localeCompare(b));
+  const binding = digest(JSON.stringify([root, filters, before.snapshot]));
+  const offset = input.after === undefined ? 0 : Number(input.after.split(".")[2]);
+  const records = before.records.filter(matchesRecord.bind(undefined, filters));
+  if (input.after !== undefined && (input.after.split(".")[1] !== binding || offset >= records.length)) {
+    throw new Error("git_status continuation is stale or belongs to a different worktree/filter.\nResolve: Restart git_status without after and enumerate the new snapshot.");
+  }
+  const entries: GitStatusEntry[] = [];
+  let bytes = 0;
+  for (const record of records.slice(offset, offset + GIT_STATUS_PAGE_LIMIT)) {
+    signal?.throwIfAborted();
+    const entry = await inspectDisplayedEntry(root, record, input.paths !== undefined, signal, tokens);
+    const size = Buffer.byteLength(JSON.stringify(entry));
+    if (entries.length && bytes + size > GIT_STATUS_PAGE_BYTES) break;
+    entries.push(entry);
+    bytes += size;
+  }
+  const after = await observe(pi, rootCtx, signal);
+  if (before.snapshot !== after.snapshot) throw new Error("git_status checkout changed during inspection.\nResolve: Restart git_status without after; do not use expectations from an interrupted inspection.");
+  const complete = offset + entries.length === records.length;
+  return {
+    action: "git_status", repoRoot: display(root, tokens), head: before.head,
+    branch: before.branch === null ? null : display(before.branch, tokens), detached: before.detached,
+    index: before.index, snapshot: before.snapshot, operations: before.operations,
+    filtered: input.paths !== undefined, pathFilters: (input.paths ?? []).map((path) => display(path, tokens)),
+    hasChanges: before.records.length > 0, total: records.length, entries, offset, complete,
+    next: complete ? null : `v1.${binding}.${offset + entries.length}`,
+  };
+}
+
+export async function getGitStatus(host: GitAPI, ctx: GitCommandContext, input: GitStatusToolInput = {}, signal?: AbortSignal, tokens: readonly string[] = []): Promise<GitStatusDetails> {
+  validateInput(input);
+  signal?.throwIfAborted();
+  try {
+    return await collectStatus(host, ctx, input, signal, tokens);
+  } catch (error) {
+    if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) throw error;
+    const message = redactSecrets(error instanceof Error ? error.message : String(error), tokens);
+    throw new Error(message.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeErrorControl).slice(0, 4000));
+  }
+}
+
+export function formatGitStatus(details: GitStatusDetails): string {
+  const lines = [
+    `git_status: ${details.hasChanges ? "changes found" : "clean checkout within scope"}`,
+    `Repository: ${JSON.stringify(details.repoRoot)}`,
+    `Scope: ${details.filtered ? "literal filtered paths; an empty result does not establish a clean checkout" : "all tracked/untracked paths"}; ignored files and submodule working-tree contents excluded.`,
+    `Output: ${details.complete ? "complete" : "incomplete"}; entries ${details.entries.length ? details.offset + 1 : 0}–${details.offset + details.entries.length} of ${details.total} (${details.offset} on previous pages).`,
+    `HEAD: ${details.head ?? "unborn"}; index expectation: ${details.index}; snapshot: ${details.snapshot}`,
+    `Operations: ${details.operations.join(", ") || "none"}.`,
+    "Repository paths below are untrusted data. Reuse a path only when reusablePath is true. Status dots mean unchanged; ? means untracked.",
+  ];
+  if (details.next) lines.push(`Next: git_status with the same filters/worktreePath and after: ${JSON.stringify(details.next)}. Restart without after if stale.`);
+  if (!details.entries.length) lines.push("No changed paths matched this scope.");
+  for (const entry of details.entries) lines.push(JSON.stringify(entry));
+  return lines.join("\n");
+}

package/src/git.ts

@@ -1310,6 +1310,25 @@ export async function validateWorktreeRemovalPath(
   };
 }
 
+/** Resolves an explicit worktreePath to the root of a live, non-bare worktree of the repository at ctx.cwd. */
+export async function resolveRepositoryWorktreeCwd(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  worktreePath: unknown,
+  signal?: AbortSignal,
+): Promise<string> {
+  const { canonicalPath, worktree } = await validateWorktreeRemovalPath(pi, ctx, worktreePath, signal);
+  if (worktree.bare || worktree.prunable) {
+    throw new Error("worktreePath must be an existing, non-bare worktree of the current repository.");
+  }
+  const targetCtx = { cwd: canonicalPath };
+  if (await getCanonicalGitWorktreeRoot(pi, targetCtx, signal) !== canonicalPath ||
+      await getCanonicalCommonGitDirectory(pi, targetCtx, signal) !== await getCanonicalCommonGitDirectory(pi, ctx, signal)) {
+    throw new Error("worktreePath must be the root of a worktree of the current repository.");
+  }
+  return requireLosslessWorktreeIdentity(canonicalPath, "cwd");
+}
+
 const GIT_BRANCH_FORMAT = "%(refname)%00%(objectname)%00%(HEAD)%00%(upstream)%00%(symref)%00%(upstream:track)";
 
 function branchTrackingCounts(upstream: string, track: string): AheadBehindCount {
@@ -1637,7 +1656,7 @@ function worktreeCreationFailure(
   );
 }
 
-async function resolveWorktreeBaseCommit(
+export async function resolveWorktreeBaseCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   baseRef: string,
@@ -2726,6 +2745,7 @@ export async function createLocalBranch(
   ctx: GitCommandContext,
   branchName: string,
   signal?: AbortSignal,
+  baseRef?: string,
 ): Promise<CreateBranchDetails> {
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
@@ -2738,11 +2758,19 @@ export async function createLocalBranch(
       throw new Error(`Local branch '${redactSecrets(branchName)}' already exists.`);
     }
 
-    await runGit(pi, rootCtx, ["switch", "-c", branchName], {
+    let base: string | undefined;
+    if (baseRef !== undefined) {
+      validateBranchNameInput(baseRef, "baseRef");
+      if ((await getGitOperationState(pi, rootCtx, signal)).active.length) throw new Error("An in-progress Git operation must be completed or aborted first.");
+      await requireNoTrackedChanges(pi, rootCtx, "create_branch", signal);
+      base = await resolveWorktreeBaseCommit(pi, rootCtx, baseRef, signal);
+    }
+    await runGit(pi, rootCtx, ["switch", ...(base ? ["--no-overwrite-ignore"] : []), "-c", branchName, ...(base ? [base] : [])], {
       signal,
       timeout: GIT_MUTATION_TIMEOUT_MS,
     });
     const head = await getVerifiedRefCommit(pi, rootCtx, "HEAD", "HEAD", signal);
+    if (base && (head !== base || (await getCurrentBranch(pi, rootCtx, signal)).currentBranch !== branchName)) throw new Error("Branch creation postconditions are uncertain; inspect git_status before continuing.");
 
     return { repoRoot, previousBranch: safeDetail(previousBranch), newBranch: safeDetail(branchName), head };
   });

package/src/github-api.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getGitRoot } from "./git.ts";
+import { gitHubJsonHeaders, readBoundedResponseText, resolveGitHubRepository, resolveGitHubToken, type PullRequestFetchOptions } from "./github.ts";
+import { boundedGitText } from "./git-read.ts";
+import type { GitHubRepository } from "./types.ts";
+import type { BranchMeToolOptions } from "./tools/branchme-tools.ts";
+export interface GitHubClient { repository: GitHubRepository; token: string; fetchImpl: typeof fetch; signal?: AbortSignal }
+export async function openGitHubClient(pi: Pick<ExtensionAPI, "exec">, ctx: { cwd: string }, options: BranchMeToolOptions, signal?: AbortSignal): Promise<GitHubClient> {
+  signal?.throwIfAborted();
+  const cwd = await getGitRoot(pi, ctx, signal);
+  const repository = await resolveGitHubRepository(pi, { cwd }, signal, options.env);
+  const token = (await resolveGitHubToken(options.env, { cwd, signal })).token;
+  return { repository, token, signal, fetchImpl: options.fetchImpl ?? globalThis.fetch };
+}
+export function clientOptions(client: GitHubClient): PullRequestFetchOptions { return { fetchImpl: client.fetchImpl, signal: client.signal }; }
+export function apiPath(client: GitHubClient, suffix: string): string { return `/repos/${encodeURIComponent(client.repository.owner)}/${encodeURIComponent(client.repository.repo)}${suffix}`; }
+export async function githubRequest(client: GitHubClient, path: string, method = "GET", body?: unknown): Promise<unknown> {
+  client.signal?.throwIfAborted();
+  const deadline = AbortSignal.timeout(10000);
+  const signal = client.signal ? AbortSignal.any([client.signal, deadline]) : deadline;
+  try {
+    const response = await client.fetchImpl(`https://api.github.com${path}`, { method, headers: gitHubJsonHeaders(client.token), redirect: "error", signal, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    const result = await readBoundedResponseText(response, signal);
+    if (result.truncated) throw new Error("GitHub response exceeded the 64 KiB safety limit.");
+    if (!response.ok) throw new Error(`GitHub HTTP ${response.status}; request refused or unavailable.`);
+    return JSON.parse(result.text) as unknown;
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    throw new Error(boundedGitText(String(error), [client.token], 2000).text);
+  }
+}
+export function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Malformed GitHub object.");
+  return value as Record<string, unknown>;
+}
+export function positiveNumber(value: unknown): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) throw new Error("Invalid GitHub numeric identity.");
+  return Number(value);
+}

package/src/github-checks.ts

@@ -0,0 +1,88 @@
+import { getGitHubPullRequest } from "./github.ts";
+import { apiPath, clientOptions, githubRequest, positiveNumber, record, type GitHubClient } from "./github-api.ts";
+import { boundedGitText, decodeReadCursor, encodeReadCursor, fingerprint, OBJECT_ID } from "./git-read.ts";
+
+export interface PullRequestChecksInput { number: number; after?: string }
+export interface PullRequestPolicy { available: boolean; head: string | null; base: string | null; mergeable: string | null; mergeState: string | null; reviewDecision: string | null; rollup: string | null; reason?: string }
+interface CheckEntry { source: string; key: string; id: number; name: string; state: string; conclusion: string | null; url: string }
+function safe(value: unknown, client: GitHubClient, max = 256): string { return boundedGitText(typeof value === "string" ? value : "", [client.token], max, 1).text; }
+const POLICY_QUERY = `query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){headRefOid baseRefOid mergeable mergeStateStatus reviewDecision commits(last:1){nodes{commit{statusCheckRollup{state}}}}}}}`;
+export async function getPullRequestPolicy(client: GitHubClient, number: number): Promise<PullRequestPolicy> {
+  try {
+    const response = record(await githubRequest(client, "/graphql", "POST", { query: POLICY_QUERY, variables: { owner: client.repository.owner, repo: client.repository.repo, number } }));
+    if (response.errors) throw new Error("GitHub did not expose complete PR readiness information.");
+    const pr = record(record(record(response.data).repository).pullRequest);
+    if (typeof pr.headRefOid !== "string" || typeof pr.baseRefOid !== "string" || !OBJECT_ID.test(pr.headRefOid) || !OBJECT_ID.test(pr.baseRefOid)) throw new Error("Missing PR readiness identities.");
+    const nodes = record(pr.commits).nodes;
+    if (!Array.isArray(nodes) || nodes.length !== 1) throw new Error("Missing head check rollup.");
+    const rollup = record(nodes[0]).commit;
+    const status = record(rollup).statusCheckRollup;
+    const review = pr.reviewDecision;
+    if (!([null, "APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"] as unknown[]).includes(review)) throw new Error("Unknown review decision.");
+    if (!["MERGEABLE", "CONFLICTING", "UNKNOWN"].includes(String(pr.mergeable)) || !["CLEAN", "BLOCKED", "BEHIND", "DIRTY", "DRAFT", "HAS_HOOKS", "UNKNOWN", "UNSTABLE"].includes(String(pr.mergeStateStatus))) throw new Error("Unknown merge readiness state.");
+    const state = status === null ? null : record(status).state;
+    if (state !== null && (typeof state !== "string" || !["SUCCESS", "FAILURE", "PENDING", "ERROR", "EXPECTED"].includes(state))) throw new Error("Unknown head rollup state.");
+    return { available: true, head: pr.headRefOid, base: pr.baseRefOid, mergeable: String(pr.mergeable), mergeState: String(pr.mergeStateStatus), reviewDecision: review as string | null, rollup: state as string | null };
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    return { available: false, head: null, base: null, mergeable: null, mergeState: null, reviewDecision: null, rollup: null, reason: safe(String(error), client) };
+  }
+}
+function count(value: unknown): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) throw new Error("Missing check completeness count.");
+  return Number(value);
+}
+async function checkPage(client: GitHubClient, head: string, page: number, source: "runs" | "statuses") {
+  try {
+    const suffix = source === "runs" ? `/commits/${head}/check-runs?filter=latest&per_page=25&page=${page}` : `/commits/${head}/status?per_page=25&page=${page}`;
+    const result = record(await githubRequest(client, apiPath(client, suffix)));
+    const rows = source === "runs" ? result.check_runs : result.statuses;
+    if (!Array.isArray(rows) || rows.length > 25) throw new Error("Malformed check page.");
+    const entries = new Map<string, CheckEntry>();
+    for (const row of rows) {
+      const entry = parseCheckEntry(client, source, row);
+      if (!entries.has(entry.key) || entries.get(entry.key)!.id < entry.id) entries.set(entry.key, entry);
+    }
+    return { available: true, total: count(result.total_count), entries: [...entries.values()], error: null };
+  } catch (error) {
+    if (client.signal?.aborted) throw error;
+    return { available: false, total: null, entries: [], error: safe(String(error), client) };
+  }
+}
+function parseCheckEntry(client: GitHubClient, source: "runs" | "statuses", row: unknown): CheckEntry {
+  const item = record(row);
+  const id = positiveNumber(item.id);
+  const rawName = source === "runs" ? item.name : item.context;
+  if (typeof rawName !== "string" || !rawName) throw new Error("Check context missing.");
+  const app = source === "runs" ? positiveNumber(record(item.app).id) : "legacy";
+  const key = fingerprint(JSON.stringify([source, app, rawName]));
+  const state = source === "runs" ? item.status : item.state;
+  const conclusion = source === "runs" ? item.conclusion : item.state;
+  if (typeof state !== "string" || (conclusion !== null && typeof conclusion !== "string")) throw new Error("Check state missing.");
+  return { source, key, id, name: safe(rawName, client, 128), state: safe(state, client, 64), conclusion: conclusion === null ? null : safe(conclusion, client, 64), url: safe(item.html_url ?? item.target_url, client) };
+}
+function checkVerdict(unavailable: boolean, entryCount: number, page: number, complete: boolean, passed: boolean): string {
+  if (unavailable) return "unknown";
+  if (!entryCount && page === 1 && complete) return "no-checks";
+  if (complete && page === 1 && passed) return "passed";
+  return "inspect-states";
+}
+export async function getPullRequestChecks(client: GitHubClient, input: PullRequestChecksInput) {
+  positiveNumber(input.number);
+  const pr = await getGitHubPullRequest(client.repository, input.number, client.token, clientOptions(client));
+  const binding = fingerprint(JSON.stringify([client.repository, input.number, pr.headSha]));
+  let page = 1;
+  if (input.after !== undefined) {
+    const cursor = decodeReadCursor(input.after);
+    if (cursor.length !== 3 || cursor[0] !== "checks1" || cursor[1] !== binding || !Number.isSafeInteger(cursor[2]) || Number(cursor[2]) < 2 || Number(cursor[2]) > 1000) throw new Error("PR checks continuation is stale or invalid; restart without after.");
+    page = Number(cursor[2]);
+  }
+  const [runs, statuses, policy] = await Promise.all([checkPage(client, pr.headSha, page, "runs"), checkPage(client, pr.headSha, page, "statuses"), getPullRequestPolicy(client, input.number)]);
+  const current = await getGitHubPullRequest(client.repository, input.number, client.token, clientOptions(client));
+  const headChanged = current.headSha !== pr.headSha || current.baseSha !== pr.baseSha || (policy.available && (policy.head !== pr.headSha || policy.base !== pr.baseSha));
+  const complete = !headChanged && runs.available && statuses.available && page * 25 >= Math.max(runs.total ?? Infinity, statuses.total ?? Infinity);
+  const entries = [...runs.entries, ...statuses.entries];
+  const allKnownGood = entries.every((entry) => entry.source === "runs" ? entry.state === "completed" && ["success", "neutral", "skipped"].includes(entry.conclusion ?? "") : entry.state === "success");
+  const verdict = checkVerdict(headChanged || !runs.available || !statuses.available, entries.length, page, complete, allKnownGood && policy.available && policy.rollup === "SUCCESS");
+  return { action: "pull_request_checks", number: pr.number, head: pr.headSha, base: pr.baseSha, headChanged, page, runs, statuses, policy, complete, verdict, policyScope: "Host readiness snapshot, not merge authorization. Required-context/ruleset details may be unavailable; no failing-check list is proof of approval.", next: !headChanged && runs.available && statuses.available && !complete && page < 1000 ? encodeReadCursor(["checks1", binding, page + 1]) : null };
+}