opencode-worktree-guardian 0.1.0

package/src/config.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { GuardianConfig, GuardianFinishMode, LoadedGuardianConfig, LoadConfigOptions, RecordLike } from "./types.ts";
+import { errorCode, isRecordLike } from "./types.ts";
+
+export const CONFIG_PATH = path.join(".opencode", "worktree-guardian.json");
+
+export const FINISH_MODES = new Set(["preserve-only", "push-branch", "create-pr", "merge-to-base"]);
+
+export const DEFAULT_CONFIG: GuardianConfig = Object.freeze({
+  remote: "origin",
+  baseBranch: "main",
+  worktreeRoot: ".worktrees/$REPO",
+  branchPrefix: "guardian/",
+  finishMode: "create-pr",
+  autoStart: true,
+  autoFinish: false,
+  autoCleanup: false,
+  safetyRefRetentionDays: 30,
+  allowStashIfUnrelated: false,
+  allowDirtyPaths: [],
+  protectedBranches: ["main", "master", "develop", "production"],
+  lockTimeoutMs: 5_000,
+});
+
+export type ConfigErrorKind = "unsupported_finish_mode";
+export type ConfigBoundaryError = Error & { readonly configErrorKind: ConfigErrorKind };
+
+function configError(kind: ConfigErrorKind, message: string): ConfigBoundaryError {
+  return Object.assign(new Error(message), { configErrorKind: kind });
+}
+
+function uniqueStrings(values: readonly unknown[]): string[] {
+  return [...new Set(values.filter((value): value is string => typeof value === "string" && value.length > 0))];
+}
+
+function isGuardianFinishMode(value: unknown): value is GuardianFinishMode {
+  return typeof value === "string" && FINISH_MODES.has(value);
+}
+
+export function normalizeConfig(input: RecordLike = {}): GuardianConfig {
+  const config = { ...DEFAULT_CONFIG, ...input };
+  if (!isGuardianFinishMode(config.finishMode)) {
+    throw configError("unsupported_finish_mode", `Unsupported worktree guardian finishMode: ${String(config.finishMode)}`);
+  }
+
+  const protectedBranches = uniqueStrings([
+    ...DEFAULT_CONFIG.protectedBranches,
+    ...(Array.isArray(input.protectedBranches) ? input.protectedBranches : []),
+  ]);
+
+  return {
+    ...config,
+    autoStart: config.autoStart !== false,
+    autoFinish: config.autoFinish === true,
+    autoCleanup: config.autoCleanup === true,
+    allowStashIfUnrelated: config.allowStashIfUnrelated === true,
+    allowDirtyPaths: uniqueStrings(Array.isArray(input.allowDirtyPaths) ? input.allowDirtyPaths : []),
+    protectedBranches,
+    lockTimeoutMs: typeof config.lockTimeoutMs === "number" && Number.isFinite(config.lockTimeoutMs) ? config.lockTimeoutMs : DEFAULT_CONFIG.lockTimeoutMs,
+  };
+}
+
+export async function loadConfig(repoRoot: string, options: LoadConfigOptions = {}): Promise<LoadedGuardianConfig> {
+  const fileSystem = options.fs ?? fs;
+  const configPath = options.configPath ?? path.join(repoRoot, CONFIG_PATH);
+  let parsed: RecordLike = {};
+
+  try {
+    const raw = await fileSystem.readFile(configPath, "utf8");
+    const value: unknown = JSON.parse(raw);
+    parsed = isRecordLike(value) ? value : {};
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+
+  return {
+    config: normalizeConfig(parsed),
+    path: configPath,
+    loaded: Object.keys(parsed).length > 0,
+  };
+}
+
+export function expandWorktreeRoot(template: string, repoRoot: string) {
+  const repoName = path.basename(repoRoot);
+  return template.replaceAll("$REPO", repoName);
+}

package/src/delete-paths-apply.ts

@@ -0,0 +1,77 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { buildDeletePathsPreflight, deleteSummary } from "./delete-paths-preflight.ts";
+import type { DeletePathBlocker, DeletePathTarget } from "./delete-paths-preflight.ts";
+
+function createDeleteConfirmToken(preflight: Record<string, unknown>) {
+  const material = {
+    tool: "guardian_delete_paths",
+    repoRoot: preflight.repoRoot,
+    paths: preflight.paths,
+    allowTracked: preflight.allowTracked === true,
+    allowRecursive: preflight.allowRecursive === true,
+    targets: (preflight.targets as DeletePathTarget[] | undefined ?? []).map((target) => ({
+      path: target.path,
+      kind: target.kind,
+      status: target.status,
+      trackedContents: target.trackedContents,
+      fingerprint: target.fingerprint,
+    })),
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+
+function deleteReport(result: Record<string, unknown>, preflight: Record<string, unknown>, removedTargets: DeletePathTarget[] = []) {
+  return {
+    ...result,
+    preflight,
+    report: {
+      action: result.status,
+      mode: preflight.mode,
+      repoRoot: preflight.repoRoot,
+      paths: preflight.paths,
+      approvedTargets: (preflight.targets as DeletePathTarget[] | undefined ?? []).map((target) => target.path),
+      removedTargets: removedTargets.map((target) => target.path),
+      blockers: preflight.blockers,
+      summary: result.summary,
+    },
+  };
+}
+
+async function removeDeleteTarget(target: DeletePathTarget) {
+  await fs.rm(target.absolutePath, { recursive: target.kind === "directory", force: false });
+}
+
+export async function guardianDeletePaths(input: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+  const mode = input.mode;
+  const preflight = await buildDeletePathsPreflight(input);
+  if (mode !== "plan" && mode !== "apply") {
+    const blocker = { reason: "mode must be plan or apply", fatal: true };
+    const blockers = [blocker];
+    const summary = deleteSummary([], blockers);
+    return deleteReport({ ok: false, status: "blocked", reason: blocker.reason, summary, targets: [], blockers }, { ...preflight, blockers, summary });
+  }
+  const targets = preflight.targets as DeletePathTarget[];
+  const blockers = preflight.blockers as DeletePathBlocker[];
+  const summary = preflight.summary as Record<string, unknown>;
+  const fatalBlockers = blockers.filter((blocker) => blocker.fatal);
+  if (fatalBlockers.length > 0 || targets.length === 0) {
+    const reason = fatalBlockers.length > 0 ? "delete paths preflight has fatal blockers" : "no approved delete targets";
+    return deleteReport({ ok: false, status: "blocked", reason, summary, targets, blockers }, preflight);
+  }
+  const confirmToken = createDeleteConfirmToken(preflight);
+  if (mode === "plan") return deleteReport({ ok: true, status: "planned", confirmToken, summary, targets, blockers, suggestedCommands: ["guardian_delete_paths"] }, preflight);
+  if (input.confirmDelete !== true) {
+    return deleteReport({ ok: false, status: "blocked", reason: "confirmDelete=true is required for guardian_delete_paths apply", tokenMatched: false, summary, targets, blockers }, preflight);
+  }
+  if (input.confirmToken !== confirmToken) {
+    return deleteReport({ ok: false, status: "blocked", reason: "confirm token mismatch; re-run mode=plan and apply with confirmDelete=true", tokenMatched: false, summary, targets, blockers }, preflight);
+  }
+  const removedTargets: DeletePathTarget[] = [];
+  for (const target of targets) {
+    await removeDeleteTarget(target);
+    removedTargets.push(target);
+  }
+  const finalSummary = deleteSummary(targets, blockers, removedTargets);
+  return deleteReport({ ok: true, status: "deleted", summary: finalSummary, targets, removedTargets, blockers, suggestedCommands: ["guardian_status"] }, { ...preflight, summary: finalSummary }, removedTargets);
+}

package/src/delete-paths-preflight.ts

@@ -0,0 +1,146 @@
+import path from "node:path";
+import { expandWorktreeRoot, loadConfig } from "./config.ts";
+import { collectDeleteFingerprint } from "./deletion-fingerprint.ts";
+import { getRepoRoot, listWorktrees, runGit, tryGit } from "./git.ts";
+import { isEnoent, isSameOrInside, lstatOrMissing, normalizeRelativePath, parseNullSeparated, recordValue, relativePath, stringArray, uniqueSorted } from "./filesystem-boundaries.ts";
+import { getGuardianPaths, readState } from "./state.ts";
+
+export type DeletePathKind = "directory" | "file" | "symlink" | "other" | "missing";
+export type DeletePathStatus = "tracked" | "ignored" | "untracked" | "missing";
+export type DeletePathBlocker = { path?: string; reason: string; fatal: boolean };
+export type DeletePathTarget = {
+  path: string;
+  absolutePath: string;
+  kind: DeletePathKind;
+  status: DeletePathStatus;
+  trackedContents: string[];
+  ignored: boolean;
+  fingerprint: Array<Record<string, string | number>>;
+};
+
+const PROTECTED_PATH_ROOTS = new Set([".opencode", "node_modules", "vendor", ".pnpm-store"]);
+
+function pathKind(stat: Awaited<ReturnType<typeof lstatOrMissing>>): DeletePathKind {
+  if (!stat) return "missing";
+  if (stat.isSymbolicLink()) return "symlink";
+  if (stat.isDirectory()) return "directory";
+  if (stat.isFile()) return "file";
+  return "other";
+}
+
+function resolveDeletePath(repoRoot: string, deletePath: string) {
+  const absolutePath = path.isAbsolute(deletePath) ? path.resolve(deletePath) : path.resolve(repoRoot, deletePath);
+  const relative = relativePath(repoRoot, absolutePath);
+  return { absolutePath, relative };
+}
+
+async function listTrackedContents(repoRoot: string, relative: string) {
+  const result = await runGit(repoRoot, ["ls-files", "-z", "--", relative]);
+  return parseNullSeparated(result.stdout).map((entry) => normalizeRelativePath(entry)).sort((left, right) => left.localeCompare(right));
+}
+
+async function isIgnoredPath(repoRoot: string, relative: string) {
+  const result = await tryGit(repoRoot, ["check-ignore", "--quiet", "--", relative]);
+  return result.ok;
+}
+
+function protectedPathReason(relative: string) {
+  if (relative === ".git" || relative.startsWith(".git/")) return "git metadata";
+  const firstPart = relative.split("/").filter(Boolean)[0] ?? "";
+  return PROTECTED_PATH_ROOTS.has(firstPart) ? `protected ${firstPart} path` : null;
+}
+
+async function collectDeleteProtectedRoots(repoRoot: string, cwd: string, config: Record<string, unknown>) {
+  const roots = new Map<string, { reason: string; blockInside: boolean }>();
+  const configuredWorktreeRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  roots.set(configuredWorktreeRoot, { reason: "configured Guardian worktree root", blockInside: true });
+  try {
+    const currentRoot = await getRepoRoot(cwd);
+    roots.set(path.resolve(currentRoot), { reason: "current worktree root", blockInside: false });
+  } catch {}
+  for (const entry of await listWorktrees(repoRoot)) {
+    const worktreePath = path.resolve(String(entry.path));
+    if (worktreePath !== path.resolve(repoRoot)) roots.set(worktreePath, { reason: "registered Git worktree path", blockInside: true });
+  }
+  try {
+    const state = await readState(await getGuardianPaths(repoRoot), { repoRoot, config });
+    for (const session of Object.values(recordValue(state.sessions))) {
+      const sessionRecord = recordValue(session);
+      if (typeof sessionRecord.worktree_path === "string" && path.resolve(sessionRecord.worktree_path) !== path.resolve(repoRoot)) {
+        roots.set(path.resolve(sessionRecord.worktree_path), { reason: "registered Guardian session worktree path", blockInside: true });
+      }
+    }
+  } catch {}
+  return [...roots.entries()].map(([root, metadata]) => ({ root, ...metadata })).sort((left, right) => left.root.localeCompare(right.root));
+}
+
+function protectedRootBlocker(absolutePath: string, protectedRoots: Array<{ root: string; reason: string; blockInside: boolean }>) {
+  return protectedRoots.find((entry) => {
+    const resolved = path.resolve(absolutePath);
+    return resolved === entry.root || isSameOrInside(entry.root, resolved) || entry.blockInside && isSameOrInside(resolved, entry.root);
+  });
+}
+
+export function deleteSummary(targets: DeletePathTarget[], blockers: DeletePathBlocker[], removedTargets: DeletePathTarget[] = []) {
+  return {
+    approvedTargetCount: targets.length,
+    blockedTargetCount: blockers.length,
+    fatalBlockerCount: blockers.filter((blocker) => blocker.fatal).length,
+    removedTargetCount: removedTargets.length,
+    trackedTargetCount: targets.filter((target) => target.trackedContents.length > 0).length,
+    directoryTargetCount: targets.filter((target) => target.kind === "directory").length,
+  };
+}
+
+export async function buildDeletePathsPreflight(input: Record<string, unknown>) {
+  const cwd = typeof input.cwd === "string" ? input.cwd : typeof input.repoRoot === "string" ? input.repoRoot : process.cwd();
+  const repoRoot = path.resolve(typeof input.repoRoot === "string" ? input.repoRoot : await getRepoRoot(cwd));
+  const loadedConfig = input.config && typeof input.config === "object" ? { config: input.config as Record<string, unknown> } : await loadConfig(repoRoot);
+  const config = loadedConfig.config;
+  const allowTracked = input.allowTracked === true;
+  const allowRecursive = input.allowRecursive === true;
+  const paths = uniqueSorted(stringArray(input.paths));
+  const blockers: DeletePathBlocker[] = [];
+  if (paths.length === 0) blockers.push({ reason: "paths must include at least one path", fatal: true });
+  const protectedRoots = await collectDeleteProtectedRoots(repoRoot, cwd, config);
+  const targets: DeletePathTarget[] = [];
+  const seenTargets = new Set<string>();
+  for (const requestedPath of paths) {
+    const { absolutePath, relative } = resolveDeletePath(repoRoot, requestedPath);
+    const pathBlockers: DeletePathBlocker[] = [];
+    if (!isSameOrInside(absolutePath, repoRoot)) pathBlockers.push({ path: requestedPath, reason: "delete path is outside the repository root", fatal: true });
+    if (relative === ".") pathBlockers.push({ path: relative, reason: "repository root cannot be deleted by guardian_delete_paths", fatal: true });
+    const protectedReason = protectedPathReason(relative);
+    if (protectedReason) pathBlockers.push({ path: relative, reason: protectedReason, fatal: true });
+    const protectedRoot = protectedRootBlocker(absolutePath, protectedRoots);
+    if (protectedRoot) pathBlockers.push({ path: relative, reason: protectedRoot.reason, fatal: true });
+    const stat = pathBlockers.length > 0 ? null : await lstatOrMissing(absolutePath);
+    const kind = pathKind(stat);
+    if (pathBlockers.length === 0 && stat == null) pathBlockers.push({ path: relative, reason: "delete path is missing", fatal: true });
+    if (kind === "symlink") pathBlockers.push({ path: relative, reason: "symlink delete roots are not allowed", fatal: true });
+    if (kind === "directory" && !allowRecursive) pathBlockers.push({ path: relative, reason: "directory deletion requires allowRecursive=true", fatal: true });
+    const trackedContents = pathBlockers.some((blocker) => blocker.fatal) ? [] : await listTrackedContents(repoRoot, relative);
+    const ignored = pathBlockers.some((blocker) => blocker.fatal) ? false : await isIgnoredPath(repoRoot, relative);
+    const status: DeletePathStatus = stat == null ? "missing" : trackedContents.length > 0 ? "tracked" : ignored ? "ignored" : "untracked";
+    if (trackedContents.length > 0 && !allowTracked) pathBlockers.push({ path: relative, reason: "tracked source deletion requires allowTracked=true", fatal: true });
+    if (pathBlockers.length > 0) {
+      blockers.push(...pathBlockers);
+      continue;
+    }
+    if (!stat || seenTargets.has(relative)) continue;
+    try {
+      targets.push({ path: relative, absolutePath, kind, status, trackedContents, ignored, fingerprint: await collectDeleteFingerprint(repoRoot, absolutePath) });
+      seenTargets.add(relative);
+    } catch (error) {
+      if (!isEnoent(error)) throw error;
+      blockers.push({ path: relative, reason: "delete path disappeared during preflight", fatal: true });
+    }
+  }
+  for (const target of targets) {
+    const overlap = targets.find((candidate) => candidate.path !== target.path && isSameOrInside(path.resolve(repoRoot, candidate.path), path.resolve(repoRoot, target.path)));
+    if (overlap) blockers.push({ path: target.path, reason: `delete paths overlap with ${overlap.path}`, fatal: true });
+  }
+  const preflight: Record<string, unknown> = { repoRoot, mode: input.mode, paths, allowTracked, allowRecursive, targets, blockers };
+  preflight.summary = deleteSummary(targets, blockers);
+  return preflight;
+}

package/src/delete-paths.ts

@@ -0,0 +1 @@
+export { guardianDeletePaths } from "./delete-paths-apply.ts";

package/src/delete-worktree-preflight.ts

@@ -0,0 +1,25 @@
+import { collectIgnoredFileFingerprint } from "./deletion-fingerprint.ts";
+import { isAncestor, listUnmergedCommits } from "./git.ts";
+import { errorMessage } from "./delete-worktree-report.ts";
+
+export { collectIgnoredFileFingerprint };
+
+export async function recordAncestryPreflight(repoRoot: string, head: string, baseRef: string, preflight: Record<string, unknown>) {
+  preflight.ancestryRef = baseRef;
+  const proven = await isAncestor(repoRoot, head, baseRef);
+  preflight.ancestryProven = proven;
+  if (proven) {
+    preflight.unmergedCommits = [];
+    preflight.unmergedCommitCount = 0;
+    return proven;
+  }
+  let unmergedCommits: { commit: string; subject: string | undefined }[] = [];
+  try {
+    unmergedCommits = await listUnmergedCommits(repoRoot, head, baseRef);
+  } catch (error) {
+    preflight.unmergedCommitError = errorMessage(error);
+  }
+  preflight.unmergedCommits = unmergedCommits;
+  preflight.unmergedCommitCount = unmergedCommits.length;
+  return proven;
+}

package/src/delete-worktree-report.ts

@@ -0,0 +1,70 @@
+import crypto from "node:crypto";
+
+export function snapshotPreflight(preflight: Record<string, unknown>) {
+  const snapshot: Record<string, unknown> = { ...preflight, blockers: [...((preflight.blockers as string[] | undefined) ?? [])] };
+  return snapshot;
+}
+
+export function withDeleteReport(result: Record<string, unknown>, preflight: Record<string, unknown>, reportDetails: Record<string, unknown> = {}) {
+  const preflightSnapshot = snapshotPreflight(preflight);
+  return {
+    ...result,
+    preflight: preflightSnapshot,
+    report: {
+      action: reportDetails.action ?? result.status,
+      mode: preflightSnapshot.mode,
+      targetPath: preflightSnapshot.targetPath,
+      branch: preflightSnapshot.branch,
+      head: preflightSnapshot.head,
+      sessionId: preflightSnapshot.sessionId,
+      sessionStatus: preflightSnapshot.sessionStatus,
+      deleteBranch: preflightSnapshot.deleteBranch,
+      abandonUnmerged: preflightSnapshot.abandonUnmerged,
+      ancestryRef: preflightSnapshot.ancestryRef,
+      ancestryProven: preflightSnapshot.ancestryProven,
+      unmergedCommitCount: preflightSnapshot.unmergedCommitCount,
+      dirtyFileCount: preflightSnapshot.dirtyFileCount,
+      ignoredFileCount: preflightSnapshot.ignoredFileCount,
+      stashCount: preflightSnapshot.stashCount,
+      safetyRef: preflightSnapshot.safetyRef ?? result.safetyRef ?? null,
+      blockers: preflightSnapshot.blockers,
+      ...reportDetails,
+    },
+  };
+}
+
+export function blocked(reason: string, details: Record<string, unknown>, preflight: Record<string, unknown>) {
+  preflight.blockers = [...((preflight.blockers as string[] | undefined) ?? []), reason];
+  return withDeleteReport({ ok: false, status: "blocked", reason, ...details }, preflight, { action: "blocked" });
+}
+
+export function errorMessage(error: unknown) {
+  if (typeof error === "object" && error !== null) {
+    const details = error as Record<string, unknown>;
+    if (typeof details.gitStderr === "string" && details.gitStderr.length > 0) return details.gitStderr;
+    if (typeof details.message === "string" && details.message.length > 0) return details.message;
+  }
+  return String(error);
+}
+
+export function createConfirmToken(preflight: Record<string, unknown>) {
+  const material = {
+    repoRoot: preflight.repoRoot,
+    targetKind: preflight.targetKind ?? "worktree",
+    targetPath: preflight.targetPath,
+    worktreeListed: preflight.worktreeListed !== false,
+    branch: preflight.branch ?? "<detached>",
+    head: preflight.head,
+    sessionId: preflight.sessionId ?? null,
+    sessionStatus: preflight.sessionStatus ?? "unrecorded",
+    deleteBranch: preflight.deleteBranch === true,
+    abandonUnmerged: preflight.abandonUnmerged === true,
+    allowIgnoredFiles: preflight.allowIgnoredFiles === true,
+    ignoredFiles: preflight.ignoredFiles ?? [],
+    ignoredFileFingerprint: preflight.ignoredFileFingerprint ?? [],
+    ancestryRef: preflight.ancestryRef ?? null,
+    ancestryProven: preflight.ancestryProven === true,
+    unmergedCommits: preflight.unmergedCommits ?? [],
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}

package/src/delete-worktree-targets.ts

@@ -0,0 +1,152 @@
+import path from "node:path";
+import { getBranchCommit, listRefs } from "./git.ts";
+import { isTerminalSession, isActiveSession } from "./lifecycle.ts";
+import { samePath } from "./filesystem-boundaries.ts";
+import type { GuardianSession, WorktreeEntry } from "./types.ts";
+
+export type TargetResolution = {
+  entry?: WorktreeEntry;
+  session?: GuardianSession;
+  targetKind?: "worktree" | "orphan-branch" | "stale-branch" | "merged-branch";
+  branch?: string;
+  head?: string;
+  ownershipProof?: string;
+  unresolvedReason: string;
+};
+
+function findSessionByWorktree(sessions: GuardianSession[], targetPath: string) {
+  const matchingSessions = sessions.filter((session) => typeof session.worktree_path === "string" && samePath(session.worktree_path, targetPath));
+  return matchingSessions.find(isActiveSession) ?? matchingSessions[0];
+}
+
+function sessionWorktreeEntry(session: GuardianSession | undefined, worktrees: WorktreeEntry[]) {
+  return session?.worktree_path ? worktrees.find((worktree) => samePath(worktree.path, session.worktree_path ?? "")) : undefined;
+}
+
+function sessionBranchCheckedOut(session: GuardianSession | undefined, worktrees: WorktreeEntry[]) {
+  return Boolean(session?.branch && worktrees.some((worktree) => worktree.branch === session.branch));
+}
+
+function safeRefSegment(value: unknown) {
+  return String(value)
+    .replace(/^refs\//, "")
+    .replace(/\.\.+/g, ".")
+    .replace(/[^A-Za-z0-9._/-]+/g, "-")
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\/+/g, "/");
+}
+
+function safetyRefMatchesBranch(refName: string, safeBranch: string) {
+  const prefix = "refs/opencode-guardian/";
+  if (!refName.startsWith(prefix)) return false;
+  const parts = refName.slice(prefix.length).split("/").filter(Boolean);
+  if (parts.length < 3) return false;
+  const branchStart = parts[0] === "preserved" ? 2 : 1;
+  return parts.slice(branchStart, -1).join("/") === safeBranch;
+}
+
+function branchFromInput(input: Record<string, unknown>) {
+  return typeof input.branch === "string" && input.branch.length > 0 ? input.branch : undefined;
+}
+
+function explicitTargets(input: Record<string, unknown>) {
+  return ["sessionId", "targetPath", "branch"].filter((key) => typeof input[key] === "string" && String(input[key]).length > 0);
+}
+
+function conflictingExplicitTarget(input: Record<string, unknown>, sessions: GuardianSession[]) {
+  const branch = branchFromInput(input);
+  if (!branch) return undefined;
+  if (typeof input.sessionId === "string" && input.sessionId.length > 0) {
+    const session = sessions.find((candidate) => candidate.session_id === input.sessionId);
+    if (!session) return `sessionId does not match guardian state for branch ${branch}`;
+    if (session?.branch && session.branch !== branch) return `sessionId resolves to branch ${session.branch}, not ${branch}`;
+  }
+  if (typeof input.targetPath === "string" && input.targetPath.length > 0) {
+    const resolved = path.resolve(String(input.repoRoot ?? process.cwd()), input.targetPath);
+    const pathSessions = sessions.filter((session) => typeof session.worktree_path === "string" && samePath(session.worktree_path, resolved));
+    if (pathSessions.length === 0) return `targetPath does not match guardian state for branch ${branch}`;
+    if (pathSessions.length > 1) return `targetPath matches multiple guardian sessions for branch ${branch}`;
+    if (pathSessions.length === 1 && pathSessions[0].branch && pathSessions[0].branch !== branch) return `targetPath resolves to branch ${pathSessions[0].branch}, not ${branch}`;
+  }
+  return undefined;
+}
+
+function orphanBranchResolution(session: GuardianSession | undefined, worktrees: WorktreeEntry[], deleteRequestedBranch: boolean, repoRoot: string): TargetResolution | undefined {
+  if (!session) return undefined;
+  if (!deleteRequestedBranch) return undefined;
+  if (!session.branch || !session.worktree_path) return undefined;
+  if (session.status === "deleted") return undefined;
+  const entry = sessionWorktreeEntry(session, worktrees);
+  if (entry && !samePath(entry.path, repoRoot)) return undefined;
+  if (sessionBranchCheckedOut(session, worktrees)) return undefined;
+  return { session, targetKind: "orphan-branch", unresolvedReason: entry ? "recorded session worktree is the primary repo but the branch is not checked out" : "recorded session worktree is not in git worktree list" };
+}
+
+async function staleBranchResolution(input: Record<string, unknown>, worktrees: WorktreeEntry[], sessions: GuardianSession[], repoRoot: string, requestedSession?: GuardianSession): Promise<TargetResolution | undefined> {
+  const branch = branchFromInput(input) ?? (requestedSession && isTerminalSession(requestedSession) ? requestedSession.branch : undefined);
+  if (!branch || input.deleteBranch !== true) return undefined;
+  if (worktrees.some((worktree) => worktree.branch === branch)) return undefined;
+  let head: string;
+  try {
+    head = await getBranchCommit(repoRoot, branch);
+  } catch {
+    return undefined;
+  }
+  const terminalMatches = requestedSession && isTerminalSession(requestedSession) ? [requestedSession] : sessions.filter((session) => session.branch === branch && isTerminalSession(session));
+  if (terminalMatches.length > 1) return { branch, head, targetKind: "stale-branch", unresolvedReason: "branch matches multiple terminal guardian sessions" };
+  if (terminalMatches.length === 1 && terminalMatches[0].head_commit === head) {
+    return { session: terminalMatches[0], branch, head, targetKind: "stale-branch", ownershipProof: "terminal-session", unresolvedReason: "branch has no checked-out worktree but terminal guardian state proves ownership" };
+  }
+  const safeBranch = safeRefSegment(branch);
+  const safetyRefs = (await listRefs(repoRoot, "refs/opencode-guardian")) as Array<{ name?: string; commit?: string }>;
+  const matchingRefs = safetyRefs.filter((ref) => ref.commit === head && typeof ref.name === "string" && safetyRefMatchesBranch(ref.name, safeBranch));
+  if (matchingRefs.length > 0) return { branch, head, targetKind: "stale-branch", ownershipProof: "safety-ref", unresolvedReason: "branch has no checked-out worktree but guardian safety refs prove ownership" };
+  return undefined;
+}
+
+async function mergedBranchResolution(input: Record<string, unknown>, worktrees: WorktreeEntry[], repoRoot: string): Promise<TargetResolution | undefined> {
+  const branch = branchFromInput(input);
+  if (!branch || input.deleteBranch !== true) return undefined;
+  if (branch.startsWith("guardian/")) return undefined;
+  if (worktrees.some((worktree) => worktree.branch === branch)) return undefined;
+  try {
+    const head = await getBranchCommit(repoRoot, branch);
+    return { branch, head, targetKind: "merged-branch", unresolvedReason: "local branch is not checked out in any worktree and can be deleted if ancestry is proven" };
+  } catch {
+    return undefined;
+  }
+}
+
+export async function findTarget(input: Record<string, unknown>, worktrees: WorktreeEntry[], sessions: GuardianSession[]): Promise<TargetResolution> {
+  const targets = explicitTargets(input);
+  if (targets.length > 1) return { unresolvedReason: `target inputs conflict: provide exactly one of targetPath, sessionId, or branch; received ${targets.join(", ")}` };
+  const conflict = conflictingExplicitTarget(input, sessions);
+  if (conflict) return { unresolvedReason: `target inputs conflict: ${conflict}` };
+  const deleteRequestedBranch = input.deleteBranch === true;
+  const repoRoot = String(input.repoRoot ?? process.cwd());
+  if (typeof input.sessionId === "string" && input.sessionId.length > 0) {
+    const session = sessions.find((candidate) => candidate.session_id === input.sessionId);
+    const staleBranch = await staleBranchResolution(input, worktrees, sessions, repoRoot, session);
+    if (staleBranch) return staleBranch;
+    const entry = sessionWorktreeEntry(session, worktrees);
+    return orphanBranchResolution(session, worktrees, deleteRequestedBranch, repoRoot) ?? (entry ? { entry, session, targetKind: "worktree", unresolvedReason: "" } : { session, unresolvedReason: session ? "recorded session worktree is not in git worktree list" : "sessionId does not match guardian state" });
+  }
+  if (typeof input.targetPath === "string" && input.targetPath.length > 0) {
+    const resolved = path.resolve(repoRoot, input.targetPath);
+    const entry = worktrees.find((worktree) => samePath(worktree.path, resolved));
+    if (entry) return { entry, session: findSessionByWorktree(sessions, entry.path), targetKind: "worktree", unresolvedReason: "" };
+    const matches = sessions.filter((session) => typeof session.worktree_path === "string" && samePath(session.worktree_path, resolved));
+    return matches.length === 1 ? orphanBranchResolution(matches[0], worktrees, deleteRequestedBranch, repoRoot) ?? { session: matches[0], unresolvedReason: "targetPath is not in git worktree list" } : { unresolvedReason: matches.length > 1 ? "targetPath matches multiple guardian sessions" : "targetPath is not in git worktree list" };
+  }
+  if (typeof input.branch === "string" && input.branch.length > 0) {
+    const staleBranch = await staleBranchResolution(input, worktrees, sessions, repoRoot);
+    if (staleBranch) return staleBranch;
+    const mergedBranch = await mergedBranchResolution(input, worktrees, repoRoot);
+    if (mergedBranch) return mergedBranch;
+    const matches = worktrees.filter((worktree) => worktree.branch === input.branch);
+    if (matches.length === 1) return { entry: matches[0], session: findSessionByWorktree(sessions, matches[0].path), targetKind: "worktree", unresolvedReason: "" };
+    const sessionMatches = sessions.filter((session) => session.branch === input.branch && session.status !== "deleted");
+    return sessionMatches.length === 1 ? orphanBranchResolution(sessionMatches[0], worktrees, deleteRequestedBranch, repoRoot) ?? { session: sessionMatches[0], unresolvedReason: "branch is not checked out in git worktree list" } : { unresolvedReason: matches.length > 1 ? "branch matches multiple worktrees" : sessionMatches.length > 1 ? "branch matches multiple guardian sessions" : "branch is not checked out in git worktree list" };
+  }
+  return { entry: undefined, session: undefined, unresolvedReason: "one of targetPath, sessionId, or branch is required" };
+}