opencode-worktree-guardian 0.1.0

package/src/state.ts

@@ -0,0 +1,197 @@
+import fs from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import path from "node:path";
+import { getCommonGitDir } from "./git.ts";
+import { clearTerminalLifecycleFields } from "./lifecycle.ts";
+import type { GuardianConfig, GuardianPaths, GuardianSession, GuardianState, GuardianStateRecord, RecordLike } from "./types.ts";
+import { errorCode, isRecordLike } from "./types.ts";
+
+export const STATE_SCHEMA_VERSION = "1.0.0";
+
+export type StateErrorKind = "invalid_shape" | "unsupported_schema" | "symlink" | "lock_timeout";
+export type StateBoundaryError = Error & { readonly stateErrorKind: StateErrorKind; readonly guardianPath?: string };
+type GuardianConfigInput = GuardianConfig | RecordLike;
+
+function stateError(kind: StateErrorKind, message: string, guardianPath?: string): StateBoundaryError {
+  return Object.assign(new Error(message), {
+    stateErrorKind: kind,
+    ...(guardianPath === undefined ? {} : { guardianPath }),
+  });
+}
+
+export async function getGuardianPaths(repoRoot: string): Promise<GuardianPaths> {
+  const gitDir = await getCommonGitDir(repoRoot);
+  const dir = path.join(gitDir, "opencode-guardian");
+  return {
+    dir,
+    statePath: path.join(dir, "state.json"),
+    eventsPath: path.join(dir, "events.jsonl"),
+    reportPath: path.join(dir, "report.html"),
+    lockPath: path.join(dir, "state.lock"),
+  };
+}
+
+export function createEmptyState({ repoRoot, config }: { readonly repoRoot: string; readonly config: GuardianConfigInput }): GuardianState {
+  return {
+    schema_version: STATE_SCHEMA_VERSION,
+    state_version: 0,
+    repo_root: repoRoot,
+    base_branch: typeof config.baseBranch === "string" ? config.baseBranch : "",
+    remote: typeof config.remote === "string" ? config.remote : "",
+    finish_mode: typeof config.finishMode === "string" ? config.finishMode : "",
+    worktree_root: typeof config.worktreeRoot === "string" ? config.worktreeRoot : "",
+    sessions: {},
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+}
+
+async function assertNotSymlink(filePath: string, label: string) {
+  try {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) throw stateError("symlink", `Refusing guardian ${label} symlink: ${filePath}`, filePath);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+function validateStateShape(state: unknown): GuardianStateRecord {
+  if (!state || typeof state !== "object" || Array.isArray(state)) throw stateError("invalid_shape", "Invalid guardian state: expected object");
+  if (!isRecordLike(state)) throw stateError("invalid_shape", "Invalid guardian state: expected object");
+  if (state.schema_version !== STATE_SCHEMA_VERSION) {
+    throw stateError("unsupported_schema", `Unsupported guardian state schema_version: ${String(state.schema_version)}`);
+  }
+  if (typeof state.state_version !== "number") throw stateError("invalid_shape", "Invalid guardian state: state_version must be a number");
+  if (!state.sessions || typeof state.sessions !== "object" || Array.isArray(state.sessions)) {
+    throw stateError("invalid_shape", "Invalid guardian state: sessions must be an object");
+  }
+  const sessions: Record<string, GuardianSession> = {};
+  for (const [sessionId, session] of Object.entries(state.sessions)) {
+    if (isRecordLike(session)) sessions[sessionId] = session;
+  }
+  return {
+    ...state,
+    sessions,
+  };
+}
+
+export async function readState(paths: GuardianPaths, context: { readonly repoRoot: string; readonly config: GuardianConfigInput }): Promise<GuardianStateRecord> {
+  try {
+    await assertNotSymlink(paths.statePath, "state");
+    const raw = await fs.readFile(paths.statePath, "utf8");
+    return validateStateShape(JSON.parse(raw));
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+    return createEmptyState(context);
+  }
+}
+
+async function sleep(ms: number) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function acquireStateLock(paths: GuardianPaths, options: { readonly timeoutMs?: number } = {}) {
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const started = Date.now();
+  await fs.mkdir(paths.dir, { recursive: true });
+
+  while (true) {
+    let handle: FileHandle | undefined;
+    try {
+      await assertNotSymlink(paths.lockPath, "lock");
+      handle = await fs.open(paths.lockPath, "wx");
+      await handle.writeFile(JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }));
+      const acquiredHandle = handle;
+      return async () => {
+        await acquiredHandle.close();
+        await fs.unlink(paths.lockPath).catch((error) => {
+          if (errorCode(error) !== "ENOENT") throw error;
+        });
+      };
+    } catch (error) {
+      if (handle) await handle.close().catch(() => {});
+      if (errorCode(error) !== "EEXIST") throw error;
+      if (Date.now() - started >= timeoutMs) {
+        throw stateError("lock_timeout", `Timed out acquiring guardian state lock at ${paths.lockPath}`, paths.lockPath);
+      }
+      await sleep(25);
+    }
+  }
+}
+
+export async function writeStateAtomic(paths: GuardianPaths, state: GuardianState | GuardianStateRecord) {
+  await fs.mkdir(paths.dir, { recursive: true });
+  await assertNotSymlink(paths.statePath, "state");
+  const tmpPath = `${paths.statePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmpPath, `${JSON.stringify(state, null, 2)}\n`);
+  await fs.rename(tmpPath, paths.statePath);
+}
+
+export async function writeReportAtomic(paths: GuardianPaths, html: string) {
+  await fs.mkdir(paths.dir, { recursive: true });
+  await assertNotSymlink(paths.reportPath, "report");
+  const tmpPath = `${paths.reportPath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmpPath, html);
+  await fs.rename(tmpPath, paths.reportPath);
+}
+
+export async function appendEvent(paths: GuardianPaths, event: RecordLike) {
+  await fs.mkdir(paths.dir, { recursive: true });
+  await assertNotSymlink(paths.eventsPath, "events");
+  await fs.appendFile(paths.eventsPath, `${JSON.stringify({ ...event, at: event.at ?? new Date().toISOString() })}\n`);
+}
+
+export async function updateState(repoRoot: string, config: GuardianConfigInput, updater: (state: GuardianStateRecord) => GuardianStateRecord | Promise<GuardianStateRecord>, options: { readonly paths?: GuardianPaths; readonly event?: RecordLike } = {}) {
+  const paths = options.paths ?? await getGuardianPaths(repoRoot);
+  const release = await acquireStateLock(paths, { timeoutMs: typeof config.lockTimeoutMs === "number" ? config.lockTimeoutMs : 5_000 });
+  try {
+    const previous = await readState(paths, { repoRoot, config });
+    const next = await updater(structuredClone(previous));
+    next.state_version = (previous.state_version ?? 0) + 1;
+    next.updated_at = new Date().toISOString();
+    const event = options.event ? { ...options.event, state_version: next.state_version } : null;
+    if (event) await assertNotSymlink(paths.eventsPath, "events");
+    await writeStateAtomic(paths, next);
+    try {
+      if (event) await appendEvent(paths, event);
+    } catch (error) {
+      await writeStateAtomic(paths, previous);
+      throw error;
+    }
+    return next;
+  } finally {
+    await release();
+  }
+}
+
+export async function recordSession(repoRoot: string, config: GuardianConfigInput, session: GuardianSession, options: { readonly paths?: GuardianPaths; readonly event?: RecordLike } = {}) {
+  return updateState(repoRoot, config, (state) => {
+    if (!state.sessions) state.sessions = {};
+    const sessionId = session.session_id;
+    if (!sessionId) throw new Error("session.session_id is required");
+    const previous = isRecordLike(state.sessions[sessionId]) ? state.sessions[sessionId] : undefined;
+    const now = new Date().toISOString();
+    if (session.status === "active" && typeof session.worktree_path === "string") {
+      for (const [candidateSessionId, candidate] of Object.entries(state.sessions)) {
+        if (candidateSessionId !== sessionId && isRecordLike(candidate) && candidate.status === "active" && typeof candidate.worktree_path === "string" && path.resolve(candidate.worktree_path) === path.resolve(session.worktree_path)) {
+          state.sessions[candidateSessionId] = {
+            ...candidate,
+            status: "superseded",
+            superseded_by: sessionId,
+            superseded_at: now,
+            updated_at: now,
+          };
+        }
+      }
+    }
+    state.sessions[sessionId] = clearTerminalLifecycleFields({
+      ...previous,
+      ...session,
+      state_version: (typeof previous?.state_version === "number" ? previous.state_version : 0) + 1,
+      safety_refs: session.safety_refs ?? previous?.safety_refs ?? [],
+      created_at: previous?.created_at ?? now,
+      updated_at: now,
+    });
+    return state;
+  }, { ...options, event: options.event ?? { type: "session_recorded", session_id: session.session_id } });
+}

