opencode-worktree-guardian 0.1.0

package/src/plugin/server.ts

@@ -0,0 +1,257 @@
+import fs from "node:fs/promises";
+import { loadConfig } from "../config.ts";
+import { getCurrentBranch } from "../git.ts";
+import { classifyGuardCommand, classifyNormalAgentGitCommand, classifyReadOnlyInspectionCommand, extractCommandText } from "../guards.ts";
+import { guardianStart } from "../start.ts";
+import { collectKnownWorktreePaths, resolveSessionWorktree } from "../session/worktree-binding.ts";
+import { recordLastSafeState } from "../session/last-safe-state.ts";
+import { runGuardianTool } from "../tool-registry.ts";
+import type { GuardCommandPayload, GuardianConfig, GuardianToolInput, GuardianToolResult, HookContext, PlanTokenCache, PluginServerOptions, RecordLike, SessionWorktreeResult } from "../types.ts";
+import { errorMessage, isRecordLike } from "../types.ts";
+import { routeDirectFileMutation, directFileMutationPathArg } from "./direct-file-routing.ts";
+import { writeLog, createEvent } from "./event-log.ts";
+import { collectGuardContext } from "./guard-context.ts";
+import { getExecutionCwd, getIdleEventSessionId, getSessionId, getStringSessionId } from "./hook-context.ts";
+import { injectInvisiblePolicy } from "./invisible-policy.ts";
+import { guardianTool } from "./native-tool.ts";
+import { rewriteGuardianCommand } from "./slash-commands.ts";
+import { canFallbackToNormalGit, getActualWorktree, pathExists, rememberSessionWorktree, resolveActualWorktreeOrPath, routeRecordedSessionCommand } from "./session-routing.ts";
+
+async function tryInvisibleStart(input: GuardCommandPayload, context: HookContext, config: GuardianConfig) {
+  const sessionId = getSessionId(input);
+  if (!config.autoStart || !sessionId || !context.directory) return null;
+  try {
+    return await guardianStart({
+      repoRoot: context.directory,
+      cwd: context.worktree ?? context.directory,
+      sessionId,
+      taskName: input?.taskName ?? "session",
+      createWorktree: context.worktree == null || context.worktree === context.directory,
+      config,
+    });
+  } catch (error) {
+    return { ok: false, reason: errorMessage(error) };
+  }
+}
+
+function createTools(planCache: PlanTokenCache) {
+  return {
+    guardian_done: guardianTool("guardian_done", "Plan or apply the safest implementation-done path for this repository state.", planCache),
+    guardian_start: guardianTool("guardian_start", "Create or attach this OpenCode session to a guardian-owned worktree.", planCache),
+    guardian_status: guardianTool("guardian_status", "Report guardian state, worktrees, safety refs, stash inventory, and blockers without mutating the repo.", planCache),
+    guardian_delete_paths: guardianTool("guardian_delete_paths", "Plan or apply exact path deletion with confirm-token, fingerprint, tracked-file, recursive, and protected-root gates.", planCache),
+    guardian_delete_worktree: guardianTool("guardian_delete_worktree", "Plan or apply safe Guardian-mediated worktree deletion with confirm-token and safety-ref gates.", planCache),
+    guardian_unblock_finish: guardianTool("guardian_unblock_finish", "Plan or apply safe finish blocker resolution, such as committing review artifacts with confirm-token gates.", planCache),
+    guardian_finish_workflow: guardianTool("guardian_finish_workflow", "Plan or apply an implementation-done workflow that verifies clean state and removes redundant merged worktrees and branches through Guardian gates.", planCache),
+    guardian_finish: guardianTool("guardian_finish", "Apply the configured gated finish mode for the current guardian-owned worktree.", planCache),
+    guardian_preserve: guardianTool("guardian_preserve", "Mark the current guardian-owned session as terminal/preserved with a safety ref.", planCache),
+    guardian_recover: guardianTool("guardian_recover", "List recovery refs, orphaned sessions, stash inventory, and suggested recovery commands without mutation.", planCache),
+    guardian_report_html: guardianTool("guardian_report_html", "Write a static offline HTML report for guardian sessions, worktrees, branches, risks, and recovery commands.", planCache),
+    guardian_hygiene: guardianTool("guardian_hygiene", "Scan, plan, or apply token-gated cleanup for workspace hygiene findings.", planCache),
+  };
+}
+
+async function resolveHookSessionWorktree(input: GuardCommandPayload, output: GuardCommandPayload, context: HookContext, pluginDirectory: string | undefined, sessionWorktreeCache: Map<string, string>) {
+  const command = extractCommandText(input, output);
+  const directFileMutation = directFileMutationPathArg(input, output);
+  const executionCwd = getExecutionCwd(input, output, context);
+  let sessionWorktree: SessionWorktreeResult | null = null;
+  try {
+    const canResolveSession = Boolean(command || directFileMutation) && pluginDirectory !== undefined && await pathExists(pluginDirectory);
+    const actualWorktree = canResolveSession ? await resolveActualWorktreeOrPath(executionCwd) : executionCwd;
+    sessionWorktree = canResolveSession ? await resolveSessionWorktree({
+      repoRoot: context.directory,
+      cwd: executionCwd,
+      actualWorktree,
+      sessionId: getStringSessionId(input),
+      cache: sessionWorktreeCache,
+      validateBinding: true,
+    }) : { ok: true, sessionId: getStringSessionId(input), expectedWorktree: null, actualWorktree: executionCwd, matches: true, source: "unavailable" };
+  } catch (error) {
+    sessionWorktree = { ok: false, reason: errorMessage(error), sessionId: getStringSessionId(input), expectedWorktree: null, actualWorktree: executionCwd };
+  }
+  return { command, executionCwd, sessionWorktree };
+}
+
+const WorktreeGuardianPlugin = {
+  id: "opencode-worktree-guardian",
+  async server({ client, directory, worktree }: PluginServerOptions = {}) {
+    const context = { directory, worktree };
+    const pluginDirectory = typeof directory === "string" ? directory : undefined;
+    const activeToolCalls = new Set<unknown>();
+    const autoFinishedSessions = new Set<unknown>();
+    const sessionWorktreeCache = new Map<string, string>();
+    const planCache: PlanTokenCache = new Map();
+
+    return {
+      tool: createTools(planCache),
+
+      async "experimental.chat.system.transform"(input: GuardCommandPayload, output: GuardianToolInput) {
+        let invisibleStart: GuardianToolResult | null = null;
+        try {
+          const directoryExists = pluginDirectory ? await fs.access(pluginDirectory).then(() => true, () => false) : false;
+          const { config } = directoryExists && pluginDirectory ? await loadConfig(pluginDirectory) : { config: null };
+          if (config) {
+            injectInvisiblePolicy(output, config);
+            invisibleStart = await tryInvisibleStart(input, context, config);
+            rememberSessionWorktree(sessionWorktreeCache, getSessionId(input), invisibleStart);
+          }
+        } catch (error) {
+          invisibleStart = { ok: false, reason: errorMessage(error) };
+        }
+        await writeLog(client, createEvent("chat.system.transform", input, output, context, { invisibleStart }));
+      },
+
+      async "tool.execute.before"(input: GuardCommandPayload, output: GuardCommandPayload) {
+        if (input.callID) activeToolCalls.add(input.callID);
+        const { command, executionCwd, sessionWorktree: initialSessionWorktree } = await resolveHookSessionWorktree(input, output, context, pluginDirectory, sessionWorktreeCache);
+        let sessionWorktree = initialSessionWorktree;
+        let effectiveCwd = executionCwd;
+        let knownWorktreePaths = typeof worktree === "string" ? [worktree] : [];
+        try {
+          knownWorktreePaths = await collectKnownWorktreePaths({ cwd: effectiveCwd, repoRoot: directory, currentWorktree: worktree });
+        } catch {}
+        const guardContext = await collectGuardContext({ pluginDirectory, effectiveCwd });
+        let guard = classifyGuardCommand(command, {
+          cwd: effectiveCwd,
+          repoRoot: directory,
+          knownWorktreePaths,
+          protectedBranches: guardContext.guardConfig?.protectedBranches,
+          branchPrefix: guardContext.guardConfig?.branchPrefix,
+          guardianBranches: guardContext.guardianBranches,
+          protectedBranchWorktreePaths: guardContext.protectedBranchWorktreePaths,
+          currentBranch: guardContext.currentBranch,
+        });
+        const readOnly = sessionWorktree?.ok === false ? classifyReadOnlyInspectionCommand(command) : { allowed: true, reason: null };
+        const normalAgentGit = sessionWorktree?.ok === false ? classifyNormalAgentGitCommand(command, {
+          cwd: effectiveCwd,
+          protectedBranches: guardContext.guardConfig?.protectedBranches,
+          branchPrefix: guardContext.guardConfig?.branchPrefix,
+          guardianBranches: guardContext.guardianBranches,
+          protectedBranchWorktreePaths: guardContext.protectedBranchWorktreePaths,
+          currentBranch: guardContext.currentBranch,
+        }) : { allowed: true, reason: null };
+        let routed = false;
+        const directFileRoute = await routeDirectFileMutation(input, output, sessionWorktree, directory, sessionWorktreeCache);
+        if (directFileRoute.blocked) {
+          if (input.callID) activeToolCalls.delete(input.callID);
+          await writeLog(client, createEvent("tool.execute.before", input, output, context, { guard, sessionWorktree, readOnly, normalAgentGit, routed, directFileRoute }));
+          throw new Error(`Worktree Guardian blocked direct file mutation: ${directFileRoute.reason}. Use guardian_status to inspect the recorded worktree.`);
+        }
+        if (directFileRoute.routed) routed = true;
+        if (guard.blocked) {
+          if (input.callID) activeToolCalls.delete(input.callID);
+          await writeLog(client, createEvent("tool.execute.before", input, output, context, { guard, sessionWorktree, readOnly, normalAgentGit, routed }));
+          throw new Error(`Worktree Guardian blocked command: ${guard.reason}. Use guardian_status or guardian_finish instead.`);
+        }
+        if (command && sessionWorktree?.ok === false && !readOnly.allowed) {
+          try {
+            sessionWorktree = await routeRecordedSessionCommand(input, output, sessionWorktree, directory, sessionWorktreeCache);
+            effectiveCwd = typeof output.args?.workdir === "string" ? output.args.workdir : effectiveCwd;
+            routed = true;
+            knownWorktreePaths = await collectKnownWorktreePaths({ cwd: effectiveCwd, repoRoot: directory, currentWorktree: worktree });
+            const currentBranch = await getCurrentBranch(effectiveCwd).catch(() => null);
+            guard = classifyGuardCommand(command, {
+              cwd: effectiveCwd,
+              repoRoot: directory,
+              knownWorktreePaths,
+              protectedBranches: guardContext.guardConfig?.protectedBranches,
+              branchPrefix: guardContext.guardConfig?.branchPrefix,
+              guardianBranches: guardContext.guardianBranches,
+              protectedBranchWorktreePaths: guardContext.protectedBranchWorktreePaths,
+              currentBranch,
+            });
+          } catch (error) {
+            await writeLog(client, createEvent("tool.execute.before", input, output, context, { guard, sessionWorktree, readOnly, normalAgentGit, routed, routeError: errorMessage(error) }));
+            if (!canFallbackToNormalGit(error, normalAgentGit)) {
+              if (input.callID) activeToolCalls.delete(input.callID);
+              throw new Error(`Worktree Guardian blocked command: ${errorMessage(error)}. Use guardian_status to inspect the recorded worktree.`);
+            }
+          }
+        }
+        await writeLog(client, createEvent("tool.execute.before", input, output, context, { guard, sessionWorktree, readOnly, normalAgentGit, routed }));
+        if (command && sessionWorktree?.ok === false && !normalAgentGit.allowed && (sessionWorktree.reason || !readOnly.allowed)) {
+          if (input.callID) activeToolCalls.delete(input.callID);
+          throw new Error(`Worktree Guardian blocked command: session ${sessionWorktree.sessionId} is recorded for expected worktree ${sessionWorktree.expectedWorktree ?? "an unknown worktree"} but actual cwd is ${executionCwd} and actual worktree is ${sessionWorktree.actualWorktree}. Use guardian_status to inspect the recorded worktree.`);
+        }
+        if (guard.blocked) {
+          if (input.callID) activeToolCalls.delete(input.callID);
+          throw new Error(`Worktree Guardian blocked command: ${guard.reason}. Use guardian_status or guardian_finish instead.`);
+        }
+      },
+
+      async "tool.execute.after"(input: GuardCommandPayload, output: GuardCommandPayload) {
+        if (input.callID) activeToolCalls.delete(input.callID);
+        let lastSafeState: GuardianToolResult | null = null;
+        try {
+          const executionCwd = getExecutionCwd(input, output, context);
+          const canResolveSession = await pathExists(directory);
+          const actualWorktree = canResolveSession ? await getActualWorktree(executionCwd) : executionCwd;
+          const sessionWorktree = canResolveSession ? await resolveSessionWorktree({
+            repoRoot: directory,
+            cwd: executionCwd,
+            actualWorktree,
+            sessionId: getStringSessionId(input),
+            cache: sessionWorktreeCache,
+          }) : null;
+          if (sessionWorktree?.ok === false) {
+            lastSafeState = { ok: false, reason: "session worktree mismatch", sessionWorktree };
+            await writeLog(client, createEvent("tool.execute.after", input, output, context, { lastSafeState }));
+            return;
+          }
+          lastSafeState = await recordLastSafeState({ cwd: executionCwd, repoRoot: directory, sessionId: getStringSessionId(input), tool: input.tool });
+        } catch (error) {
+          lastSafeState = { ok: false, reason: errorMessage(error) };
+        }
+        await writeLog(client, createEvent("tool.execute.after", input, output, context, { lastSafeState }));
+      },
+
+      async "command.execute.before"(input: GuardCommandPayload, output: GuardCommandPayload) {
+        const rewritten = rewriteGuardianCommand(input, output);
+        await writeLog(client, createEvent("command.execute.before", input, output, context, { rewritten }));
+      },
+
+      async event(input: RecordLike) {
+        const event = isRecordLike(input.event) ? input.event : null;
+        let autoFinish: GuardianToolResult | null = null;
+        if (event?.type === "session.idle") {
+          const sessionId = getIdleEventSessionId(input);
+          if (sessionId && !autoFinishedSessions.has(sessionId) && activeToolCalls.size === 0 && directory) {
+            try {
+              const { config } = await loadConfig(directory);
+              if (config.autoFinish === true) {
+                const executionCwd = worktree ?? directory;
+                const recordedSessionWorktree = await resolveSessionWorktree({ repoRoot: directory, cwd: executionCwd, actualWorktree: executionCwd, sessionId, cache: sessionWorktreeCache, config });
+                const validationCwd = recordedSessionWorktree.expectedWorktree ?? executionCwd;
+                const validationWorktree = await resolveActualWorktreeOrPath(validationCwd);
+                const sessionWorktree = await resolveSessionWorktree({ repoRoot: directory, cwd: validationCwd, actualWorktree: validationWorktree, sessionId, cache: sessionWorktreeCache, config, validateBinding: true });
+                if (sessionWorktree?.ok !== true) {
+                  autoFinish = {
+                    ok: false,
+                    status: "blocked",
+                    reason: `recorded session cannot be auto-finished: ${sessionWorktree?.reason ?? "session worktree binding is invalid"}; rerun guardian_start with createWorktree=true`,
+                    sessionWorktree,
+                    suggestedCommand: "guardian_start createWorktree=true",
+                  };
+                } else {
+                  autoFinish = await runGuardianTool("guardian_finish", {
+                    repoRoot: directory,
+                    cwd: sessionWorktree.expectedWorktree ?? executionCwd,
+                    sessionId,
+                    finishMode: config.finishMode,
+                  });
+                }
+                if (autoFinish?.ok === true) autoFinishedSessions.add(sessionId);
+              }
+            } catch (error) {
+              autoFinish = { ok: false, reason: errorMessage(error) };
+            }
+          }
+        }
+        if (autoFinish) await writeLog(client, createEvent("event", input, {}, context, { autoFinish }));
+      },
+    };
+  },
+};
+
+export default WorktreeGuardianPlugin;

