@payconductor/houndsman 0.7.0 → 0.10.0

package/src/core/ai/provider-capabilities.ts

@@ -0,0 +1,45 @@
+/**
+ * Capacidades do provider de IA (puro).
+ *
+ * O AI SDK descarta `temperature`/`topP` e emite warning a cada chamada quando
+ * o DeepSeek opera em thinking mode — que é o default nos modelos V4. Enviar o
+ * parâmetro nesse caso não tem efeito: o adapter o omite.
+ */
+
+import type { AiProviderKind, AiProviderOptions } from "../config";
+
+/** `true` quando o modelo DeepSeek usa thinking sem `providerOptions`. */
+function isDeepSeekV4Model(modelId: string): boolean {
+	return !/(^|[/.])deepseek-(?:chat|reasoner|v[1-3](?:\.\d+)?)(?=[-/:.]|$)/.test(
+		modelId,
+	);
+}
+
+/**
+ * `true` quando o DeepSeek vai operar em thinking mode.
+ *
+ * Espelha a resolução do `@ai-sdk/deepseek`: `thinking.type` explícito manda;
+ * sem ele, V4 (e o alias `deepseek-reasoner`) ligam thinking.
+ */
+export function deepSeekThinkingEnabled(
+	modelId: string,
+	providerOptions: AiProviderOptions | undefined,
+): boolean {
+	const thinking = providerOptions?.deepseek?.thinking as
+		| Record<string, unknown>
+		| undefined;
+	const type = thinking?.type;
+	if (type === "disabled") return false;
+	if (type === "enabled" || type === "adaptive") return true;
+	return modelId === "deepseek-reasoner" || isDeepSeekV4Model(modelId);
+}
+
+/** `true` quando `temperature` chega ao provider (não é descartada). */
+export function temperatureApplies(
+	provider: AiProviderKind,
+	modelId: string,
+	providerOptions?: AiProviderOptions,
+): boolean {
+	if (provider !== "deepseek") return true;
+	return !deepSeekThinkingEnabled(modelId, providerOptions);
+}

package/src/core/ai/schemas.ts

@@ -22,12 +22,28 @@ export const ContextSummarySchema = z.object({
 			head: z.string().optional(),
 		})
 		.optional(),
-	objective: z.string().max(200).optional(),
-	motivation: z.string().max(240).optional(),
-	changeSummary: z.array(z.string().max(160)).max(4).optional(),
+	objective: z.string().max(400).optional(),
+	motivation: z.string().max(480).optional(),
+	changeSummary: z.array(z.string().max(240)).max(6).optional(),
 });
 export type ContextSummaryPlan = z.infer<typeof ContextSummarySchema>;
 