package/src/tool-registry.ts

@@ -0,0 +1,35 @@
+import { guardianDeletePaths } from "./delete-paths.ts";
+import { guardianDeleteWorktree } from "./delete.ts";
+import { guardianDone } from "./done.ts";
+import { guardianFinish } from "./finish.ts";
+import { guardianHygiene } from "./hygiene.ts";
+import { guardianPreserve } from "./preserve.ts";
+import { guardianRecover, guardianStatus } from "./recover.ts";
+import { guardianReportHtml } from "./report.ts";
+import { guardianStart } from "./start.ts";
+import { guardianUnblockFinish } from "./unblock-finish.ts";
+import { guardianFinishWorkflow } from "./workflow.ts";
+import type { GuardianToolInput, GuardianToolName, GuardianToolResult } from "./types.ts";
+import { isGuardianToolName } from "./types.ts";
+
+type GuardianToolRunner = (input: GuardianToolInput) => Promise<GuardianToolResult>;
+
+export const GUARDIAN_TOOL_RUNNERS = {
+  guardian_delete_paths: guardianDeletePaths,
+  guardian_delete_worktree: guardianDeleteWorktree,
+  guardian_done: guardianDone,
+  guardian_finish: guardianFinish,
+  guardian_finish_workflow: guardianFinishWorkflow,
+  guardian_hygiene: guardianHygiene,
+  guardian_preserve: guardianPreserve,
+  guardian_recover: guardianRecover,
+  guardian_report_html: guardianReportHtml,
+  guardian_start: guardianStart,
+  guardian_status: guardianStatus,
+  guardian_unblock_finish: guardianUnblockFinish,
+} satisfies Record<GuardianToolName, GuardianToolRunner>;
+
+export async function runGuardianTool(name: GuardianToolName | string, input: GuardianToolInput = {}): Promise<GuardianToolResult> {
+  if (isGuardianToolName(name)) return GUARDIAN_TOOL_RUNNERS[name](input);
+  throw new Error(`Unknown guardian tool: ${name}`);
+}

