@payconductor/houndsman 0.6.0 → 0.8.0

package/src/core/services/worktree-manager.ts

@@ -0,0 +1,269 @@
+/**
+ * Worktrees gerenciados pelo houndsman (biblioteca).
+ *
+ * Um worktree por branch revisada, criado em **detached HEAD** no commit da PR.
+ * Detached evita o conflito "branch já checada" com o clone principal e é o
+ * modo correto para revisão (somente leitura). Vive fora do projeto, em
+ * `<HOUNDSMAN_HOME>/worktrees/<repoSlug>/<branchSlug>`.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createGitRunner } from "../git-runner";
+import { sanitizeBranch } from "../report-builder";
+import { worktreesRoot } from "../storage/paths";
+import { GitRepository } from "./git-repository";
+
+/** Entrada de `git worktree list --porcelain`. */
+export type WorktreeEntry = {
+	path: string;
+	head?: string;
+	/** Ref completo (`refs/heads/...`) quando não detached. */
+	branch?: string;
+	detached: boolean;
+	bare: boolean;
+	prunable: boolean;
+	locked: boolean;
+};
+
+/** Entrada de criação de worktree. */
+export type EnsureWorktreeInput = {
+	branch: string;
+	/** Ref/SHA que o worktree deve apontar. */
+	ref: string;
+};
+
+/** Resultado da criação/reuso. */
+export type EnsureWorktreeResult = {
+	path: string;
+	/** Commit efetivamente checado (detached). */
+	head: string;
+	/** `true` quando o diretório foi criado agora. */
+	created: boolean;
+	/** `true` quando já existia apontando para o commit pedido. */
+	reused: boolean;
+};
+
+/** Resultado da remoção. */
+export type RemoveWorktreeResult = {
+	removed: boolean;
+	detail?: string;
+};
+
+/** Opções do gerenciador. */
+export type WorktreeManagerOptions = {
+	repoKey: string;
+	/** Raiz do clone principal. */
+	repoRoot: string;
+	/**
+	 * Raiz onde os diretórios por repositório são criados.
+	 * Default: `<HOUNDSMAN_HOME>/worktrees` (o CLI normalmente passa
+	 * `resolveWorktreesRoot(config.worktrees?.location, repoRoot)`).
+	 */
+	baseDir?: string;
+};
+
+/** Slug estável e legível para o diretório do repositório. */
+export function repoSlug(repoKey: string): string {
+	const clean = repoKey
+		.replace(/^(remote|path):/, "")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.toLowerCase();
+	const hash = createHash("sha1").update(repoKey).digest("hex").slice(0, 8);
+	return `${clean.slice(-60) || "repo"}-${hash}`;
+}
+
+/** Normaliza um path para comparação (Windows é case-insensitive). */
+function normalizePath(path: string): string {
+	const absolute = resolve(path).replace(/[\\/]+$/, "");
+	return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+
+/** `true` se `path` está dentro de `root`. */
+function isInside(root: string, path: string): boolean {
+	const rel = relative(resolve(root), resolve(path));
+	return rel === "" || (!rel.startsWith("..") && !rel.split(sep).includes(".."));
+}
+
+/** Fatia a saída de `git worktree list --porcelain` em entradas. */
+export function parseWorktreeList(raw: string): WorktreeEntry[] {
+	const entries: WorktreeEntry[] = [];
+	let current: WorktreeEntry | null = null;
+
+	const flush = (): void => {
+		if (current) entries.push(current);
+		current = null;
+	};
+
+	for (const line of raw.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			flush();
+			current = {
+				path: line.slice("worktree ".length).trim(),
+				detached: false,
+				bare: false,
+				prunable: false,
+				locked: false,
+			};
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("HEAD ")) current.head = line.slice(5).trim();
+		else if (line.startsWith("branch ")) current.branch = line.slice(7).trim();
+		else if (line === "detached") current.detached = true;
+		else if (line === "bare") current.bare = true;
+		else if (line.startsWith("prunable")) current.prunable = true;
+		else if (line.startsWith("locked")) current.locked = true;
+	}
+	flush();
+	return entries;
+}
+
+/** Gerencia os worktrees de um repositório. */
+export class WorktreeManager {
+	private readonly git: GitRepository;
+	private readonly repoKey: string;
+	private readonly rootDir: string;
+
+	constructor(git: GitRepository, options: WorktreeManagerOptions) {
+		this.git = git;
+		this.repoKey = options.repoKey;
+		this.rootDir = join(
+			options.baseDir ?? worktreesRoot(),
+			repoSlug(options.repoKey),
+		);
+	}
+
+	/**
+	 * Garante o diretório gerenciado e um `.gitignore` local (`*`), para que
+	 * worktrees dentro do repositório nunca sujem `git status` — mesmo que a
+	 * camada `.houndsman/.gitignore` ainda não tenha sido atualizada.
+	 */
+	private ensureRoot(): void {
+		mkdirSync(this.rootDir, { recursive: true });
+		const ignore = join(this.rootDir, ".gitignore");
+		if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
+	}
+
+	/** Diretório-base dos worktrees deste repositório. */
+	get baseDir(): string {
+		return this.rootDir;
+	}
+
+	/** Caminho determinístico do worktree de uma branch. */
+	pathFor(branch: string): string {
+		const slug = sanitizeBranch(branch) || "branch";
+		return join(this.rootDir, slug);
+	}
+
+	/** Todos os worktrees registrados no repositório. */
+	list(): WorktreeEntry[] {
+		return parseWorktreeList(this.git.worktreeListRaw());
+	}
+
+	/** Apenas os worktrees sob o diretório gerenciado. */
+	managed(): WorktreeEntry[] {
+		return this.list().filter((entry) => isInside(this.rootDir, entry.path));
+	}
+
+	/** Worktree registrado para uma branch (se existir). */
+	find(branch: string): WorktreeEntry | null {
+		const target = normalizePath(this.pathFor(branch));
+		return this.list().find((entry) => normalizePath(entry.path) === target) ?? null;
+	}
+
+	/**
+	 * Garante o worktree da branch no commit `ref`.
+	 *
+	 * Reusa quando o HEAD já é o commit pedido; tenta `checkout --detach` quando
+	 * existe e está em outro commit; recria quando o diretório está quebrado.
+	 */
+	ensure(input: EnsureWorktreeInput): EnsureWorktreeResult {
+		this.ensureRoot();
+		const path = this.pathFor(input.branch);
+		const target = this.git.resolveSha(input.ref);
+		const existing = this.list().find(
+			(entry) => normalizePath(entry.path) === normalizePath(path),
+		);
+
+		if (existing) {
+			if (existing.head === target) {
+				return { path, head: target, created: false, reused: true };
+			}
+			const checkout = new GitRepository(createGitRunner(path)).tryRun([
+				"checkout",
+				"--detach",
+				target,
+			]);
+			if (checkout.ok) {
+				return { path, head: target, created: false, reused: true };
+			}
+			// Worktree quebrado/inacessível: remove e recria do zero.
+			this.git.removeWorktree(path, true);
+			rmSync(path, { recursive: true, force: true });
+		} else if (existsSync(path)) {
+			// Diretório sobrou de um prune/remoção manual.
+			if (!isInside(this.rootDir, path)) {
+				throw new Error(`Worktree fora da raiz gerenciada: ${path}`);
+			}
+			rmSync(path, { recursive: true, force: true });
+		}
+
+		mkdirSync(dirname(path), { recursive: true });
+		try {
+			this.git.addWorktree(path, target);
+		} catch (error) {
+			// Corrida com outro processo ou metadado órfão: pruna e tenta 1x.
+			this.git.pruneWorktrees();
+			try {
+				this.git.addWorktree(path, target);
+			} catch (retry) {
+				const detail = retry instanceof Error ? retry.message : String(retry);
+				const original = error instanceof Error ? error.message : String(error);
+				throw new Error(
+					`Falha ao criar worktree em ${path}: ${detail || original}`,
+				);
+			}
+		}
+		return { path, head: target, created: true, reused: false };
+	}
+
+	/** Remove o worktree de uma branch (ou um path absoluto). */
+	remove(
+		branchOrPath: string,
+		options: { force?: boolean } = {},
+	): RemoveWorktreeResult {
+		const path = isAbsolute(branchOrPath) ? branchOrPath : this.pathFor(branchOrPath);
+		const entry = this.list().find(
+			(worktree) => normalizePath(worktree.path) === normalizePath(path),
+		);
+		if (!entry) {
+			if (existsSync(path) && isInside(this.rootDir, path)) {
+				rmSync(path, { recursive: true, force: true });
+			}
+			return { removed: false, detail: "worktree não registrado" };
+		}
+
+		const result = this.git.removeWorktree(path, options.force ?? false);
+		if (result.ok) return { removed: true };
+
+		if (options.force) {
+			rmSync(path, { recursive: true, force: true });
+			this.git.pruneWorktrees();
+			return { removed: true };
+		}
+		return { removed: false, detail: result.stderr.trim() };
+	}
+
+	/** Limpa metadados de worktrees que não existem mais. */
+	prune(): string {
+		return this.git.pruneWorktrees().stdout.trim();
+	}
+
+	/** Nome legível do repositório gerenciado (diagnóstico). */
+	get name(): string {
+		return basename(this.rootDir) || this.repoKey;
+	}
+}

