@payconductor/houndsman 0.7.0 → 0.10.0

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;
 };
 
@@ -90,6 +102,7 @@ export type ArtifactKind =
 	| "finding-report"
 	| "review"
 	| "resume"
+	| "technical"
 	| "domain-review"
 	| "verify"
 	| "ast"

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 });
 	}