package/src/tools.ts

@@ -0,0 +1,8 @@
+export { buildInvisiblePolicy, injectInvisiblePolicy } from "./plugin/invisible-policy.ts";
+export { rewriteGuardianCommand } from "./plugin/slash-commands.ts";
+export { guardianPreserve } from "./preserve.ts";
+export { guardianStart } from "./start.ts";
+export type { GuardianStartResult } from "./start.ts";
+export { recordLastSafeState } from "./session/last-safe-state.ts";
+export { collectKnownWorktreePaths, resolveSessionWorktree } from "./session/worktree-binding.ts";
+export { runGuardianTool } from "./tool-registry.ts";

package/src/tui.ts

@@ -0,0 +1,113 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+
+const COMMANDS = [
+  {
+    name: "guardian-done",
+    title: "Guardian: Done",
+    description: "Plan or apply the safest implementation-done path for the current repository state.",
+    prompt: "Use the guardian_done native tool. Run mode=plan first. If it selects dirty primary-main publishing, require an explicit commitMessage and explicit user confirmation, then apply with confirm=true so the plugin can reuse the matching internal plan token. After publish, inspect the returned cleanupPlan and do not silently apply cleanup. Never force-push, mutate stashes, delete remote branches, or run raw cleanup commands.",
+  },
+  {
+    name: "guardian-status",
+    title: "Guardian: Status",
+    description: "Show Guardian session, worktree, branch, stash, and recovery inventory.",
+    prompt: "Use the guardian_status native tool to inspect the current repository. Treat the result as read-only evidence.",
+  },
+  {
+    name: "guardian-start",
+    title: "Guardian: Start",
+    description: "Create or attach this session to a Guardian-owned worktree.",
+    prompt: "Use the guardian_start native tool to create or attach this session to a Guardian-owned worktree. Do not use raw git worktree add.",
+  },
+  {
+    name: "guardian-finish",
+    title: "Guardian: Finish",
+    description: "Finish Guardian-owned work through the configured gated finish mode.",
+    prompt: "Use the guardian_finish native tool for gated completion. Do not manually push, merge, clean, or remove worktrees. If dirty files block finish, distinguish allowedDirtyFiles from blockingDirtyFiles; narrow file-specific runtime paths can be allowed through repo config allowDirtyPaths, and allowed runtime dirt is left untouched.",
+  },
+  {
+    name: "guardian-finish-workflow",
+    title: "Guardian: Finish Workflow",
+    description: "Plan or apply implementation-done cleanup for redundant merged worktrees and branches.",
+    prompt: "Use the guardian_finish_workflow native tool. Run mode=plan first, inspect clean/synced preflight facts, cleanup candidates, blockers, and confirmToken, then apply only after explicit user confirmation with the fresh token. This workflow may remove only redundant merged Guardian worktrees and merged local branches through Guardian gates; it must not invent commits, merge protected branches, mutate stashes, run raw cleanup commands, or bypass guardian_finish/guardian_delete_worktree safety checks.",
+  },
+  {
+    name: "guardian-preserve",
+    title: "Guardian: Preserve",
+    description: "Mark Guardian-owned work as terminal/preserved with a safety ref.",
+    prompt: "Use the guardian_preserve native tool to mark the current Guardian-owned session as terminal/preserved with a safety ref. Preserved worktrees are cleanup-eligible; do not treat preservation as a reason to retain disk state forever.",
+  },
+  {
+    name: "guardian-recover",
+    title: "Guardian: Recover",
+    description: "Inspect Guardian recovery refs, orphaned sessions, stashes, and evidence.",
+    prompt: "Use the guardian_recover native tool for read-only recovery evidence. Do not mutate stashes, refs, worktrees, or files.",
+  },
+  {
+    name: "guardian-report",
+    title: "Guardian: Report",
+    description: "Write a static offline Guardian HTML report.",
+    prompt: "Use the guardian_report_html native tool to write the offline report, then return the report path and summarize the main risks.",
+  },
+  {
+    name: "guardian-hygiene",
+    title: "Guardian: Hygiene",
+    description: "Scan, plan, or apply confirmed cleanup for workspace hygiene findings.",
+    prompt: "Use the guardian_hygiene native tool. With no mode it scans only. For cleanup, run mode=plan first, inspect exact approved targets and blockers, get explicit user confirmation, then apply with confirmDelete=true. Never run raw cleanup commands.",
+  },
+  {
+    name: "guardian-delete-worktree",
+    title: "Guardian: Delete Worktree",
+    description: "Plan or apply safe Guardian-mediated worktree, orphan branch, stale branch, or explicit unmerged abandon deletion.",
+    prompt: "Use the guardian_delete_worktree native tool. Run mode=plan first unless a fresh confirmToken for the exact target/options is provided. 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. Never run raw worktree removal, filesystem deletion, forced branch deletion, hard reset, forced clean, or stash mutation.",
+  },
+  {
+    name: "guardian-delete-paths",
+    title: "Guardian: Delete Paths",
+    description: "Plan or apply exact path deletion for approved files or directories.",
+    prompt: "Use the guardian_delete_paths native tool. 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. Use guardian_delete_worktree for worktree removal.",
+  },
+  {
+    name: "guardian-unblock-finish",
+    title: "Guardian: Unblock Finish",
+    description: "Plan or apply safe Guardian finish blocker resolution.",
+    prompt: "Use the guardian_unblock_finish native tool. Run mode=plan first unless a fresh confirmToken for the exact action is provided. Do not delete files, stash, clean, or commit source changes.",
+  },
+] as const;
+
+async function submitPrompt(api: TuiPluginApi, prompt: string) {
+  const route = api.route.current;
+  let sessionID: string | undefined;
+  if (route.name === "session" && route.params && typeof route.params.sessionID === "string") {
+    sessionID = route.params.sessionID;
+  }
+  if (!sessionID) {
+    api.ui.toast({ variant: "warning", title: "Guardian", message: "Open a session before running Guardian commands." });
+    return;
+  }
+
+  await api.client.session.promptAsync({
+    sessionID,
+    directory: api.state.path.directory,
+    parts: [{ type: "text", text: prompt }],
+  });
+}
+
+export async function tui(api: TuiPluginApi) {
+  api.keymap.registerLayer({
+    commands: COMMANDS.map((command) => ({
+      namespace: "palette",
+      name: command.name,
+      title: command.title,
+      desc: command.description,
+      category: "Guardian",
+      slashName: command.name,
+      run: () => submitPrompt(api, command.prompt),
+    })),
+    bindings: [],
+  });
+}
+
+export const id = "opencode-worktree-guardian";
+
+export default { id, tui };