package/src/plugin/session-routing.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import { getRepoRoot } from "../git.ts";
+import { resolveSessionWorktree } from "../session/worktree-binding.ts";
+import type { AllowDecision, GuardCommandPayload, GuardianToolResult, SessionWorktreeResult } from "../types.ts";
+import { errorMessage, isMutableRecord, isRecordLike } from "../types.ts";
+import { getSessionId } from "./hook-context.ts";
+
+export function rememberSessionWorktree(cache: Map<string, string>, sessionId: unknown, result: GuardianToolResult | null) {
+  const session = isRecordLike(result?.session) ? result.session : null;
+  const worktreePath = session?.worktree_path;
+  if (typeof sessionId === "string" && sessionId.length > 0 && result?.ok === true && typeof worktreePath === "string") cache.set(sessionId, worktreePath);
+}
+
+export async function pathExists(candidate: string | undefined) {
+  if (!candidate) return false;
+  return fs.access(candidate).then(() => true, () => false);
+}
+
+export async function getActualWorktree(executionCwd: string) {
+  return await getRepoRoot(executionCwd);
+}
+
+export async function resolveActualWorktreeOrPath(executionCwd: string) {
+  try {
+    return await getActualWorktree(executionCwd);
+  } catch {
+    return executionCwd;
+  }
+}
+
+export async function validateRecordedSessionTarget(input: GuardCommandPayload, sessionWorktree: SessionWorktreeResult, repoRoot: string | undefined, cache: Map<string, string>) {
+  const expectedWorktree = sessionWorktree.expectedWorktree;
+  if (typeof expectedWorktree !== "string" || expectedWorktree.length === 0) {
+    throw new Error(`recorded worktree is unavailable for session ${sessionWorktree.sessionId}`);
+  }
+  if (!await pathExists(expectedWorktree)) {
+    throw new Error(`recorded worktree is missing for session ${sessionWorktree.sessionId}: ${expectedWorktree}`);
+  }
+  const actualWorktree = await getActualWorktree(expectedWorktree);
+  const routed = await resolveSessionWorktree({
+    repoRoot,
+    cwd: expectedWorktree,
+    actualWorktree,
+    sessionId: getSessionId(input),
+    cache,
+    validateBinding: true,
+  });
+  if (routed?.ok !== true) {
+    const reason = routed?.reason ? `${routed.reason}: ` : "";
+    throw new Error(`recorded worktree cannot be used for session ${sessionWorktree.sessionId}: ${reason}expected ${routed?.expectedWorktree ?? expectedWorktree}, actual ${routed?.actualWorktree ?? actualWorktree}`);
+  }
+  return { ...routed, actualWorktree };
+}
+
+export async function routeRecordedSessionCommand(input: GuardCommandPayload, output: GuardCommandPayload, sessionWorktree: SessionWorktreeResult, repoRoot: string | undefined, cache: Map<string, string>) {
+  const routed = await validateRecordedSessionTarget(input, sessionWorktree, repoRoot, cache);
+  const expectedWorktree = routed.expectedWorktree;
+  if (typeof expectedWorktree !== "string") throw new Error(`recorded worktree is unavailable for session ${sessionWorktree.sessionId}`);
+  if (!isMutableRecord(output.args)) output.args = {};
+  const args = output.args;
+  args.workdir = expectedWorktree;
+  args.cwd = expectedWorktree;
+  return {
+    ...routed,
+    routed: true,
+    routedFrom: sessionWorktree.actualWorktree,
+  };
+}
+
+export function canFallbackToNormalGit(error: unknown, normalAgentGit: AllowDecision) {
+  if (normalAgentGit.allowed !== true) return false;
+  const message = error instanceof Error ? error.message : String(error);
+  return /recorded worktree is (missing|unavailable)/.test(message);
+}