+/** Pontos técnicos estruturais do resumo final (`technical-summary.json`). */
+export const TechnicalSummarySchema = z.object({
+	/** Parágrafo curto de abertura (opcional). */
+	overview: z.string().max(600).optional(),
+	highlights: z
+		.array(
+			z.object({
+				area: z.string().min(1).max(80),
+				detail: z.string().min(1).max(400),
+			}),
+		)
+		.max(8)
+		.default([]),
+});
+export type TechnicalSummaryPlan = z.infer<typeof TechnicalSummarySchema>;
+
 /** Plano de revisão sugerido por IA para um brief. */
 export const BriefPlanSchema = z.object({
 	focus: z.array(z.string()).max(5).default([]),

package/src/core/ai/types.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ZodType, ZodTypeAny } from "zod";
-import type { AiProviderKind } from "../config";
+import type { AiProviderKind, AiProviderOptions } from "../config";
 
 /** Uso de tokens de uma chamada (ou acumulado de uma review). */
 export type AiUsage = {
@@ -52,6 +52,8 @@ export type ModelRequest<T> = {
 	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
+	/** Opções do AI SDK por provider (repassadas ao SDK sem interpretação). */
+	providerOptions?: AiProviderOptions;
 	signal?: AbortSignal;
 };
 

package/src/core/ast/service.ts

@@ -27,10 +27,15 @@ export class AstService {
 	private readonly git: GitRepository;
 	private readonly parser: AstParser;
 
-	constructor(config: HoundsmanConfig, git: GitRepository = new GitRepository()) {
+	constructor(
+		config: HoundsmanConfig,
+		git: GitRepository = new GitRepository(),
+		root: string = process.cwd(),
+	) {
 		this.project = new ProjectConfig(config);
 		this.git = git;
-		const layerGrammars = join(process.cwd(), CORE_DIR, "grammars");
+		// Camada do projeto (quando presente); sem ela o parser usa o wasm embarcado.
+		const layerGrammars = join(root, CORE_DIR, "grammars");
 		this.parser = new AstParser({
 			maxFileBytes: this.project.astMaxFileBytes,
 			languages: this.project.ast.languages,

package/src/core/brief.ts

@@ -27,15 +27,36 @@ export const PROCEDURE: readonly string[] = [
 	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
 ];
 
+/** Limites do contexto injetado em cada brief (o resumo final é maior). */
+const BRIEF_CONTEXT_LIMITS = {
+	objective: 200,
+	motivation: 240,
+	changeSummaryItem: 160,
+	changeSummaryItems: 4,
+} as const;
+
 /** Bloco de contexto da PR, injetado no brief de cada watchdog. */
 export function renderBriefContext(context: WatchdogRenderContext): string[] {
 	const lines = ["## Contexto da PR", ""];
-	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
-	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
-	const changeSummary = context.changeSummary ?? [];
+	if (context.objective) {
+		lines.push(
+			`**Objetivo:** ${shorten(context.objective, BRIEF_CONTEXT_LIMITS.objective)}`,
+		);
+	}
+	if (context.motivation) {
+		lines.push(
+			`**Motivação:** ${shorten(context.motivation, BRIEF_CONTEXT_LIMITS.motivation)}`,
+		);
+	}
+	const changeSummary = (context.changeSummary ?? []).slice(
+		0,
+		BRIEF_CONTEXT_LIMITS.changeSummaryItems,
+	);
 	if (changeSummary.length > 0) {
 		lines.push("", "**Resumo das alterações:**", "");
-		for (const item of changeSummary) lines.push(`- ${item}`);
+		for (const item of changeSummary) {
+			lines.push(`- ${shorten(item, BRIEF_CONTEXT_LIMITS.changeSummaryItem)}`);
+		}
 	}
 	lines.push("");
 	return lines;
@@ -265,6 +286,7 @@ export function defaultRenderBrief(
 		`# Brief — ${def.name} (\`${def.id}\`)`,
 		"",
 		`**Branch:** ${args.branch}`,
+		...(args.worktree ? [`**Worktree:** \`${args.worktree}\``] : []),
 		`**Output obrigatório:** \`${args.outputPath}\``,
 		`**Schema do output:** \`${args.outputFormatPath}\``,
 		"",

package/src/core/commands/context.ts

@@ -26,13 +26,21 @@ export function runContextCommand(
 	_config: HoundsmanConfig,
 	storage: StorageProvider,
 	repo: RepoIdentity,
-	opts: { branch?: string } = {},
+	opts: {
+		branch?: string;
+		/** Worktree onde a review roda (persistido na review). */
+		worktreePath?: string;
+		/** PR de origem (persistida na review). */
+		prNumber?: number;
+	} = {},
 ): ContextRunResult {
 	const branch = opts.branch ?? currentBranch();
 	const review = storage.getOrCreateReview({
 		repo,
 		branch,
 		slug: sanitizeBranch(branch),
+		worktreePath: opts.worktreePath,
+		prNumber: opts.prNumber,
 	});
 	const work = new ReviewWorkArea(review);
 	const paths = work.contextPaths;

package/src/core/commands/findings.ts

@@ -10,6 +10,7 @@
  * com o UUID interno no banco.
  */
 
+import { existsSync } from "node:fs";
 import { AiClient } from "../ai/ai-client";
 import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
@@ -107,11 +108,13 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Contexto de uma review (storage + registro + staging). */
+/** Contexto de uma review (storage + registro + staging + raiz). */
 type CommandContext = {
 	storage: StorageProvider;
 	review: ReviewRecord;
 	work: ReviewWorkArea;
+	/** Worktree da review quando existir; senão, a raiz do repositório. */
+	root: string;
 };
 
 /** Resolve a review da branch atual (explícita ou via git). */
@@ -127,7 +130,10 @@ function openContext(
 			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
-	return { storage, review, work: new ReviewWorkArea(review) };
+	const worktree = review.worktreePath;
+	// Sem worktree, mantém a raiz onde o comando foi invocado (comportamento histórico).
+	const root = worktree && existsSync(worktree) ? worktree : process.cwd();
+	return { storage, review, work: new ReviewWorkArea(review), root };
 }
 
 /** Lê o estado de triagem; lança se a review ainda não tem findings. */
@@ -380,7 +386,7 @@ function execute(
 		}
 		case "sync": {
 			const state = loadState(ctx);
-			const result = syncState(state, fileReader(process.cwd()));
+			const result = syncState(state, fileReader(ctx.root));
 			ctx.storage.writeFindings(ctx.review.id, state);
 			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
@@ -517,7 +523,7 @@ async function executeVerify(
 	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
 	const findings = verifier.select(state, filterFrom(parsed));
-	const entries = verifier.verifyLocal(findings, fileReader(process.cwd()));
+	const entries = verifier.verifyLocal(findings, fileReader(ctx.root));
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
@@ -565,7 +571,7 @@ async function executeVerify(
 		} else if (!aiVerifier.enabled) {
 			aiReason = "feature ai.features.verify desligada";
 		} else {
-			const readFile = fileReader(process.cwd());
+			const readFile = fileReader(ctx.root);
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const confidence = await aiVerifier.verify({
 				findings: stillAmbiguous.map((entry) => ({

package/src/core/commands/review.ts

@@ -20,9 +20,22 @@ export function parseReviewArgs(args: string[]): ReviewOptions {
 	const base = parser.value("--base");
 	const head = parser.value("--head");
 	const branch = parser.value("--branch");
+	const pr = parser.value("--pr");
+	const worktree = parser.value("--worktree");
 	if (base) opts.base = base;
 	if (head) opts.head = head;
 	if (branch) opts.branch = branch;
+	if (worktree) opts.worktree = worktree;
+	if (pr) {
+		const number = Number.parseInt(pr, 10);
+		if (!Number.isFinite(number) || number <= 0) {
+			throw new Error(`--pr inválido: '${pr}'.`);
+		}
+		opts.pr = number;
+	}
+	if (opts.pr !== undefined && opts.worktree !== undefined) {
+		throw new Error("Use --pr ou --worktree, não os dois.");
+	}
 
 	if (parser.has("--finalize") || parser.has("--report-only")) opts.finalize = true;
 	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;

package/src/core/commands/scaffold.ts

@@ -219,10 +219,14 @@ export type HoundsmanAst = {
 /** Providers suportados pela camada de IA. */
 export type AiProviderKind = "deepseek" | "openai" | "anthropic";
 
+/** Opções do AI SDK por provider (repassadas sem interpretação). */
+export type AiProviderOptions = Record<string, Record<string, unknown>>;
+
 /** Features de IA do fluxo normal (todas fail-open). */
 export type HoundsmanAiFeatures = {
 	context?: boolean;
 	brief?: boolean;
+	technical?: boolean;
 	classification?: boolean;
 	preAnalysis?: boolean;
 	verify?: boolean;
@@ -245,6 +249,7 @@ export type HoundsmanAi = {
 	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
+	providerOptions?: AiProviderOptions;
 	timeoutMs?: number;
 	maxCallsPerReview?: number;
 	maxTokensPerReview?: number;
@@ -398,10 +403,12 @@ const DOC_MAPPINGS_TEMPLATE = `/**
 export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [];
 `;
 
-const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
-# e \`.runs/\` guarda os artefatos de revisão.
+const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`.
+# \`work/\` e \`worktrees/\` são runtime de revisão (staging e worktrees).
 core/
 .runs/
+work/
+worktrees/
 `;
 
 // ---------------------------------------------------------------------------

package/src/core/config.ts

@@ -57,12 +57,23 @@ export type HoundsmanConcurrency = {
 /** Providers suportados pela camada de IA. */
 export type AiProviderKind = "deepseek" | "openai" | "anthropic";
 
+/**
+ * Opções do AI SDK indexadas pelo id do provider
+ * (`{ deepseek: { thinking: { type: "disabled" } } }`).
+ *
+ * O motor não interpreta o conteúdo: só repassa. Use para controlar
+ * thinking/reasoning sem acoplar a config a um provider específico.
+ */
+export type AiProviderOptions = Record<string, Record<string, unknown>>;
+
 /** Features de IA do fluxo determinístico (todas fail-open). */
 export type HoundsmanAiFeatures = {
 	/** Resume o contexto da PR (`context-summary`) quando o subagente não gerou. */
 	context?: boolean;
 	/** Enriquece os briefs com um plano de revisão sugerido. */
 	brief?: boolean;
+	/** Gera os pontos técnicos estruturais do resumo final. */
+	technical?: boolean;
 	/** Classifica arquivos que nenhum watchdog casou. */
 	classification?: boolean;
 	/** Gera candidatos de pré-análise (substitui o Jev quando disponível). */
@@ -94,8 +105,13 @@ export type HoundsmanAi = {
 	maxSteps?: number;
 	/** Teto de tokens de saída por chamada. */
 	maxOutputTokens?: number;
-	/** Temperatura (default: 0). */
+	/**
+	 * Temperatura (default: 0). Ignorada quando o provider usa thinking
+	 * (DeepSeek V4 liga thinking por default) — nesse caso o motor não a envia.
+	 */
 	temperature?: number;
+	/** Opções do AI SDK por provider (repassadas sem interpretação). */
+	providerOptions?: AiProviderOptions;
 	/** Timeout por chamada em ms (default: 120_000). */
 	timeoutMs?: number;
 	/** Teto de chamadas por review (default: 40). */
@@ -108,6 +124,17 @@ export type HoundsmanAi = {
 	watchdogs?: Record<string, HoundsmanAiWatchdog>;
 };
 
+/** Onde os worktrees de revisão são criados. */
+export type HoundsmanWorktrees = {
+	/**
+	 * `workspace` (default): `<repo>/.houndsman/worktrees` — dentro da pasta
+	 * aberta no editor, então agentes com permissão escopada ao workspace
+	 * conseguem ler/executar sem prompts. `home`: `<HOUNDSMAN_HOME>/worktrees`.
+	 * Qualquer outro valor é um caminho (absoluto ou relativo à raiz do repo).
+	 */
+	location?: "home" | "workspace" | string;
+};
+
 /** Backend de persistência (reviews, findings e artefatos). */
 export type HoundsmanStorage = {
 	/**
@@ -132,6 +159,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
 	/** Persistência das runs e artefatos (default: SQLite global). */
 	storage?: HoundsmanStorage;
+	/** Localização dos worktrees de revisão (default: dentro do workspace). */
+	worktrees?: HoundsmanWorktrees;
 	/**
 	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
 	 * `defineHoundsmanConfig` (não informar manualmente).

package/src/core/defaults.ts

@@ -19,6 +19,13 @@ export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
 /** Concorrência default das chamadas simultâneas ao Jev. */
 export const DEFAULT_JEV_CONCURRENCY = 5;
 
+/**
+ * Localização default dos worktrees: dentro do workspace aberto no editor.
+ * Mantém leitura/execução dentro da pasta do projeto — agentes com permissão
+ * escopada ao workspace não pedem autorização a cada acesso.
+ */
+export const DEFAULT_WORKTREES_LOCATION = "workspace";
+
 /** Teto default de bytes por arquivo no AST (evita bundles/minificados). */
 export const DEFAULT_AST_MAX_FILE_BYTES = 512_000;
 

package/src/core/engine/houndsman-engine.ts

@@ -6,9 +6,11 @@
  * de instanciar/importar tudo diretamente.
  */
 
+import { resolve } from "node:path";
 import { AiClient } from "../ai/ai-client";
 import { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
+import { createGitRunner } from "../git-runner";
 import type { ReviewOptions } from "../orchestrator";
 import { ProjectConfig } from "../project-config";
 import { FileClassifier } from "../services/file-classifier";
@@ -19,9 +21,14 @@ import { createStorage } from "../storage/factory";
 import { resolveRepoIdentity } from "../storage/repo-identity";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { ReviewSession } from "./review-session";
+import { mainRootOf } from "./review-workspace";
 
 /** Colaboradores injetáveis (testes/CLI). */
 export type EngineDeps = {
+	/** Raiz operacional (worktree ou clone principal). */
+	root?: string;
+	/** Raiz do clone principal (identidade/config). */
+	mainRoot?: string;
 	git?: GitRepository;
 	classifier?: FileClassifier;
 	verifier?: Verifier;
@@ -35,6 +42,10 @@ export type EngineDeps = {
 /** Composition root do motor. */
 export class HoundsmanEngine {
 	readonly project: ProjectConfig;
+	/** Onde os arquivos da revisão são lidos (worktree ou clone principal). */
+	readonly root: string;
+	/** Clone principal (identidade estável + camada/config). */
+	readonly mainRoot: string;
 	readonly git: GitRepository;
 	readonly classifier: FileClassifier;
 	readonly verifier: Verifier;
@@ -46,16 +57,27 @@ export class HoundsmanEngine {
 
 	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
 		this.project = new ProjectConfig(raw);
-		this.git = deps.git ?? new GitRepository();
+		this.root = resolve(deps.root ?? process.cwd());
+		this.git = deps.git ?? new GitRepository(createGitRunner(this.root));
+		this.mainRoot = resolve(
+			deps.mainRoot ?? mainRootOf(this.git, this.repoRootFallback()),
+		);
 		this.classifier = deps.classifier ?? new FileClassifier(raw);
 		this.verifier = deps.verifier ?? new Verifier();
 		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
 		this.storage = deps.storage ?? createStorage(raw);
-		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
-		this.ast = deps.ast ?? new AstService(raw, this.git);
+		this.repo =
+			deps.repo ??
+			resolveRepoIdentity(new GitRepository(createGitRunner(this.mainRoot)));
+		this.ast = deps.ast ?? new AstService(raw, this.git, this.root);
 		this.ai = deps.ai ?? new AiClient({ project: this.project });
 	}
 
+	/** Raiz do clone principal a partir do git atual (fallback: `root`). */
+	private repoRootFallback(): string {
+		return this.git.rootPath() ?? this.root;
+	}
+
 	/** Configuração crua (contrato do consumidor). */
 	get config(): HoundsmanConfig {
 		return this.project.raw;
@@ -70,6 +92,7 @@ export class HoundsmanEngine {
 			this.repo,
 			this.ast,
 			this.ai,
+			{ root: this.root, mainRoot: this.mainRoot, git: this.git },
 		);
 	}
 

package/src/core/engine/review-scope.ts

@@ -8,13 +8,12 @@
 import type { AstService } from "../ast/service";
 import type { AstAnalysis, AstFacts } from "../ast/types";
 import type { HoundsmanConfig } from "../config";
-import { churnToRecord, collectDiff, type DiffSource } from "../diff-source";
+import { churnToRecord, type DiffSource } from "../diff-source";
 import { type ClassificationResult, parseEntries } from "../file-classifier";
 import type { FindingsStateFile } from "../findings-state";
-import { collectDiffSince, diffEntries, isAncestor } from "../git-revision";
-import { runGit, tryGit } from "../git-runner";
 import type { MergedFinding } from "../report-builder";
 import { FileClassifier } from "../services/file-classifier";
+import { GitRepository } from "../services/git-repository";
 import { buildCarryover } from "./carryover";
 
 /** Opções que afetam o escopo (subset do `ReviewOptions`). */
@@ -60,11 +59,18 @@ export class ReviewScopeResolver {
 	private readonly options: ScopeOptions;
 	private readonly classifier: FileClassifier;
 	private readonly ast?: AstService;
+	private readonly git: GitRepository;
 
-	constructor(options: ScopeOptions, config: HoundsmanConfig, ast?: AstService) {
+	constructor(
+		options: ScopeOptions,
+		config: HoundsmanConfig,
+		ast?: AstService,
+		git: GitRepository = new GitRepository(),
+	) {
 		this.options = options;
 		this.classifier = new FileClassifier(config);
 		this.ast = ast;
+		this.git = git;
 	}
 
 	/**
@@ -89,18 +95,15 @@ export class ReviewScopeResolver {
 			this.options.full ||
 			this.options.clean ||
 			!prevSha ||
-			!isAncestor(prevSha, headSha)
+			!this.git.isAncestor(prevSha, headSha)
 		) {
-			const diff = collectDiff(this.options.base, this.options.head);
+			const diff = this.git.collectDiff(this.options.base, this.options.head);
 			const entries = parseEntries(
-				runGit([
-					"diff",
-					`${this.options.base}...${this.options.head}`,
-					"--name-status",
-				]),
+				this.git.diffNameStatus(this.options.base, this.options.head),
 			);
 			const baseRef =
-				mergeBase(this.options.base, this.options.head) ?? this.options.base;
+				this.git.mergeBase(this.options.base, this.options.head) ??
+				this.options.base;
 			const ast = this.ast
 				? await this.ast.analyze(entries, diff, baseRef)
 				: undefined;
@@ -119,8 +122,8 @@ export class ReviewScopeResolver {
 		}
 
 		const range = `${prevSha}..${headSha}`;
-		const diff = collectDiffSince(prevSha, headSha);
-		const entries = diffEntries(range);
+		const diff = this.git.collectDiffSince(prevSha, headSha);
+		const entries = parseEntries(this.git.run(["diff", range, "--name-status"]));
 		const changedPaths = new Set(entries.map((entry) => entry.path));
 		const ast = this.ast ? await this.ast.analyze(entries, diff, prevSha) : undefined;
 		const classification: RunClassification = {
@@ -149,11 +152,3 @@ function factsOf(
 	}
 	return facts;
 }
-
-/** SHA do merge-base entre base e head (best effort). */
-function mergeBase(base: string, head: string): string | null {
-	const result = tryGit(["merge-base", base, head]);
-	if (!result.ok) return null;
-	const sha = result.stdout.trim();
-	return sha.length > 0 ? sha : null;
-}

package/src/core/engine/review-session.ts

@@ -7,6 +7,7 @@
 import type { AiClient } from "../ai/ai-client";
 import type { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
+import { createGitRunner } from "../git-runner";
 import {
 	type FinalizeResult,
 	finalize,
@@ -14,10 +15,12 @@ import {
 	prepare,
 	type ReviewContext,
 	type ReviewOptions,
+	type ReviewWorkspaceContext,
 	resolveBranch,
 	reviewContext,
 } from "../orchestrator";
 import { sanitizeBranch } from "../report-builder";
+import { GitRepository } from "../services/git-repository";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 
 /** Uma revisão em andamento (prepare ou finalize). */
@@ -37,6 +40,7 @@ export class ReviewSession {
 		repo: RepoIdentity,
 		ast?: AstService,
 		ai?: AiClient,
+		workspace?: ReviewWorkspaceContext,
 	) {
 		this.config = config;
 		this.options = options;
@@ -51,13 +55,30 @@ export class ReviewSession {
 					slug: sanitizeBranch(branch),
 					base: options.base,
 					head: options.head,
+					worktreePath: options.worktreePath,
+					prNumber: options.pr,
 				});
 		if (!review) {
 			throw new Error(
 				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
 			);
 		}
-		this.context = reviewContext(storage, review);
+		// Um prepare no clone principal invalida um worktree usado antes; o finalize
+		// não mexe (pode ser rodado de outro lugar depois do prepare no worktree).
+		const current =
+			!options.finalize && !options.worktreePath && review.worktreePath
+				? (storage.updateReview(review.id, { resetWorkspace: true }) ?? review)
+				: review;
+		// Finalize sem flag explícita reusa o worktree gravado no prepare.
+		const effective =
+			options.finalize && !options.worktreePath && current.worktreePath
+				? {
+						root: current.worktreePath,
+						mainRoot: workspace?.mainRoot,
+						git: new GitRepository(createGitRunner(current.worktreePath)),
+					}
+				: workspace;
+		this.context = reviewContext(storage, current, effective);
 	}
 
 	/** Resolve a branch (opção explícita ou a atual do git). */
@@ -68,15 +89,17 @@ export class ReviewSession {
 		repo: RepoIdentity,
 		ast?: AstService,
 		ai?: AiClient,
+		workspace?: ReviewWorkspaceContext,
 	): ReviewSession {
 		return new ReviewSession(
 			config,
 			options,
-			resolveBranch(options),
+			resolveBranch(options, workspace?.git),
 			storage,
 			repo,
 			ast,
 			ai,
+			workspace,
 		);
 	}