package/src/types.ts

@@ -0,0 +1,339 @@
+export type RecordLike = Record<string, unknown>;
+
+export type MutableRecord = {
+  [key: string]: unknown;
+};
+
+export type GuardianFinishMode = "preserve-only" | "push-branch" | "create-pr" | "merge-to-base";
+
+export type GuardianConfig = {
+  readonly remote: string;
+  readonly baseBranch: string;
+  readonly worktreeRoot: string;
+  readonly branchPrefix: string;
+  readonly finishMode: GuardianFinishMode;
+  readonly autoStart: boolean;
+  readonly autoFinish: boolean;
+  readonly autoCleanup: boolean;
+  readonly safetyRefRetentionDays: number;
+  readonly allowStashIfUnrelated: boolean;
+  readonly allowDirtyPaths: readonly string[];
+  readonly protectedBranches: readonly string[];
+  readonly lockTimeoutMs: number;
+  readonly [key: string]: unknown;
+};
+
+export type ConfigFileSystem = {
+  readonly readFile: (path: string, encoding: "utf8") => Promise<string>;
+};
+
+export type LoadConfigOptions = {
+  readonly fs?: ConfigFileSystem;
+  readonly configPath?: string;
+};
+
+export type LoadedGuardianConfig = {
+  readonly config: GuardianConfig;
+  readonly path: string;
+  readonly loaded: boolean;
+};
+
+export type GuardianPaths = {
+  readonly dir: string;
+  readonly statePath: string;
+  readonly eventsPath: string;
+  readonly reportPath: string;
+  readonly lockPath: string;
+};
+
+export type GuardianSessionStatus =
+  | "active"
+  | "deleted"
+  | "abandoned"
+  | "finished"
+  | "preserved"
+  | "superseded"
+  | string;
+
+export type GuardianSession = {
+  readonly session_id?: string;
+  readonly sessionId?: string;
+  readonly status?: GuardianSessionStatus;
+  readonly branch?: string;
+  readonly worktree_path?: string;
+  readonly worktreePath?: string;
+  readonly base_ref?: string;
+  readonly head_commit?: string;
+  readonly safety_refs?: readonly string[];
+  readonly deleted_worktree_path?: string;
+  readonly deleted_branch?: string | null;
+  readonly abandoned_branch?: string;
+  readonly branch_only_delete?: boolean;
+  readonly superseded_by?: string;
+  readonly superseded_at?: string;
+  readonly created_at?: string;
+  readonly updated_at?: string;
+  readonly state_version?: number;
+  readonly [key: string]: unknown;
+};
+
+export type GuardianState = {
+  schema_version: string;
+  state_version: number;
+  repo_root: string;
+  base_branch: string;
+  remote: string;
+  finish_mode: string;
+  worktree_root: string;
+  sessions: Record<string, GuardianSession>;
+  created_at: string;
+  updated_at: string;
+  [key: string]: unknown;
+};
+
+export type GuardianStateRecord = MutableRecord & {
+  schema_version?: unknown;
+  state_version?: number;
+  sessions: Record<string, GuardianSession>;
+};
+
+export type WorktreeEntry = {
+  readonly path: string;
+  readonly head?: string;
+  readonly branch?: string;
+  readonly detached?: boolean;
+  readonly bare?: boolean;
+  readonly [key: string]: unknown;
+};
+
+export type GuardianToolInput = MutableRecord;
+export type GuardianToolResult = MutableRecord & {
+  ok?: boolean;
+  status?: string | RecordLike;
+  reason?: string;
+  session?: GuardianSession;
+  sessions?: readonly GuardianSession[];
+  activeSessions?: readonly GuardianSession[];
+  terminalSessions?: readonly GuardianSession[];
+  worktrees?: readonly WorktreeEntry[];
+  preflight?: MutableRecord;
+  previous?: MutableRecord & {
+    branch?: string;
+    worktree_path?: string;
+    reason?: string;
+  };
+  report?: MutableRecord;
+  summary?: MutableRecord;
+  confirmToken?: string;
+  repoRoot?: string;
+  safetyRefs?: readonly unknown[];
+};
+
+export type SessionWorktreeResult = {
+  readonly ok: boolean;
+  readonly sessionId?: string | null;
+  readonly expectedWorktree?: string | null;
+  readonly actualWorktree?: string | null;
+  readonly matches?: boolean;
+  readonly source?: string;
+  readonly terminal?: boolean;
+  readonly status?: string;
+  readonly reason?: string;
+  readonly [key: string]: unknown;
+};
+
+export type GuardOptions = {
+  readonly cwd?: string;
+  readonly knownWorktreePaths?: readonly string[];
+  readonly protectedBranches?: readonly string[];
+  readonly branchPrefix?: string | null;
+  readonly guardianBranches?: readonly string[];
+  readonly protectedBranchWorktreePaths?: readonly string[];
+  readonly currentBranch?: string | null;
+  readonly inheritedEnvAssignments?: readonly string[];
+  readonly [key: string]: unknown;
+};
+
+export type GuardCommandPayload = MutableRecord & {
+  args?: MutableRecord & {
+    command?: unknown;
+    cwd?: unknown;
+    workdir?: unknown;
+  };
+  parts?: readonly { readonly type: string; readonly text: string }[];
+  system?: unknown;
+  command?: unknown;
+  code?: unknown;
+  tool?: unknown;
+  callID?: unknown;
+  sessionID?: unknown;
+  sessionId?: unknown;
+};
+
+export type GuardDecision = {
+  readonly blocked: boolean;
+  readonly reason: string | null;
+  readonly command: string;
+  readonly tokens?: readonly string[];
+  readonly segment?: readonly string[];
+};
+
+export type AllowDecision = {
+  readonly allowed: boolean;
+  readonly reason: string | null;
+};
+
+export type HookContext = {
+  readonly directory?: string;
+  readonly worktree?: string;
+  readonly sessionID?: string;
+  readonly sessionId?: string;
+  readonly metadata?: (metadata: { readonly title?: string; readonly metadata?: RecordLike }) => void;
+  readonly [key: string]: unknown;
+};
+
+export type PluginClient = {
+  readonly app?: {
+    readonly log?: (event: { readonly body: RecordLike }) => Promise<void> | void;
+  };
+};
+
+export type PluginServerOptions = {
+  readonly client?: PluginClient;
+  readonly directory?: string;
+  readonly worktree?: string;
+};
+
+export type ToolExecutionPayload = MutableRecord & {
+  args?: MutableRecord;
+  parts?: readonly { readonly type: string; readonly text: string }[];
+  system?: unknown;
+  command?: unknown;
+  tool?: unknown;
+  callID?: unknown;
+  sessionID?: unknown;
+  sessionId?: unknown;
+};
+
+export const GUARDIAN_TOOL_NAMES = [
+  "guardian_delete_paths",
+  "guardian_delete_worktree",
+  "guardian_done",
+  "guardian_finish",
+  "guardian_finish_workflow",
+  "guardian_hygiene",
+  "guardian_preserve",
+  "guardian_recover",
+  "guardian_report_html",
+  "guardian_start",
+  "guardian_status",
+  "guardian_unblock_finish",
+] as const;
+
+export type GuardianToolName = typeof GUARDIAN_TOOL_NAMES[number];
+
+export type GuardianPluginMetadata = {
+  readonly id: string;
+};
+
+export type GuardianNativeToolReturn = {
+  readonly title: GuardianToolName;
+  readonly metadata: GuardianToolResult;
+  readonly output: string;
+};
+
+export type PlanTokenCache = Map<string, string>;
+
+export type PlanCacheToolArgs = MutableRecord & {
+  mode?: unknown;
+  sessionId?: unknown;
+  repoRoot?: unknown;
+  cwd?: unknown;
+  paths?: unknown;
+  cleanupPaths?: unknown;
+  allowCategories?: unknown;
+  allowTracked?: unknown;
+  allowRecursive?: unknown;
+  allowDirtyNestedGit?: unknown;
+  commitMessage?: unknown;
+  finishMode?: unknown;
+  deleteBranch?: unknown;
+  abandonUnmerged?: unknown;
+  allowIgnoredFiles?: unknown;
+  action?: unknown;
+  confirm?: unknown;
+  confirmDelete?: unknown;
+  confirmToken?: unknown;
+  branch?: unknown;
+  targetPath?: unknown;
+  worktreePath?: unknown;
+};
+
+export function isRecordLike(value: unknown): value is RecordLike {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isMutableRecord(value: unknown): value is MutableRecord {
+  return isRecordLike(value);
+}
+
+export function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+export function isGuardianToolName(value: string): value is GuardianToolName {
+  return GUARDIAN_TOOL_NAMES.some((toolName) => toolName === value);
+}
+
+export function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function errorCode(error: unknown): string | undefined {
+  return isRecordLike(error) && typeof error.code === "string" ? error.code : undefined;
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export type GitCommandOutput = { readonly stdout: string; readonly stderr: string };
+
+export type GitCommandMetadata = {
+  readonly gitArgs: readonly string[];
+  readonly gitStdout: string;
+  readonly gitStderr: string;
+  readonly gitExitCode?: number;
+  readonly gitSignal?: string;
+};
+
+export type GitCommandFailure = Error & GitCommandMetadata;
+
+function textFromOutput(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (Buffer.isBuffer(value)) return value.toString("utf8").trim();
+  return "";
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export function gitMetadataFromError(args: readonly string[], error: unknown, fallback: GitCommandOutput = { stdout: "", stderr: "" }): GitCommandMetadata {
+  if (!isRecordLike(error)) {
+    return { gitArgs: [...args], gitStdout: fallback.stdout, gitStderr: fallback.stderr };
+  }
+  const code = typeof error.code === "number" ? error.code : undefined;
+  const signal = typeof error.signal === "string" ? error.signal : undefined;
+  return {
+    gitArgs: [...args],
+    gitStdout: textFromOutput(error.stdout) || fallback.stdout,
+    gitStderr: textFromOutput(error.stderr) || fallback.stderr,
+    ...(code === undefined ? {} : { gitExitCode: code }),
+    ...(signal === undefined ? {} : { gitSignal: signal }),
+  };
+}
+
+export function withGitMetadata(error: unknown, metadata: GitCommandMetadata): GitCommandFailure {
+  return Object.assign(toError(error), metadata);
+}