package/src/core/storage/file/file-storage.ts

@@ -43,12 +43,17 @@ export class FileStorageProvider implements StorageProvider {
 		if (existing) {
 			if (
 				existing.repoRoot !== input.repo.root ||
-				existing.repoRemote !== input.repo.remote
+				existing.repoRemote !== input.repo.remote ||
+				(input.worktreePath !== undefined &&
+					existing.worktreePath !== input.worktreePath) ||
+				(input.prNumber !== undefined && existing.prNumber !== input.prNumber)
 			) {
 				return this.writeReview({
 					...existing,
 					repoRoot: input.repo.root,
 					repoRemote: input.repo.remote,
+					worktreePath: input.worktreePath ?? existing.worktreePath,
+					prNumber: input.prNumber ?? existing.prNumber,
 				});
 			}
 			return existing;
@@ -64,6 +69,8 @@ export class FileStorageProvider implements StorageProvider {
 			slug: input.slug,
 			base: input.base,
 			head: input.head,
+			worktreePath: input.worktreePath,
+			prNumber: input.prNumber,
 			status: null,
 			createdAt: now,
 			updatedAt: now,
@@ -99,11 +106,17 @@ export class FileStorageProvider implements StorageProvider {
 		if (patch.headSha !== undefined) updated.headSha = patch.headSha;
 		if (patch.reviewedSha !== undefined) updated.reviewedSha = patch.reviewedSha;
 		if (patch.reviewedAt !== undefined) updated.reviewedAt = patch.reviewedAt;
+		if (patch.worktreePath !== undefined) updated.worktreePath = patch.worktreePath;
+		if (patch.prNumber !== undefined) updated.prNumber = patch.prNumber;
 		if (patch.status !== undefined) updated.status = patch.status;
 		if (patch.resetStartedAt) updated.startedAt = now;
 		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
 		if (patch.resetHeartbeat) updated.heartbeatAt = undefined;
 		else if (patch.heartbeatAt !== undefined) updated.heartbeatAt = patch.heartbeatAt;
+		if (patch.resetWorkspace) {
+			updated.worktreePath = undefined;
+			updated.prNumber = undefined;
+		}
 		updated.updatedAt = patch.updatedAt ?? now;
 		return this.writeReview(updated);
 	}

package/src/core/storage/paths.ts

@@ -7,9 +7,11 @@
  */
 
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import type { HoundsmanConfig } from "../config";
+import { DEFAULT_WORKTREES_LOCATION } from "../defaults";
 import { ENV_NAMES, env } from "../env";
+import { PROJECT_DIR } from "../paths";
 
 export const HOUNDSMAN_HOME_ENV = ENV_NAMES.home;
 
@@ -52,6 +54,33 @@ export function workRoot(): string {
 	return join(houndsmanHome(), "work");
 }
 
+/** Raiz global dos worktrees (`worktrees.location: "home"`). */
+export function worktreesRoot(): string {
+	return join(houndsmanHome(), "worktrees");
+}
+
+/** Diretório de um worktree gerenciado. */
+export function worktreeDir(repoSlug: string, branchSlug: string): string {
+	return join(worktreesRoot(), repoSlug, branchSlug);
+}
+
+/**
+ * Raiz efetiva dos worktrees de um repositório.
+ *
+ * `workspace` (default) mantém tudo em `<repo>/.houndsman/worktrees` — dentro
+ * da pasta aberta no editor, o que evita prompts de permissão de agentes.
+ * `home` usa o diretório global; outros valores são caminhos do usuário.
+ */
+export function resolveWorktreesRoot(
+	location: string | undefined,
+	repoRoot: string,
+): string {
+	const value = location?.trim() || DEFAULT_WORKTREES_LOCATION;
+	if (value === "home") return worktreesRoot();
+	if (value === "workspace") return join(repoRoot, PROJECT_DIR, "worktrees");
+	return isAbsolute(value) ? value : resolve(repoRoot, value);
+}
+
 /** Referência legível do storage configurado (diagnóstico). */
 export function storageLocation(config: HoundsmanConfig): string {
 	return config.storage?.provider === "file"

package/src/core/storage/sqlite/mappers.ts

@@ -31,6 +31,8 @@ export type ReviewRow = {
 	status: string | null;
 	started_at: string | null;
 	heartbeat_at: string | null;
+	worktree_path: string | null;
+	pr_number: number | null;
 	created_at: string;
 	updated_at: string;
 };
@@ -95,6 +97,8 @@ export function reviewFromRow(row: ReviewRow): ReviewRecord {
 		headSha: row.head_sha ?? undefined,
 		reviewedSha: row.reviewed_sha ?? undefined,
 		reviewedAt: row.reviewed_at ?? undefined,
+		worktreePath: row.worktree_path ?? undefined,
+		prNumber: row.pr_number ?? undefined,
 		status: (row.status as ReviewRecord["status"]) ?? null,
 		startedAt: row.started_at ?? undefined,
 		heartbeatAt: row.heartbeat_at ?? undefined,

package/src/core/storage/sqlite/schema.ts

@@ -7,7 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS reviews (
@@ -25,6 +25,8 @@ CREATE TABLE IF NOT EXISTS reviews (
 	status TEXT,
 	started_at TEXT,
 	heartbeat_at TEXT,
+	worktree_path TEXT,
+	pr_number INTEGER,
 	created_at TEXT NOT NULL,
 	updated_at TEXT NOT NULL,
 	UNIQUE(repo_key, branch)
@@ -105,11 +107,19 @@ export function migrate(db: Database, path: string): void {
 	db.transaction(() => {
 		db.exec(DDL);
 		// v2: heartbeat explícito da execução (bancos v1 não tinham a coluna).
+		// v3: worktree/pr da revisão (revisões paralelas).
 		const columns = db.query("PRAGMA table_info(reviews)").all() as {
 			name: string;
 		}[];
-		if (!columns.some((column) => column.name === "heartbeat_at")) {
-			db.exec("ALTER TABLE reviews ADD COLUMN heartbeat_at TEXT");
+		const missing: [string, string][] = [
+			["heartbeat_at", "TEXT"],
+			["worktree_path", "TEXT"],
+			["pr_number", "INTEGER"],
+		];
+		for (const [name, type] of missing) {
+			if (!columns.some((column) => column.name === name)) {
+				db.exec(`ALTER TABLE reviews ADD COLUMN ${name} ${type}`);
+			}
 		}
 		db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 	})();

package/src/core/storage/sqlite/sqlite-storage.ts

@@ -33,7 +33,7 @@ import { migrate } from "./schema";
 
 /** Colunas mutáveis de review (camel → snake). */
 const REVIEW_PATCH_COLUMNS: Record<
-	Exclude<keyof ReviewPatch, "resetStartedAt" | "resetHeartbeat">,
+	Exclude<keyof ReviewPatch, "resetStartedAt" | "resetHeartbeat" | "resetWorkspace">,
 	string
 > = {
 	branch: "branch",
@@ -43,6 +43,8 @@ const REVIEW_PATCH_COLUMNS: Record<
 	headSha: "head_sha",
 	reviewedSha: "reviewed_sha",
 	reviewedAt: "reviewed_at",
+	worktreePath: "worktree_path",
+	prNumber: "pr_number",
 	status: "status",
 	startedAt: "started_at",
 	heartbeatAt: "heartbeat_at",
@@ -70,13 +72,24 @@ export class SQLiteStorageProvider implements StorageProvider {
 		const existing = this.findReview(input.repo.key, input.branch);
 		if (existing) {
 			// O repo pode ter sido movido; a identidade continua a mesma.
-			if (
+			const moved =
 				existing.repoRoot !== input.repo.root ||
-				existing.repoRemote !== input.repo.remote
-			) {
+				existing.repoRemote !== input.repo.remote;
+			const workspace =
+				(input.worktreePath !== undefined &&
+					existing.worktreePath !== input.worktreePath) ||
+				(input.prNumber !== undefined && existing.prNumber !== input.prNumber);
+			if (moved || workspace) {
 				this.db.run(
-					"UPDATE reviews SET repo_root = ?, repo_remote = ? WHERE id = ?",
-					[input.repo.root, input.repo.remote ?? null, existing.id],
+					`UPDATE reviews SET repo_root = ?, repo_remote = ?, worktree_path = ?,
+					 pr_number = ? WHERE id = ?`,
+					[
+						input.repo.root,
+						input.repo.remote ?? null,
+						input.worktreePath ?? existing.worktreePath ?? null,
+						input.prNumber ?? existing.prNumber ?? null,
+						existing.id,
+					],
 				);
 			}
 			return this.requireReview(existing.id);
@@ -92,6 +105,8 @@ export class SQLiteStorageProvider implements StorageProvider {
 			slug: input.slug,
 			base: input.base,
 			head: input.head,
+			worktreePath: input.worktreePath,
+			prNumber: input.prNumber,
 			status: null,
 			createdAt: now,
 			updatedAt: now,
@@ -99,8 +114,8 @@ export class SQLiteStorageProvider implements StorageProvider {
 		this.db.run(
 			`INSERT INTO reviews
 				(id, repo_key, repo_root, repo_remote, branch, slug, base, head,
-				 created_at, updated_at)
-			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+				 worktree_path, pr_number, created_at, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 			[
 				record.id,
 				record.repoKey,
@@ -110,6 +125,8 @@ export class SQLiteStorageProvider implements StorageProvider {
 				record.slug,
 				record.base ?? null,
 				record.head ?? null,
+				record.worktreePath ?? null,
+				record.prNumber ?? null,
 				record.createdAt,
 				record.updatedAt,
 			],
@@ -163,6 +180,9 @@ export class SQLiteStorageProvider implements StorageProvider {
 		if (patch.resetHeartbeat) {
 			sets.push("heartbeat_at = NULL");
 		}
+		if (patch.resetWorkspace) {
+			sets.push("worktree_path = NULL", "pr_number = NULL");
+		}
 		if (patch.updatedAt === undefined) {
 			sets.push("updated_at = ?");
 			params.push(now);

package/src/core/storage/types.ts

@@ -34,6 +34,10 @@ export type ReviewRecord = {
 	headSha?: string;
 	reviewedSha?: string;
 	reviewedAt?: string;
+	/** Worktree onde a revisão roda (ausente = clone principal). */
+	worktreePath?: string;
+	/** Número da PR revisada (quando iniciada via `--pr`). */
+	prNumber?: number;
 	status: ReviewStatus | null;
 	startedAt?: string;
 	/**
@@ -56,6 +60,8 @@ export type ReviewPatch = Partial<
 		| "headSha"
 		| "reviewedSha"
 		| "reviewedAt"
+		| "worktreePath"
+		| "prNumber"
 		| "status"
 		| "startedAt"
 		| "heartbeatAt"
@@ -66,6 +72,8 @@ export type ReviewPatch = Partial<
 	resetStartedAt?: boolean;
 	/** Limpa o heartbeat (execução terminou). */
 	resetHeartbeat?: boolean;
+	/** Limpa `worktreePath`/`prNumber` (review voltou ao clone principal). */
+	resetWorkspace?: boolean;
 };
 
 /** Entrada de `getOrCreateReview`. */
@@ -75,6 +83,10 @@ export type CreateReviewInput = {
 	slug: string;
 	base?: string;
 	head?: string;
+	/** Worktree onde a revisão roda (ausente = clone principal). */
+	worktreePath?: string;
+	/** Número da PR revisada (quando iniciada via `--pr`). */
+	prNumber?: number;
 	now?: string;
 };
 

package/src/core/storage/work-area.ts

@@ -14,6 +14,7 @@ import {
 	CONTEXT_FILE,
 	CONTEXT_SUMMARY_FILE,
 	displayPath,
+	PROJECT_DIR,
 } from "../paths";
 import type { ContextPaths } from "../pr-context";
 import {
@@ -35,12 +36,26 @@ export type FindingsIngest = {
 	warnings: string[];
 };
 
+/**
+ * Raiz do staging da review.
+ *
+ * Com worktree, tudo (briefs/findings/contexto) fica dentro dele — assim os
+ * agentes leem e escrevem dentro do workspace aberto no editor, sem prompts de
+ * permissão. Sem worktree, mantém o diretório global do houndsman.
+ */
+export function reviewWorkBase(review: ReviewRecord): string {
+	const worktree = review.worktreePath;
+	return worktree && existsSync(worktree)
+		? join(worktree, PROJECT_DIR, "work")
+		: workRoot();
+}
+
 /** Staging de uma review (briefs/findings/contexto). */
 export class ReviewWorkArea {
 	readonly review: ReviewRecord;
 	readonly root: string;
 
-	constructor(review: ReviewRecord, base: string = workRoot()) {
+	constructor(review: ReviewRecord, base: string = reviewWorkBase(review)) {
 		this.review = review;
 		this.root = join(base, review.id);
 	}
@@ -86,6 +101,10 @@ export class ReviewWorkArea {
 	/** Garante os diretórios; `clean` recria a área do zero. */
 	ensure(clean = false): void {
 		if (clean) this.clean();
+		mkdirSync(this.root, { recursive: true });
+		// Staging nunca deve sujar `git status` (especialmente dentro do worktree).
+		const ignore = join(this.root, ".gitignore");
+		if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
 		mkdirSync(this.briefsDir, { recursive: true });
 		mkdirSync(this.findingsDir, { recursive: true });
 	}

package/src/core/types.ts

@@ -135,6 +135,8 @@ export type WatchdogRenderArgs = {
 	branch: string;
 	outputPath: string;
 	outputFormatPath: string;
+	/** Worktree onde a review roda (ausente = clone principal). */
+	worktree?: string;
 	docs: readonly string[];
 	context?: WatchdogRenderContext | null;
 	candidates?: readonly WatchdogRenderCandidate[];

package/src/harness/hunt/hunt-options.ts

@@ -24,6 +24,12 @@ export type HuntOptions = {
 	concurrency?: number;
 	provider?: AiProviderKind;
 	model?: string;
+	/** Número da PR (`--pr`) — o comando resolve/cria o worktree. */
+	pr?: number;
+	/** Worktree informado via flag (relativo ao cwd ou absoluto). */
+	worktree?: string;
+	/** Worktree resolvido (absoluto) para persistir na review. */
+	worktreePath?: string;
 };
 
 /** Defaults do hunt. */
@@ -54,6 +60,17 @@ export function parseHuntArgs(args: string[]): HuntOptions {
 	const model = parser.value("--model");
 	const maxCalls = parser.value("--max-calls");
 	const concurrency = parser.value("--concurrency");
+	const pr = parser.value("--pr");
+	const worktree = parser.value("--worktree");
+	if (pr) {
+		const number = Number.parseInt(pr, 10);
+		if (Number.isFinite(number) && number > 0) options.pr = number;
+		else throw new Error(`--pr inválido: '${pr}'.`);
+	}
+	if (worktree) options.worktree = worktree;
+	if (options.pr !== undefined && options.worktree !== undefined) {
+		throw new Error("Use --pr ou --worktree, não os dois.");
+	}
 	if (base) options.base = base;
 	if (head) options.head = head;
 	if (branch) options.branch = branch;