package/src/plugin/slash-commands.ts

@@ -0,0 +1,20 @@
+import type { GuardianToolInput } from "../types.ts";
+
+export function rewriteGuardianCommand(input: GuardianToolInput = {}, output: GuardianToolInput = {}) {
+  const command = input?.command;
+  if (typeof command !== "string") return false;
+  const match = command.trim().match(/^\/?guardian\s+(done|status|finish-workflow|finish|preserve|recover|report|start|hygiene|delete-paths|delete-worktree|unblock-finish)(?:\s+(.*))?$/);
+  if (!match) return false;
+  const action = match[1];
+  const rest = match[2] ?? "";
+  if (!action) return false;
+  const toolName = action === "report" ? "guardian_report_html" : action === "delete-worktree" ? "guardian_delete_worktree" : action === "delete-paths" ? "guardian_delete_paths" : action === "unblock-finish" ? "guardian_unblock_finish" : action === "finish-workflow" ? "guardian_finish_workflow" : `guardian_${action}`;
+  const deleteGuidance = action === "delete-worktree" ? " Run mode=plan first. Stale local Guardian branch cleanup requires an exact branch or terminal sessionId plus deleteBranch=true and Guardian ownership proof from terminal state or safety refs. Intentional unmerged local abandonment requires deleteBranch=true plus abandonUnmerged=true in both plan and apply after inspecting unmerged commit evidence." : "";
+  const deletePathsGuidance = action === "delete-paths" ? " Run mode=plan first with exact paths, inspect target status and blockers, get explicit user confirmation, then apply with confirmDelete=true. Tracked source deletion requires allowTracked=true; directory deletion requires allowRecursive=true." : "";
+  const hygieneCleanupGuidance = action === "hygiene" ? " With no mode it scans only. For cleanup, run mode=plan first, inspect exact targets/blockers, get explicit user confirmation, then apply with confirmDelete=true." : "";
+  const doneGuidance = action === "done" ? " Run mode=plan first. Dirty primary-main publishing requires an explicit commitMessage and explicit user confirmation; apply with confirm=true so the plugin reuses the matching internal plan token. Cleanup after publish returns a separate cleanup plan and must not be silently applied." : "";
+  const text = `Use the ${toolName} native tool.${deleteGuidance}${deletePathsGuidance}${hygieneCleanupGuidance}${doneGuidance}${rest.trim() ? ` User arguments: ${rest.trim()}` : ""}`;
+  if (!output || typeof output !== "object") return false;
+  output.parts = [{ type: "text", text }];
+  return true;
+}

