@payconductor/houndsman 0.7.0 → 0.10.0

package/src/core/project-config.ts

@@ -8,11 +8,13 @@
 
 import type {
 	AiProviderKind,
+	AiProviderOptions,
 	HoundsmanAi,
 	HoundsmanAiFeatures,
 	HoundsmanAst,
 	HoundsmanConfig,
 	HoundsmanStorage,
+	HoundsmanWorktrees,
 } from "./config";
 import {
 	DEFAULT_AI_CONCURRENCY,
@@ -27,6 +29,7 @@ import {
 	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
+	DEFAULT_WORKTREES_LOCATION,
 } from "./defaults";
 import { WatchdogRegistry } from "./watchdog-registry";
 
@@ -48,6 +51,16 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.storage ?? {};
 	}
 
+	/** Config de worktrees (objeto vazio quando ausente). */
+	get worktrees(): HoundsmanWorktrees {
+		return this.raw.worktrees ?? {};
+	}
+
+	/** Localização dos worktrees resolvida (default: workspace). */
+	get worktreesLocation(): string {
+		return this.worktrees.location?.trim() || DEFAULT_WORKTREES_LOCATION;
+	}
+
 	/** Config do AST (objeto vazio quando ausente). */
 	get ast(): HoundsmanAst {
 		return this.raw.ast ?? {};
@@ -126,6 +139,12 @@ export class ProjectConfig<TId extends string = string> {
 		return typeof value === "number" && Number.isFinite(value) ? value : 0;
 	}
 
+	/** Opções do AI SDK por provider (undefined quando ausentes/vazias). */
+	get aiProviderOptions(): AiProviderOptions | undefined {
+		const value = this.ai.providerOptions;
+		return value && Object.keys(value).length > 0 ? value : undefined;
+	}
+
 	get aiTimeoutMs(): number {
 		return positive(this.ai.timeoutMs, DEFAULT_AI_TIMEOUT_MS);
 	}
@@ -140,12 +159,13 @@ export class ProjectConfig<TId extends string = string> {
 		return value !== undefined && value > 0 ? value : undefined;
 	}
 
-	/** Features resolvidas com defaults (`context`/`brief` ligadas). */
+	/** Features resolvidas com defaults (`context`/`brief`/`technical` ligadas). */
 	get aiFeatures(): Required<HoundsmanAiFeatures> {
 		const features = this.ai.features ?? {};
 		return {
 			context: features.context !== false,
 			brief: features.brief !== false,
+			technical: features.technical !== false,
 			classification: features.classification === true,
 			preAnalysis: features.preAnalysis === true,
 			verify: features.verify === true,

package/src/core/renderers/resume-renderer.ts

@@ -3,19 +3,16 @@
  *
  * Artefato somente-leitura para humanos: não entra em briefs, não é lido pelos
  * watchdogs e não participa de nenhuma etapa seguinte. Une o contexto de
- * negócio da PR aos números técnicos diretos da revisão, com limite de
+ * negócio da PR aos pontos técnicos estruturais da revisão, com limite de
  * `RESUME_MAX_CHARS`.
  */
 
-import type {
-	ContextSummary,
-	MergedFinding,
-	WatchdogNameResolver,
-} from "../report-builder";
+import type { ContextSummary, MergedFinding } from "../report-builder";
 import { systemClock } from "../services/clock";
+import type { TechnicalSummary } from "../technical-summary";
 
 /** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
-export const RESUME_MAX_CHARS = 2500;
+export const RESUME_MAX_CHARS = 5000;
 
 /** Dados de classificação usados no resumo. */
 export type ResumeClassification = {
@@ -30,11 +27,10 @@ export type ReviewResumeInput = {
 	context?: ContextSummary | null;
 	classification: ResumeClassification;
 	findings: readonly MergedFinding[];
-	nameOf?: WatchdogNameResolver;
+	/** Pontos técnicos estruturais (não achados). */
+	technical?: TechnicalSummary | null;
 };
 
-const identityName: WatchdogNameResolver = (id) => id;
-
 const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
 	blocking: "❌ Mudanças necessárias",
 	attention: "⚠️ Aprovado com ressalvas",
@@ -80,36 +76,24 @@ function businessSection(input: ReviewResumeInput): string[] {
 	if (context.objective) lines.push(context.objective, "");
 	if (context.motivation) lines.push(`**Por quê:** ${context.motivation}`, "");
 	if (context.changeSummary && context.changeSummary.length > 0) {
-		for (const item of context.changeSummary.slice(0, 4)) {
-			lines.push(`- ${truncate(item, 180)}`);
+		for (const item of context.changeSummary.slice(0, 6)) {
+			lines.push(`- ${truncate(item, 240)}`);
 		}
 		lines.push("");
 	}
 	return lines;
 }
 
-/** Achados que exigem ação, em formato direto (máximo 5). */
-function technicalSection(
-	findings: readonly MergedFinding[],
-	nameOf: WatchdogNameResolver,
-): string[] {
-	const relevant = findings
-		.filter(
-			(finding) =>
-				finding.severity === "blocking" || finding.severity === "attention",
-		)
-		.slice(0, 5);
+/** Pontos técnicos estruturais (módulos, contratos, impacto) — não achados. */
+function technicalSection(summary: TechnicalSummary | null | undefined): string[] {
 	const lines = ["## Pontos técnicos", ""];
-	if (relevant.length === 0) {
-		lines.push("- Nenhum bloqueio ou ponto de atenção.", "");
+	if (!summary || (!summary.overview && summary.highlights.length === 0)) {
+		lines.push("Sem mudanças estruturais detectadas nesta revisão.", "");
 		return lines;
 	}
-	for (const finding of relevant) {
-		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-		const watchdogs = finding.watchdogs.map((id) => nameOf(id)).join(", ");
-		lines.push(
-			`- \`${location}\` — ${truncate(finding.message, 130)}${watchdogs ? ` _(${watchdogs})_` : ""}`,
-		);
+	if (summary.overview) lines.push(summary.overview, "");
+	for (const highlight of summary.highlights) {
+		lines.push(`- **${highlight.area}** — ${truncate(highlight.detail, 300)}`);
 	}
 	lines.push("");
 	return lines;
@@ -125,10 +109,9 @@ function clamp(markdown: string, max: number): string {
 
 /**
  * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
- * nasce do contexto já disponível e dos findings consolidados.
+ * nasce do contexto já disponível e dos pontos técnicos persistidos.
  */
 export function renderReviewResume(input: ReviewResumeInput): string {
-	const nameOf = input.nameOf ?? identityName;
 	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
 	const attention = input.findings.filter((f) => f.severity === "attention").length;
 	const status =
@@ -144,7 +127,7 @@ export function renderReviewResume(input: ReviewResumeInput): string {
 		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
 		"",
 		...businessSection(input),
-		...technicalSection(input.findings, nameOf),
+		...technicalSection(input.technical),
 	];
 
 	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);

package/src/core/report-builder.ts

@@ -63,14 +63,14 @@ export type ContextSummary = {
 const VALID_SEVERITIES = new Set<string>(SEVERITY_ORDER);
 
 /**
- * Limites do resumo da PR: mantém o relatório e os briefs enxutos — evita
- * confundir o watchdog humano e estourar o contexto da IA watchdog.
+ * Limites do resumo da PR: o contexto abre o relatório e o resumo final, mas
+ * não pode inflar os briefs — a injeção nos briefs é recortada em `brief.ts`.
  */
 const CONTEXT_LIMITS = {
-	objective: 200,
-	motivation: 240,
-	changeSummaryItem: 160,
-	changeSummaryItems: 4,
+	objective: 400,
+	motivation: 480,
+	changeSummaryItem: 240,
+	changeSummaryItems: 6,
 } as const;
 
 /** Corta `value` em `max` caracteres, sinalizando com reticências. */

package/src/core/services/git-repository.ts

@@ -75,6 +75,52 @@ export class GitRepository {
 	isAncestor(ancestor: string, descendant: string): boolean {
 		return this.tryRun(["merge-base", "--is-ancestor", ancestor, descendant]).ok;
 	}
+	/** SHA do merge-base entre duas refs; `null` quando não há ancestral comum. */
+	mergeBase(base: string, head: string): string | null {
+		const result = this.tryRun(["merge-base", base, head]);
+		const sha = result.ok ? result.stdout.trim() : "";
+		return sha.length > 0 ? sha : null;
+	}
+
+	/**
+	 * Diretório git comum (`.git`) em caminho absoluto. Em um worktree linkado
+	 * aponta para o `.git` do clone principal — é como descobrimos a raiz real.
+	 */
+	gitCommonDir(): string | null {
+		const result = this.tryRun([
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir",
+		]);
+		const dir = result.ok ? result.stdout.trim() : "";
+		return dir.length > 0 ? dir : null;
+	}
+
+	/** Saída crua de `git worktree list --porcelain` (vazia em erro). */
+	worktreeListRaw(): string {
+		const result = this.tryRun(["worktree", "list", "--porcelain"]);
+		return result.ok ? result.stdout : "";
+	}
+
+	/** Cria um worktree detached apontando para `ref` (lança em falha). */
+	addWorktree(path: string, ref: string): string {
+		return this.run(["worktree", "add", "--detach", path, ref]);
+	}
+
+	/** Remove um worktree; nunca lança (devolve o resultado para o chamador). */
+	removeWorktree(path: string, force = false): GitResult {
+		return this.tryRun(["worktree", "remove", ...(force ? ["--force"] : []), path]);
+	}
+
+	/** Remove metadados de worktrees cujo diretório sumiu. */
+	pruneWorktrees(): GitResult {
+		return this.tryRun(["worktree", "prune"]);
+	}
+
+	/** `git fetch --no-tags <remote> <refspecs...>` (nunca lança). */
+	fetch(remote: string, refspecs: readonly string[]): GitResult {
+		return this.tryRun(["fetch", "--no-tags", remote, ...refspecs]);
+	}
 
 	/** Conteúdo de um arquivo num commit; `null` se ausente. */
 	readFileAt(sha: string, path: string): string | null {

package/src/core/services/pr-resolver.ts

@@ -0,0 +1,147 @@
+/**
+ * Resolução de uma PR para revisão (biblioteca).
+ *
+ * Usa `gh pr view` para descobrir head/base e garante os commits localmente.
+ * O head é buscado em `refs/pull/<n>/head`, que funciona também para forks;
+ * o base vem de `origin/<baseRefName>`. Fail-open na leitura, mas a revisão só
+ * começa quando as refs necessárias existem (erro explícito caso contrário).
+ */
+
+import { describeGhError, type GhRunner } from "./gh-client";
+import type { GitRepository } from "./git-repository";
+
+const PR_FIELDS =
+	"number,title,headRefName,baseRefName,headRefOid,isCrossRepository,url,isDraft";
+
+/** Dados mínimos de uma PR para montar o worktree. */
+export type PullRequestInfo = {
+	number: number;
+	title?: string;
+	headRefName: string;
+	baseRefName: string;
+	/** Commit exato do head no momento da consulta. */
+	headSha?: string;
+	isCrossRepository: boolean;
+	isDraft: boolean;
+	url?: string;
+};
+
+/** Resultado da consulta ao `gh`. */
+export type PrResolveResult =
+	| { ok: true; pr: PullRequestInfo }
+	| { ok: false; reason: "gh" | "invalid"; detail: string };
+
+/** Refs locais preparadas para o diff. */
+export type PrRefs = {
+	base: string;
+	head: string;
+	/** `true` quando o fetch trouxe algo novo. */
+	fetched: boolean;
+	/** Aviso (ex.: fetch parcial) para o CLI imprimir. */
+	warning?: string;
+};
+
+type GhPrView = {
+	number?: unknown;
+	title?: unknown;
+	headRefName?: unknown;
+	baseRefName?: unknown;
+	headRefOid?: unknown;
+	isCrossRepository?: unknown;
+	isDraft?: unknown;
+	url?: unknown;
+};
+
+/** Cliente de PR sobre um runner injetável. */
+export class PrResolver {
+	constructor(
+		private readonly runner: GhRunner,
+		private readonly git: GitRepository,
+	) {}
+
+	/** Consulta a PR no GitHub (nunca lança). */
+	resolve(number: number): PrResolveResult {
+		const result = this.runner(["pr", "view", String(number), "--json", PR_FIELDS]);
+		if (!result.ok) {
+			return { ok: false, reason: "gh", detail: describeGhError(result) };
+		}
+
+		let parsed: GhPrView;
+		try {
+			parsed = JSON.parse(result.stdout) as GhPrView;
+		} catch {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "Resposta inválida do gh (JSON malformado).",
+			};
+		}
+
+		const headRefName =
+			typeof parsed.headRefName === "string" ? parsed.headRefName.trim() : "";
+		const baseRefName =
+			typeof parsed.baseRefName === "string" ? parsed.baseRefName.trim() : "";
+		const resolvedNumber = Number(parsed.number);
+		if (
+			!Number.isFinite(resolvedNumber) ||
+			resolvedNumber <= 0 ||
+			headRefName.length === 0 ||
+			baseRefName.length === 0
+		) {
+			return {
+				ok: false,
+				reason: "invalid",
+				detail: "gh não devolveu número/head/base da PR.",
+			};
+		}
+
+		return {
+			ok: true,
+			pr: {
+				number: resolvedNumber,
+				title: typeof parsed.title === "string" ? parsed.title : undefined,
+				headRefName,
+				baseRefName,
+				headSha:
+					typeof parsed.headRefOid === "string"
+						? parsed.headRefOid.trim()
+						: undefined,
+				isCrossRepository: Boolean(parsed.isCrossRepository),
+				isDraft: Boolean(parsed.isDraft),
+				url: typeof parsed.url === "string" ? parsed.url : undefined,
+			},
+		};
+	}
+
+	/**
+	 * Garante base/head da PR no repositório local.
+	 *
+	 * Prefere o SHA informado pelo `gh`; cai para `refs/houndsman/pr-<n>` quando
+	 * o objeto não existe localmente.
+	 */
+	prepareRefs(pr: PullRequestInfo): PrRefs {
+		const headRef = `refs/houndsman/pr-${pr.number}`;
+		const headFetch = this.git.fetch("origin", [
+			`+refs/pull/${pr.number}/head:${headRef}`,
+		]);
+		const baseFetch = this.git.fetch("origin", [pr.baseRefName]);
+
+		const originBase = `origin/${pr.baseRefName}`;
+		const hasOriginBase = this.git.tryRun(["rev-parse", "--verify", originBase]).ok;
+		const base = hasOriginBase ? originBase : pr.baseRefName;
+
+		const hasSha = pr.headSha
+			? this.git.tryRun(["cat-file", "-e", `${pr.headSha}^{commit}`]).ok
+			: false;
+		const head = hasSha && pr.headSha ? pr.headSha : headRef;
+
+		const warning =
+			!headFetch.ok && !hasSha
+				? `Não foi possível buscar o head da PR: ${headFetch.stderr.trim()}`
+				: !baseFetch.ok
+					? `Não foi possível atualizar ${pr.baseRefName}: ${baseFetch.stderr.trim()}`
+					: undefined;
+
+		return { base, head, fetched: headFetch.ok || baseFetch.ok, warning };
+	}
+}

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

@@ -0,0 +1,293 @@
+/**
+ * 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
+ * `<baseDir>/<repoSlug>/<branchSlug>`.
+ *
+ * Os dois segmentos são `<trecho-legível>-<hash8>`: o trecho legível é
+ * truncado porque o checkout de uma PR herda a profundidade dos arquivos do
+ * projeto, e o Windows (MAX_PATH = 260) estoura "Filename too long" com
+ * repo+branch longos. O hash mantém o nome determinístico e único.
+ */
+
+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;
+};
+
+/** Limite do trecho legível no diretório do repositório. */
+const REPO_SLUG_MAX = 24;
+/** Limite do trecho legível no diretório da branch. */
+const BRANCH_SLUG_MAX = 20;
+
+/**
+ * `<trecho legível truncado>-<hash8>`: curto o bastante para o MAX_PATH do
+ * Windows e estável para o mesmo par (repositório, branch).
+ */
+function hashName(key: string, readable: string, max: number, fallback: string): string {
+	const hash = createHash("sha1").update(key).digest("hex").slice(0, 8);
+	// Ponto/traço no fim do nome é descartado pelo Windows; corte antes do hash.
+	const head = readable.slice(0, max).replace(/[-._]+$/, "");
+	return `${head || fallback}-${hash}`;
+}
+
+/** 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();
+	return hashName(repoKey, clean.slice(-REPO_SLUG_MAX), REPO_SLUG_MAX, "repo");
+}
+
+/** Slug estável e curto para o diretório de uma branch. */
+export function branchSlug(branch: string): string {
+	return hashName(branch, sanitizeBranch(branch), BRANCH_SLUG_MAX, "branch");
+}
+
+/** 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 {
+		return join(this.rootDir, branchSlug(branch));
+	}
+
+	/** 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;
+	}
+}