@payconductor/houndsman 0.7.0 → 0.8.0

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;

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

@@ -14,11 +14,9 @@ import {
 	type ModelProvider,
 } from "../../core/ai";
 import type { AstAnalysis } from "../../core/ast/types";
-import { collectDiff } from "../../core/diff-source";
 import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
 import type { RunClassification } from "../../core/engine/review-scope";
 import { parseEntries } from "../../core/file-classifier";
-import { runGit, tryGit } from "../../core/git-runner";
 import type { LoggerLike } from "../../core/logging";
 import type { PrepareResult } from "../../core/orchestrator";
 import { defaultOptions, type ReviewOptions } from "../../core/orchestrator";
@@ -67,6 +65,8 @@ export class HuntSession {
 			clean: options.clean,
 			noAi: true,
 			finalize: false,
+			pr: options.pr,
+			worktreePath: options.worktreePath,
 		};
 
 		const session = engine.session(reviewOptions);
@@ -137,7 +137,7 @@ export class HuntSession {
 			reporter,
 			config: this.deps.config,
 			ast: engine.ast,
-			readFile: defaultFileReader(fileRoot()),
+			readFile: defaultFileReader(engine.root),
 		});
 		const runner = new AgentRunner(factory);
 		const scheduler = new AgentScheduler(
@@ -265,11 +265,11 @@ export class HuntSession {
 		work: import("../../core/storage/work-area").ReviewWorkArea,
 	) {
 		const { engine, options } = this.deps;
-		const diff = collectDiff(options.base, options.head);
+		const diff = engine.git.collectDiff(options.base, options.head);
 		const entries = parseEntries(
-			runGit(["diff", `${options.base}...${options.head}`, "--name-status"]),
+			engine.git.diffNameStatus(options.base, options.head),
 		);
-		const baseRef = mergeBase(options.base, options.head) ?? options.base;
+		const baseRef = engine.git.mergeBase(options.base, options.head) ?? options.base;
 		const ast: Map<string, AstAnalysis> = options.noAst
 			? new Map()
 			: await engine.ast.analyze(entries, diff, baseRef);
@@ -283,7 +283,7 @@ export class HuntSession {
 			context,
 			ast,
 			impact,
-			repoRoot: process.cwd(),
+			repoRoot: engine.root,
 			diff,
 			branch: review.branch,
 			watchdog: options.watchdog,
@@ -357,16 +357,3 @@ function readContextSummary(
 		return null;
 	}
 }
-
-/** Merge-base 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;
-}
-
-/** Raiz do repositório para leitura das tools. */
-function fileRoot(): string {
-	return process.cwd();
-}

package/src/index.ts

@@ -89,6 +89,14 @@ export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
 export { HoundsmanEngine } from "./core/engine/houndsman-engine";
 export { ReviewScopeResolver } from "./core/engine/review-scope";
 export { ReviewSession } from "./core/engine/review-session";
+export type {
+	ResolvedWorkspace,
+	WorkspaceRequest,
+} from "./core/engine/review-workspace";
+export {
+	mainRootOf,
+	resolveReviewWorkspace,
+} from "./core/engine/review-workspace";
 export type { HoundsmanEnv } from "./core/env";
 export { ENV_NAMES, env, readEnv } from "./core/env";
 export {
@@ -171,8 +179,26 @@ export { FixBatchBuilder } from "./core/services/fix-batch-builder";
 export type { GhResult, GhRunner } from "./core/services/gh-client";
 export { GhClient } from "./core/services/gh-client";
 export { GitRepository } from "./core/services/git-repository";
+export type {
+	PrRefs,
+	PrResolveResult,
+	PullRequestInfo,
+} from "./core/services/pr-resolver";
+export { PrResolver } from "./core/services/pr-resolver";
 export { ProjectFiles } from "./core/services/project-files";
 export { Verifier } from "./core/services/verifier";
+export type {
+	EnsureWorktreeInput,
+	EnsureWorktreeResult,
+	RemoveWorktreeResult,
+	WorktreeEntry,
+	WorktreeManagerOptions,
+} from "./core/services/worktree-manager";
+export {
+	parseWorktreeList,
+	repoSlug,
+	WorktreeManager,
+} from "./core/services/worktree-manager";
 export {
 	createMemoryStorage,
 	createStorage,
@@ -226,4 +252,9 @@ export {
 } from "./core/watchdog-registry";
 export type { ServerOptions } from "./server";
 export { createRequestHandler, HoundsmanServer, startServer } from "./server";
+export type {
+	DeleteRunResult,
+	RunDetail,
+	RunListItem,
+} from "./server/run-repository";
 export { RunRepository } from "./server/run-repository";

package/src/server/client/App.tsx

@@ -8,6 +8,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks"
 import { ArtifactsPanel } from "./ArtifactsPanel";
 import { AutoRefresh } from "./AutoRefresh";
 import { CommentsPanel } from "./CommentsPanel";
+import { DeleteRunModal } from "./DeleteRunModal";
 import { Filters, type FiltersState } from "./Filters";
 import { FindingsList } from "./FindingsList";
 import { FileText, Layers, ListIcon, MessageSquare, Refresh, Send } from "./icons";
@@ -17,7 +18,13 @@ import { SubmitModal } from "./SubmitModal";
 import { SummaryBar } from "./SummaryBar";
 import { api, computeSummary } from "./utils/api";
 import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./utils/constants";
-import type { EditorContext, Finding, FindingsResponse, RunSummary } from "./utils/types";
+import type {
+	DeleteRunResponse,
+	EditorContext,
+	Finding,
+	FindingsResponse,
+	RunSummary,
+} from "./utils/types";
 
 type Tab = "resume" | "findings" | "artifacts" | "comments";
 
@@ -67,6 +74,7 @@ export function App() {
 	const [refreshing, setRefreshing] = useState(false);
 	const [syncing, setSyncing] = useState(false);
 	const [submitOpen, setSubmitOpen] = useState(false);
+	const [deleteOpen, setDeleteOpen] = useState(false);
 	/** Editor detectado pelo servidor — base dos links de código. */
 	const [editor, setEditor] = useState<EditorContext>({ kind: "vscode" });
 	/** Refs espelhando estado volátil — o polling não deve recriar o intervalo. */
@@ -212,8 +220,28 @@ export function App() {
 
 	const summary = useMemo(() => computeSummary(data?.findings ?? []), [data]);
 
-	const branch =
-		data?.branch ?? runs.find((run) => run.slug === slug)?.branch ?? slug ?? "";
+	const selectedRun = runs.find((run) => run.slug === slug) ?? null;
+	const branch = data?.branch ?? selectedRun?.branch ?? slug ?? "";
+
+	/** Após excluir: limpa a seleção e escolhe a próxima run da lista. */
+	const afterDelete = useCallback((result: DeleteRunResponse) => {
+		setDeleteOpen(false);
+		setData(null);
+		setSlug(null);
+		if (result.warning) {
+			setError(
+				`Execução excluída, mas o worktree não foi removido: ${result.warning}`,
+			);
+		} else {
+			setError("");
+		}
+		api<{ runs: RunSummary[] }>("/api/runs")
+			.then(({ runs: list }) => {
+				setRuns(list);
+				setSlug(list[0]?.slug ?? null);
+			})
+			.catch((err) => setError(String(err)));
+	}, []);
 
 	return (
 		<div class="app">
@@ -290,7 +318,7 @@ export function App() {
 							branch={branch}
 							findings={data.findings}
 							summary={summary}
-							onOpenArtifacts={() => setTab("artifacts")}
+							onRequestDelete={() => setDeleteOpen(true)}
 						/>
 					)}
 					{slug && tab === "findings" && data && (
@@ -312,13 +340,23 @@ export function App() {
 					{!slug && !error && <p class="empty">Nenhuma execução para triar.</p>}
 				</div>
 				{slug && (
-					<SubmitModal
-						slug={slug}
-						branch={branch}
-						open={submitOpen}
-						onClose={() => setSubmitOpen(false)}
-						onSubmitted={afterSubmit}
-					/>
+					<>
+						<SubmitModal
+							slug={slug}
+							branch={branch}
+							open={submitOpen}
+							onClose={() => setSubmitOpen(false)}
+							onSubmitted={afterSubmit}
+						/>
+						<DeleteRunModal
+							slug={slug}
+							branch={branch}
+							worktreePath={selectedRun?.worktreePath}
+							open={deleteOpen}
+							onClose={() => setDeleteOpen(false)}
+							onDeleted={afterDelete}
+						/>
+					</>
 				)}
 			</main>
 		</div>

package/src/server/client/DeleteRunModal.tsx

@@ -0,0 +1,163 @@
+/**
+ * Modal "Excluir execução": confirma a remoção definitiva da run.
+ *
+ * Apaga a review, findings, histórico de triagem, artefatos e o staging local.
+ * Quando a run tem worktree, oferece removê-lo junto (alterações não commitadas
+ * nele são descartadas).
+ */
+
+import { useEffect, useState } from "preact/hooks";
+import { Spinner, Trash } from "./icons";
+import { api } from "./utils/api";
+import type { DeleteRunResponse } from "./utils/types";
+
+export function DeleteRunModal({
+	slug,
+	branch,
+	worktreePath,
+	open,
+	onClose,
+	onDeleted,
+}: {
+	slug: string;
+	branch: string;
+	worktreePath?: string;
+	open: boolean;
+	onClose: () => void;
+	onDeleted: (result: DeleteRunResponse) => void;
+}) {
+	const [removeWorktree, setRemoveWorktree] = useState(Boolean(worktreePath));
+	const [deleting, setDeleting] = useState(false);
+	const [error, setError] = useState("");
+
+	useEffect(() => {
+		if (!open) return;
+		setRemoveWorktree(Boolean(worktreePath));
+		setDeleting(false);
+		setError("");
+	}, [open, worktreePath]);
+
+	useEffect(() => {
+		if (!open) return;
+		const onKey = (event: KeyboardEvent) => {
+			if (event.key === "Escape" && !deleting) onClose();
+		};
+		document.addEventListener("keydown", onKey);
+		return () => document.removeEventListener("keydown", onKey);
+	}, [open, deleting, onClose]);
+
+	if (!open) return null;
+
+	const confirm = async () => {
+		setDeleting(true);
+		setError("");
+		try {
+			const suffix = removeWorktree && worktreePath ? "?worktree=1" : "";
+			const result = await api<DeleteRunResponse>(`/api/runs/${slug}${suffix}`, {
+				method: "DELETE",
+			});
+			if (!result.deleted) throw new Error("A execução não foi encontrada.");
+			onDeleted(result);
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err));
+		} finally {
+			setDeleting(false);
+		}
+	};
+
+	return (
+		<div class="modal-layer">
+			<button
+				type="button"
+				class="modal-backdrop"
+				aria-label="Fechar"
+				title="Fechar"
+				onClick={() => {
+					if (!deleting) onClose();
+				}}
+			/>
+			<div
+				class="modal"
+				role="dialog"
+				aria-modal="true"
+				aria-label="Excluir execução"
+			>
+				<header class="modal-head">
+					<div>
+						<h2 class="modal-title">Excluir execução</h2>
+						<p class="modal-sub">
+							Esta ação é permanente e apaga a revisão de{" "}
+							<code>{branch}</code>.
+						</p>
+					</div>
+					<button
+						type="button"
+						class="modal-close"
+						title="Fechar"
+						disabled={deleting}
+						onClick={onClose}
+					>
+						×
+					</button>
+				</header>
+
+				<div class="modal-body">
+					<p class="modal-warn">
+						Serão removidos os findings, o histórico de triagem, todos os
+						artefatos (briefs, classificação, manifesto, relatório, verify) e
+						o staging local desta run. O envio já feito ao GitHub não é
+						desfeito.
+					</p>
+
+					{worktreePath && (
+						<label class="modal-check">
+							<input
+								type="checkbox"
+								checked={removeWorktree}
+								disabled={deleting}
+								onChange={(event) =>
+									setRemoveWorktree(event.currentTarget.checked)
+								}
+							/>
+							<span>
+								Excluir também o worktree desta execução. Alterações não
+								commitadas nele serão perdidas.
+								<br />
+								<code>{worktreePath}</code>
+							</span>
+						</label>
+					)}
+
+					{error && <p class="error">{error}</p>}
+				</div>
+
+				<footer class="modal-foot">
+					<span class="submit-label">Run: {branch}</span>
+					<div class="submit-actions">
+						<button
+							type="button"
+							class="btn"
+							disabled={deleting}
+							onClick={onClose}
+						>
+							Cancelar
+						</button>
+						<button
+							type="button"
+							class="btn danger"
+							disabled={deleting}
+							onClick={() => void confirm()}
+						>
+							{deleting ? (
+								<Spinner size={15} class="icon spin" />
+							) : (
+								<Trash size={15} />
+							)}
+							{deleting ? "Excluindo…" : "Excluir execução"}
+						</button>
+					</div>
+				</footer>
+			</div>
+		</div>
+	);
+}

package/src/server/client/ResumePanel.tsx

@@ -10,7 +10,7 @@
 
 import type { ComponentChildren } from "preact";
 import { useEffect, useMemo, useState } from "preact/hooks";
-import { ExternalLink, Layers } from "./icons";
+import { ExternalLink, Layers, Trash } from "./icons";
 import { MarkdownBlocks } from "./MarkdownText";
 import { api } from "./utils/api";
 import { SEVERITY_LABELS, SEVERITY_ORDER } from "./utils/constants";
@@ -79,13 +79,13 @@ export function ResumePanel({
 	branch,
 	findings,
 	summary,
-	onOpenArtifacts,
+	onRequestDelete,
 }: {
 	slug: string;
 	branch: string;
 	findings: Finding[];
 	summary: Summary;
-	onOpenArtifacts: () => void;
+	onRequestDelete: () => void;
 }) {
 	const [resume, setResume] = useState("");
 	const [detail, setDetail] = useState<RunDetail | null>(null);
@@ -241,12 +241,12 @@ export function ResumePanel({
 					<span class={`resume-status ${status.tone}`}>{status.label}</span>
 					<button
 						type="button"
-						class="btn"
-						title="Ver os artefatos brutos da revisão"
-						onClick={onOpenArtifacts}
+						class="btn danger"
+						title="Excluir esta execução, seus findings e artefatos locais"
+						onClick={onRequestDelete}
 					>
-						<Layers size={14} />
-						Ver artefatos
+						<Trash size={14} />
+						Excluir
 					</button>
 				</div>
 			</section>