package/src/preserve.ts

@@ -0,0 +1,32 @@
+import { buildPreservedRef, createRef, getCurrentBranch, getHeadCommit, getRepoRoot } from "./git.ts";
+import { recordSession } from "./state.ts";
+import type { GuardianToolInput, GuardianToolResult } from "./types.ts";
+import { configFromInput, sessionIdFromInput } from "./session/context.ts";
+import { protectedBranchReason } from "./session/worktree-binding.ts";
+
+export async function guardianPreserve(input: GuardianToolInput = {}): Promise<GuardianToolResult> {
+  const cwd = typeof input.cwd === "string" ? input.cwd : typeof input.repoRoot === "string" ? input.repoRoot : process.cwd();
+  const repoRoot = typeof input.repoRoot === "string" ? input.repoRoot : await getRepoRoot(cwd);
+  const config = await configFromInput(input, repoRoot);
+  const sessionId = sessionIdFromInput(input);
+  if (!sessionId) throw new Error("sessionId is required");
+
+  const worktreePath = await getRepoRoot(cwd);
+  const branch = await getCurrentBranch(worktreePath);
+  if (!branch) throw new Error("Cannot preserve detached HEAD");
+  const unsafeReason = protectedBranchReason(config, branch);
+  if (unsafeReason) return { ok: false, status: "blocked", reason: unsafeReason, branch, worktreePath };
+  const headCommit = await getHeadCommit(worktreePath);
+  const preservedRef = buildPreservedRef(sessionId, branch, typeof input.timestamp === "string" ? input.timestamp : undefined);
+  await createRef(worktreePath, preservedRef, headCommit);
+  const recordedState = await recordSession(repoRoot, config, {
+    session_id: sessionId,
+    status: "preserved",
+    branch,
+    worktree_path: worktreePath,
+    base_ref: `${config.remote}/${config.baseBranch}`,
+    head_commit: headCommit,
+    safety_refs: [preservedRef],
+  }, { event: { type: "guardian_preserve", session_id: sessionId, ref: preservedRef } });
+  return { ok: true, status: "preserved", session: recordedState.sessions[sessionId], preservedRef };
+}

package/src/recover.ts

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { expandWorktreeRoot, loadConfig, normalizeConfig } from "./config.ts";
+import { getCommonGitDir, getDirtyFiles, getRepoRoot, listBranches, listRecoveryCandidates, listRefs, listStashes, listWorktrees } from "./git.ts";
+import type { GitBranchEntry, GitRefEntry, GitStashEntry } from "./git.ts";
+import { scanWorkspaceHygiene } from "./hygiene.ts";
+import { isActiveSession, isTerminalSession } from "./lifecycle.ts";
+import { getGuardianPaths, readState } from "./state.ts";
+import type { GuardianConfig, GuardianSession, GuardianToolInput, GuardianToolResult, WorktreeEntry } from "./types.ts";
+import { errorMessage, isRecordLike } from "./types.ts";
+
+type WorktreeAnnotationMetadata = {
+  readonly guardianRoot: string;
+  readonly commonGitDir?: string;
+  readonly commonGitDirError?: string;
+};
+
+type AnnotatedWorktreeEntry = WorktreeEntry & {
+  readonly category?: "external-temp-worktree" | "external-worktree";
+  readonly severity?: "fail";
+  readonly reason?: string;
+  readonly metadata?: WorktreeAnnotationMetadata;
+};
+
+type PoisonedSession = GuardianSession & {
+  readonly severity: "fail";
+  readonly reason: string;
+  readonly suggestedCommand: string;
+};
+
+type HygieneStatus = Record<string, unknown> & {
+  readonly ok?: unknown;
+  readonly summary?: Record<string, unknown> & { readonly findingCount?: unknown };
+  readonly findings: readonly (Record<string, unknown> & { readonly path?: unknown })[];
+};
+
+type GuardianStatusResult = Omit<GuardianToolResult, "activeSessions" | "terminalSessions" | "worktrees" | "safetyRefs" | "sessions"> & {
+  readonly repoRoot: string;
+  readonly config: GuardianConfig;
+  readonly stateVersion: number | undefined;
+  readonly sessions: readonly GuardianSession[];
+  readonly activeSessions: readonly GuardianSession[];
+  readonly terminalSessions: readonly GuardianSession[];
+  readonly orphanedSessions: readonly GuardianSession[];
+  readonly poisonedSessions: readonly PoisonedSession[];
+  readonly worktrees: readonly WorktreeEntry[];
+  readonly branchesWithoutWorktrees: readonly GitBranchEntry[];
+  readonly worktreesWithoutState: readonly AnnotatedWorktreeEntry[];
+  readonly stateBranchesWithoutWorktrees: readonly string[];
+  readonly safetyRefs: readonly GitRefEntry[];
+  readonly preservedRefs: readonly GitRefEntry[];
+  readonly stashes: readonly GitStashEntry[];
+  readonly dirtyFiles: readonly string[];
+  readonly hygiene: HygieneStatus;
+  readonly suggestedCommands: readonly string[];
+};
+
+type GuardianRecoverResult = GuardianStatusResult & {
+  readonly recoveryCandidates: Awaited<ReturnType<typeof listRecoveryCandidates>>;
+};
+
+async function pathExists(candidate: string) {
+  try {
+    await fs.access(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isInside(candidate: string, parent: string) {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function isTempPath(candidate: string) {
+  const normalized = path.resolve(candidate);
+  return path.basename(normalized).startsWith("opencode-") || normalized.includes(path.sep + "opencode" + path.sep) || normalized.includes(path.sep + "var" + path.sep + "folders" + path.sep) || normalized.startsWith(path.resolve("/private/tmp")) || normalized.startsWith(path.resolve("/tmp"));
+}
+
+async function annotateWorktreeWithoutState(worktree: WorktreeEntry, repoRoot: string, config: GuardianConfig): Promise<AnnotatedWorktreeEntry> {
+  const worktreePath = path.resolve(worktree.path);
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(config.worktreeRoot, repoRoot));
+  if (isInside(worktreePath, guardianRoot)) return worktree;
+
+  let metadata: WorktreeAnnotationMetadata = { guardianRoot };
+  try {
+    metadata = { ...metadata, commonGitDir: await getCommonGitDir(worktreePath) };
+  } catch (error) {
+    metadata = { ...metadata, commonGitDirError: errorMessage(error) };
+  }
+
+  return {
+    ...worktree,
+    category: isTempPath(worktreePath) ? "external-temp-worktree" : "external-worktree",
+    severity: "fail",
+    reason: "linked Git worktree is outside Guardian ownership and outside the configured Guardian worktree root",
+    metadata,
+  };
+}
+
+function poisonedSessionReason(session: GuardianSession, repoRoot: string, config: GuardianConfig) {
+  const reasons: string[] = [];
+  if (typeof session.worktree_path === "string" && path.resolve(session.worktree_path) === path.resolve(repoRoot)) {
+    reasons.push("active session is recorded on the primary repository worktree");
+  }
+  if (typeof session.branch === "string" && Array.isArray(config.protectedBranches) && config.protectedBranches.includes(session.branch)) {
+    reasons.push("active session branch is protected");
+  }
+  return reasons.join("; ");
+}
+
+function annotatePoisonedSession(session: GuardianSession, repoRoot: string, config: GuardianConfig): PoisonedSession | null {
+  const reason = poisonedSessionReason(session, repoRoot, config);
+  if (!reason) return null;
+  return {
+    ...session,
+    severity: "fail",
+    reason,
+    suggestedCommand: "guardian_start createWorktree=true",
+  };
+}
+
+async function configFromInput(input: GuardianToolInput, repoRoot: string): Promise<GuardianConfig> {
+  if (input.config === undefined || input.config === null) return (await loadConfig(repoRoot)).config;
+  if (!isRecordLike(input.config)) throw new Error("config must be an object");
+  return normalizeConfig(input.config);
+}
+
+export async function guardianStatus(input: GuardianToolInput = {}): Promise<GuardianStatusResult> {
+  const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
+  const repoRoot = typeof input.repoRoot === "string" ? input.repoRoot : await getRepoRoot(cwd);
+  const config = await configFromInput(input, repoRoot);
+  const paths = await getGuardianPaths(repoRoot);
+  const state = await readState(paths, { repoRoot, config });
+  const worktrees = await listWorktrees(repoRoot);
+  const worktreePaths = new Set(worktrees.map((entry) => path.resolve(entry.path)));
+  const sessions = Object.values(state.sessions ?? {});
+  const activeSessions = sessions.filter(isActiveSession);
+  const terminalSessions = sessions.filter(isTerminalSession);
+  const sessionWorktreePaths = new Set(activeSessions.map((session) => session.worktree_path).filter((entry): entry is string => typeof entry === "string").map((entry) => path.resolve(entry)));
+  const sessionBranches = new Set(activeSessions.map((session) => session.branch).filter((entry): entry is string => typeof entry === "string"));
+  const orphanedSessions = [];
+  const poisonedSessions = [];
+
+  for (const session of activeSessions) {
+    if (!session.worktree_path || !worktreePaths.has(path.resolve(session.worktree_path)) || !(await pathExists(session.worktree_path))) {
+      orphanedSessions.push(session);
+    }
+    const poisonedSession = annotatePoisonedSession(session, repoRoot, config);
+    if (poisonedSession) poisonedSessions.push(poisonedSession);
+  }
+
+  const branches = await listBranches(repoRoot);
+  const branchesWithoutWorktrees = branches.filter((branch) => !worktrees.some((worktree) => worktree.branch === branch.name));
+  const worktreesWithoutState = await Promise.all(worktrees
+    .filter((worktree) => !sessionWorktreePaths.has(path.resolve(worktree.path)))
+    .map((worktree) => annotateWorktreeWithoutState(worktree, repoRoot, config)));
+  const stateBranchesWithoutWorktrees = [...sessionBranches].filter((branch) => !worktrees.some((worktree) => worktree.branch === branch));
+
+  return {
+    repoRoot,
+    config,
+    stateVersion: state.state_version,
+    sessions,
+    activeSessions,
+    terminalSessions,
+    orphanedSessions,
+    poisonedSessions,
+    worktrees,
+    branchesWithoutWorktrees,
+    worktreesWithoutState,
+    stateBranchesWithoutWorktrees,
+    safetyRefs: await listRefs(repoRoot, "refs/opencode-guardian"),
+    preservedRefs: await listRefs(repoRoot, "refs/opencode-guardian/preserved"),
+    stashes: await listStashes(repoRoot),
+    dirtyFiles: await getDirtyFiles(repoRoot),
+    hygiene: await scanWorkspaceHygiene({ repoRoot, cwd: input.cwd, config }),
+    suggestedCommands: ["guardian_status", "guardian_recover"],
+  };
+}
+
+export async function guardianRecover(input: GuardianToolInput = {}): Promise<GuardianRecoverResult> {
+  const status = await guardianStatus(input);
+  const candidates = await listRecoveryCandidates(status.repoRoot);
+  return {
+    ...status,
+    recoveryCandidates: candidates,
+    suggestedCommands: [
+      ...status.suggestedCommands,
+      ...status.safetyRefs.map((ref) => `git branch recovery/<name> ${ref.commit}`),
+      ...status.stashes.map((stash) => `git stash show -p ${stash.name}`),
+    ],
+  };
+}