opencode-worktree-guardian 0.1.0

package/src/report.ts

@@ -0,0 +1,168 @@
+import { guardianRecover, guardianStatus } from "./recover.ts";
+import { getGuardianPaths, writeReportAtomic } from "./state.ts";
+import type { MutableRecord } from "./types.ts";
+import { isMutableRecord } from "./types.ts";
+
+type LooseRecord = MutableRecord;
+
+const CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src 'none'; script-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+
+function escapeHtml(value: unknown) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+    .replace(/=/g, "&#61;");
+}
+
+function recordValue(value: unknown): LooseRecord {
+  return isMutableRecord(value) ? value : {};
+}
+
+function arrayValue(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function textValue(value: unknown, fallback = "-") {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function numberValue(value: unknown, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function shortCommit(value: unknown) {
+  const text = textValue(value);
+  return text === "-" ? text : text.slice(0, 12);
+}
+
+function metric(label: string, value: number, tone = "") {
+  return `<article class="metric ${tone}"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></article>`;
+}
+
+function emptyRow(columns: number, message: string) {
+  return `<tr><td colspan="${columns}" class="empty">${escapeHtml(message)}</td></tr>`;
+}
+
+function sessionsTable(sessions: unknown[]) {
+  const rows = sessions.map((entry) => {
+    const session = recordValue(entry);
+    return `<tr><td>${escapeHtml(session.session_id ?? session.sessionId)}</td><td>${escapeHtml(session.status)}</td><td>${escapeHtml(session.branch)}</td><td>${escapeHtml(session.worktree_path ?? session.worktreePath)}</td><td>${escapeHtml(shortCommit(session.head_commit ?? session.headCommit))}</td></tr>`;
+  }).join("") || emptyRow(5, "No guardian sessions recorded.");
+  return `<table><thead><tr><th>Session</th><th>Status</th><th>Branch</th><th>Worktree</th><th>Head</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function worktreesTable(worktrees: unknown[]) {
+  const rows = worktrees.map((entry) => {
+    const worktree = recordValue(entry);
+    const markers = [worktree.detached === true ? "detached" : "", worktree.bare === true ? "bare" : ""].filter(Boolean).join(", ");
+    return `<tr><td>${escapeHtml(worktree.branch)}</td><td>${escapeHtml(worktree.path)}</td><td>${escapeHtml(shortCommit(worktree.head ?? worktree.head_commit ?? worktree.headCommit))}</td><td>${escapeHtml(markers || "clean")}</td></tr>`;
+  }).join("") || emptyRow(4, "No git worktrees found.");
+  return `<table><thead><tr><th>Branch</th><th>Path</th><th>Head</th><th>Markers</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function branchesTable(branches: unknown[]) {
+  const rows = branches.map((entry) => {
+    const branch = recordValue(entry);
+    return `<tr><td>${escapeHtml(branch.name ?? entry)}</td><td>${escapeHtml(shortCommit(branch.commit ?? branch.head))}</td></tr>`;
+  }).join("") || emptyRow(2, "Every listed branch has a worktree.");
+  return `<table><thead><tr><th>Branch Without Worktree</th><th>Commit</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function severityRank(value: unknown) {
+  return textValue(value) === "fail" ? 0 : textValue(value) === "warn" ? 1 : 2;
+}
+
+function hygieneCountCard(label: string, value: number, tone = "") {
+  return `<article class="hygiene-count ${tone}"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></article>`;
+}
+
+function hygieneFindingsTable(findings: unknown[]) {
+  const rows = [...findings]
+    .sort((left, right) => {
+      const leftRecord = recordValue(left);
+      const rightRecord = recordValue(right);
+      return severityRank(leftRecord.severity) - severityRank(rightRecord.severity)
+        || textValue(leftRecord.category).localeCompare(textValue(rightRecord.category))
+        || textValue(leftRecord.path).localeCompare(textValue(rightRecord.path));
+    })
+    .slice(0, 12)
+    .map((entry) => {
+      const finding = recordValue(entry);
+      const severity = textValue(finding.severity);
+      const tone = severity === "fail" ? "bad" : severity === "warn" ? "warn" : "";
+      return `<tr><td><span class="status-pill ${tone}">${escapeHtml(severity)}</span></td><td>${escapeHtml(finding.category)}</td><td><code>${escapeHtml(finding.path)}</code></td><td>${escapeHtml(finding.reason)}</td></tr>`;
+    }).join("") || emptyRow(4, "No workspace hygiene findings recorded.");
+  return `<table><thead><tr><th>Severity</th><th>Category</th><th>Path</th><th>Reason</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function hygieneSection(input: unknown) {
+  const hygiene = recordValue(input);
+  const summary = recordValue(hygiene.summary);
+  const bySeverity = recordValue(summary.bySeverity);
+  const byCategory = recordValue(summary.byCategory);
+  const findings = arrayValue(hygiene.findings);
+  const findingCount = numberValue(summary.findingCount, findings.length);
+  const failCount = numberValue(bySeverity.fail);
+  const warnCount = numberValue(bySeverity.warn);
+  const knownCleanableCount = numberValue(byCategory["known-cleanable"]);
+  const nestedGitCount = numberValue(byCategory["nested-git"]);
+  const suspiciousCount = numberValue(byCategory.suspicious);
+  const sectionTone = failCount > 0 ? "risk" : findingCount > 0 ? "warning" : "info";
+  const failureReason = hygiene.ok === false ? `<p class="hygiene-alert">Scan failed: ${escapeHtml(hygiene.reason)}</p>` : "";
+
+  return `<section class="card hygiene ${sectionTone}" aria-labelledby="workspace-hygiene-heading"><h2 id="workspace-hygiene-heading">Workspace Hygiene</h2><p class="section-note">Report-only scan of untracked and ignored workspace artifacts. No cleanup actions are performed here.</p>${failureReason}<div class="hygiene-metrics">${hygieneCountCard("Candidate Paths", numberValue(summary.candidateCount))}${hygieneCountCard("Findings", findingCount, findingCount > 0 ? "warn" : "good")}${hygieneCountCard("Fail", failCount, failCount > 0 ? "bad" : "good")}${hygieneCountCard("Warn", warnCount, warnCount > 0 ? "warn" : "good")}${hygieneCountCard("Known Cleanable", knownCleanableCount, knownCleanableCount > 0 ? "warn" : "good")}${hygieneCountCard("Nested Git", nestedGitCount, nestedGitCount > 0 ? "bad" : "good")}${hygieneCountCard("Suspicious", suspiciousCount, suspiciousCount > 0 ? "warn" : "good")}${hygieneCountCard("Exclusions", numberValue(summary.exclusionCount))}</div><h3>Top Findings By Severity And Category</h3>${hygieneFindingsTable(findings)}</section>`;
+}
+
+function listSection(title: string, entries: unknown[], tone: "risk" | "info") {
+  const items = entries.map((entry) => `<li><code>${escapeHtml(describeEntry(entry))}</code></li>`).join("") || `<li class="empty">${escapeHtml(tone === "risk" ? "No risks detected." : "Nothing to show.")}</li>`;
+  return `<section class="card ${tone}"><h2>${escapeHtml(title)}</h2><ul>${items}</ul></section>`;
+}
+
+function describeEntry(entry: unknown) {
+  const item = recordValue(entry);
+  return textValue(item.session_id ?? item.sessionId ?? item.branch ?? item.path ?? item.worktree_path ?? item.name ?? item.ref ?? item.command ?? entry, JSON.stringify(entry));
+}
+
+function commandSection(commands: unknown[]) {
+  const items = commands.map((command) => `<li><code>${escapeHtml(command)}</code></li>`).join("") || `<li class="empty">No recovery commands suggested.</li>`;
+  return `<section class="card command-bank"><h2>Recovery Commands</h2><p>Read-only suggestions. Review before running anything mutating.</p><ul>${items}</ul></section>`;
+}
+
+function styles() {
+  return `:root{--bg:#080b0d;--panel:#11181c;--panel-2:#172126;--line:#31444c;--text:#e4efe9;--muted:#92a49f;--good:#7ddf9a;--warn:#ffbe5c;--bad:#ff6b5e;--accent:#8fd6ff;--shadow:0 24px 80px rgba(0,0,0,.42);--radius:18px;--space-1:4px;--space-2:8px;--space-3:12px;--space-4:16px;--space-6:24px;--space-8:32px}*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 20% 0%,#17303a 0,#080b0d 34%),linear-gradient(135deg,#080b0d,#121618);color:var(--text);font:15px/1.55 ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace}body:before{content:"";position:fixed;inset:0;pointer-events:none;background:repeating-linear-gradient(0deg,rgba(255,255,255,.025),rgba(255,255,255,.025) 1px,transparent 1px,transparent 6px)}header,main{width:min(1180px,calc(100% - 32px));margin:0 auto}header{padding:var(--space-8) 0 var(--space-6)}.eyebrow{color:var(--accent);letter-spacing:.18em;text-transform:uppercase;font-size:12px}h1{font-size:clamp(32px,6vw,72px);line-height:.9;margin:var(--space-3) 0;font-weight:900;letter-spacing:-.08em}h2{margin:0 0 var(--space-4);font-size:18px;text-transform:uppercase;letter-spacing:.08em}.timestamp{color:var(--muted)}.grid{display:grid;grid-template-columns:repeat(12,1fr);gap:var(--space-4);margin-bottom:var(--space-4)}.card,.metric{background:linear-gradient(180deg,rgba(255,255,255,.045),rgba(255,255,255,.015));border:1px solid var(--line);border-radius:var(--radius);box-shadow:var(--shadow)}.card{grid-column:span 12;padding:var(--space-6);overflow:hidden}.half{grid-column:span 6}.third{grid-column:span 4}.metric{padding:var(--space-4);min-height:96px}.metric span{display:block;color:var(--muted);text-transform:uppercase;font-size:12px;letter-spacing:.1em}.metric strong{display:block;font-size:34px;line-height:1.1}.metric.good strong{color:var(--good)}.metric.warn strong{color:var(--warn)}.metric.bad strong{color:var(--bad)}table{width:100%;border-collapse:collapse;overflow:hidden}th,td{padding:var(--space-3);border-bottom:1px solid rgba(255,255,255,.08);text-align:left;vertical-align:top}th{color:var(--accent);font-size:12px;text-transform:uppercase;letter-spacing:.08em;background:rgba(143,214,255,.06)}td{color:var(--text);word-break:break-word}.empty{color:var(--muted)}ul{margin:0;padding-left:var(--space-6)}li{margin:var(--space-2) 0}code,pre{font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;color:#d7ffea}code{background:rgba(125,223,154,.08);padding:2px 6px;border-radius:8px}pre{white-space:pre-wrap;word-break:break-word;margin:var(--space-4) 0 0;max-height:520px;overflow:auto}.risk{border-color:rgba(255,190,92,.45)}.command-bank{border-color:rgba(143,214,255,.35)}details summary{cursor:pointer;color:var(--accent);font-weight:700}.section-note{margin:0 0 var(--space-4);color:var(--muted)}.hygiene.warning{border-color:rgba(255,190,92,.45)}.hygiene.info{border-color:rgba(143,214,255,.35)}.hygiene h3{margin:var(--space-6) 0 var(--space-3);font-size:13px;color:var(--accent);text-transform:uppercase;letter-spacing:.12em}.hygiene-metrics{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:var(--space-3);margin:var(--space-4) 0}.hygiene-count{border:1px solid rgba(255,255,255,.1);background:rgba(0,0,0,.18);border-radius:14px;padding:var(--space-3)}.hygiene-count span{display:block;color:var(--muted);text-transform:uppercase;font-size:11px;letter-spacing:.09em}.hygiene-count strong{display:block;font-size:24px;line-height:1.1}.hygiene-count.good strong,.status-pill.good{color:var(--good)}.hygiene-count.warn strong,.status-pill.warn{color:var(--warn)}.hygiene-count.bad strong,.status-pill.bad{color:var(--bad)}.status-pill{display:inline-block;text-transform:uppercase;font-size:12px;font-weight:800;letter-spacing:.08em}.hygiene-alert{color:var(--bad);font-weight:800}@media(max-width:800px){.half,.third{grid-column:span 12}.hygiene-metrics{grid-template-columns:repeat(2,minmax(0,1fr))}header,main{width:min(100% - 20px,1180px)}th,td{padding:var(--space-2)}}`;
+}
+
+export function renderGuardianReportHtml(input: { reportPath: string; generatedAt: string; status: LooseRecord; recover: LooseRecord }) {
+  const { reportPath, generatedAt, status, recover } = input;
+  const sessions = arrayValue(status.sessions);
+  const worktrees = arrayValue(status.worktrees);
+  const orphanedSessions = arrayValue(status.orphanedSessions);
+  const worktreesWithoutState = arrayValue(status.worktreesWithoutState);
+  const dirtyFiles = arrayValue(status.dirtyFiles);
+  const stashes = arrayValue(status.stashes);
+  const safetyRefs = arrayValue(status.safetyRefs);
+  const recoveryCandidates = arrayValue(recover.recoveryCandidates);
+  const hygiene = recordValue(status.hygiene);
+  const hygieneSummary = recordValue(hygiene.summary);
+  const hygieneBySeverity = recordValue(hygieneSummary.bySeverity);
+  const hygieneFindingCount = numberValue(hygieneSummary.findingCount, arrayValue(hygiene.findings).length);
+  const hygieneFailCount = numberValue(hygieneBySeverity.fail);
+  const riskCount = orphanedSessions.length + worktreesWithoutState.length + dirtyFiles.length + stashes.length + hygieneFindingCount;
+  const rawJson = JSON.stringify({ reportPath, generatedAt, status, recover }, null, 2);
+
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escapeHtml(CSP)}"><title>Guardian Control Report</title><style>${styles()}</style></head><body><header><div class="eyebrow">OpenCode Worktree Guardian</div><h1>Control Report</h1><p class="timestamp">Generated ${escapeHtml(generatedAt)} for <code>${escapeHtml(status.repoRoot)}</code></p><p class="timestamp">Offline file: <code>${escapeHtml(reportPath)}</code></p></header><main><section class="grid" aria-label="Guardian summary metrics">${metric("Sessions", sessions.length, sessions.length > 0 ? "good" : "")}${metric("Worktrees", worktrees.length, worktrees.length > 0 ? "good" : "")}${metric("Risks", riskCount, riskCount > 0 ? "warn" : "good")}${metric("Safety Refs", safetyRefs.length, safetyRefs.length > 0 ? "warn" : "")}${metric("Recovery Candidates", recoveryCandidates.length, recoveryCandidates.length > 0 ? "warn" : "good")}${metric("Dirty Files", dirtyFiles.length, dirtyFiles.length > 0 ? "bad" : "good")}${metric("Hygiene Findings", hygieneFindingCount, hygieneFailCount > 0 ? "bad" : hygieneFindingCount > 0 ? "warn" : "good")}</section><section class="grid"><section class="card"><h2>Sessions</h2>${sessionsTable(sessions)}</section><section class="card"><h2>Worktrees</h2>${worktreesTable(worktrees)}</section><section class="card half"><h2>Branch Coverage</h2>${branchesTable(arrayValue(status.branchesWithoutWorktrees))}</section>${listSection("Orphaned Sessions", orphanedSessions, "risk")}${listSection("Worktrees Without State", worktreesWithoutState, "risk")}${listSection("Dirty Files", dirtyFiles, "risk")}${listSection("Stashes", stashes, "risk")}${hygieneSection(hygiene)}${listSection("Safety Refs", safetyRefs, "info")}${listSection("Recovery Candidates", recoveryCandidates, "info")}${commandSection(arrayValue(recover.suggestedCommands))}<section class="card"><h2>Raw Guardian JSON</h2><details><summary>Open raw status and recovery metadata</summary><pre>${escapeHtml(rawJson)}</pre></details></section></section></main></body></html>\n`;
+}
+
+export async function guardianReportHtml(input: LooseRecord = {}) {
+  const status = await guardianStatus(input);
+  const recover = await guardianRecover(input);
+  const paths = await getGuardianPaths(String(status.repoRoot));
+  const generatedAt = new Date().toISOString();
+  const html = renderGuardianReportHtml({ reportPath: paths.reportPath, generatedAt, status, recover });
+  await writeReportAtomic(paths, html);
+  return { ok: true, reportPath: paths.reportPath, status, recover };
+}

package/src/session/context.ts

@@ -0,0 +1,41 @@
+import { loadConfig, normalizeConfig } from "../config.ts";
+import type { GuardianConfig, GuardianStateRecord, GuardianToolInput } from "../types.ts";
+import { isRecordLike } from "../types.ts";
+
+export 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 function stateFromInput(value: unknown): GuardianStateRecord | null {
+  if (!isRecordLike(value)) return null;
+  const sessions: GuardianStateRecord["sessions"] = {};
+  if (isRecordLike(value.sessions)) {
+    for (const [sessionId, session] of Object.entries(value.sessions)) {
+      if (isRecordLike(session)) sessions[sessionId] = session;
+    }
+  }
+  return {
+    ...value,
+    sessions,
+  };
+}
+
+export function sessionIdFromInput(input: GuardianToolInput): string | null {
+  const rawSessionId = input.sessionId ?? input.sessionID;
+  return rawSessionId == null || rawSessionId === "" ? null : String(rawSessionId);
+}
+
+export type WorktreeCache = {
+  readonly get: (key: string) => unknown;
+  readonly set: (key: string, value: string) => unknown;
+};
+
+export function worktreeCache(value: unknown): WorktreeCache | null {
+  if (!(value instanceof Map)) return null;
+  return {
+    get: (key: string) => value.get(key),
+    set: (key: string, nextValue: string) => value.set(key, nextValue),
+  };
+}

package/src/session/last-safe-state.ts

@@ -0,0 +1,27 @@
+import { getCurrentBranch, getHeadCommit, getRepoRoot } from "../git.ts";
+import { isTerminalSession } from "../lifecycle.ts";
+import { getGuardianPaths, readState } from "../state.ts";
+import type { GuardianToolInput, GuardianToolResult } from "../types.ts";
+import { isRecordLike } from "../types.ts";
+import { configFromInput, sessionIdFromInput } from "./context.ts";
+import { protectedBranchReason, recordActiveSession } from "./worktree-binding.ts";
+
+export async function recordLastSafeState(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) return { ok: false, reason: "sessionId is required" };
+  const guardianPaths = await getGuardianPaths(repoRoot);
+  const state = await readState(guardianPaths, { repoRoot, config });
+  const rawExisting = state.sessions?.[sessionId];
+  const existing = isRecordLike(rawExisting) ? rawExisting : undefined;
+  if (existing && isTerminalSession(existing)) return { ok: true, status: "skipped", reason: `session ${sessionId} is terminal (${String(existing.status)})`, session: existing };
+  const worktreePath = await getRepoRoot(cwd);
+  const branch = await getCurrentBranch(worktreePath);
+  if (!branch) return { ok: false, reason: "detached HEAD" };
+  const unsafeReason = protectedBranchReason(config, branch);
+  if (unsafeReason) return { ok: false, reason: unsafeReason, branch, worktreePath };
+  await getHeadCommit(worktreePath);
+  return recordActiveSession({ repoRoot, config, sessionId, worktreePath, branch, eventType: "last_safe_state", tool: input.tool });
+}

package/src/session/worktree-binding.ts

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { expandWorktreeRoot } from "../config.ts";
+import { getCurrentBranch, getHeadCommit, getRepoRoot, listWorktrees } from "../git.ts";
+import { isTerminalSession } from "../lifecycle.ts";
+import { getGuardianPaths, readState, recordSession } from "../state.ts";
+import type { GuardianConfig, GuardianToolInput, GuardianToolResult, MutableRecord, SessionWorktreeResult, WorktreeEntry } from "../types.ts";
+import { isRecordLike } from "../types.ts";
+import { configFromInput, sessionIdFromInput, stateFromInput, worktreeCache } from "./context.ts";
+
+function isSameOrInside(candidate: string, root: string) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export async function collectKnownWorktreePaths(input: GuardianToolInput = {}): Promise<string[]> {
+  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 paths = new Set<string>();
+  if (typeof input.currentWorktree === "string") paths.add(path.resolve(input.currentWorktree));
+  try {
+    const worktreeRoot = path.resolve(repoRoot, expandWorktreeRoot(config.worktreeRoot, repoRoot));
+    paths.add(worktreeRoot);
+  } catch {}
+  try {
+    for (const entry of await listWorktrees(repoRoot)) paths.add(path.resolve(entry.path));
+  } catch {}
+  try {
+    const guardianPaths = await getGuardianPaths(repoRoot);
+    const state = await readState(guardianPaths, { repoRoot, config });
+    const sessions = Object.values(state.sessions ?? {});
+    for (const session of sessions) {
+      if (isRecordLike(session) && typeof session.worktree_path === "string") paths.add(path.resolve(session.worktree_path));
+    }
+  } catch {}
+  return [...paths];
+}
+
+function matchesWorktree(expectedWorktree: string, actualPath: string) {
+  return isSameOrInside(path.resolve(actualPath), path.resolve(expectedWorktree));
+}
+
+function samePath(left: string, right: string) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+async function validateRecordedBinding(repoRoot: string, config: GuardianConfig, session: MutableRecord, actualWorktree: string) {
+  const expectedWorktree = session.worktree_path;
+  if (typeof expectedWorktree !== "string") return { ok: false, reason: "recorded session has no worktree path" };
+  if (!matchesWorktree(expectedWorktree, actualWorktree)) return { ok: false, reason: "session worktree path does not match actual worktree" };
+  const entries = await listWorktrees(repoRoot);
+  const matches = entries.filter((entry: WorktreeEntry) => samePath(entry.path, expectedWorktree));
+  if (matches.length !== 1) return { ok: false, reason: matches.length > 1 ? "recorded worktree path matches multiple git worktrees" : "recorded worktree is not checked out in git worktree list" };
+  const entry = matches[0];
+  if (!entry) return { ok: false, reason: "recorded worktree is not checked out in git worktree list" };
+  if (entry.detached || !entry.branch) return { ok: false, reason: "recorded worktree is detached" };
+  if (typeof session.branch === "string" && entry.branch !== session.branch) return { ok: false, reason: "recorded branch does not match checked-out worktree branch" };
+  if (Array.isArray(config.protectedBranches) && config.protectedBranches.includes(entry.branch)) return { ok: false, reason: "recorded worktree branch is protected" };
+  if (samePath(entry.path, repoRoot)) return { ok: false, reason: "recorded worktree is the primary repository worktree" };
+  return { ok: true, branch: entry.branch };
+}
+
+export async function validateOwnedSession(repoRoot: string, config: GuardianConfig, session: MutableRecord) {
+  if (typeof session.worktree_path !== "string") return { ok: false, reason: "recorded session has no worktree path" };
+  return validateRecordedBinding(repoRoot, config, session, session.worktree_path);
+}
+
+export function protectedBranchReason(config: GuardianConfig, branch: string | null) {
+  if (!branch) return "detached HEAD cannot be recorded by guardian";
+  return Array.isArray(config.protectedBranches) && config.protectedBranches.includes(branch)
+    ? "protected branches cannot be recorded as Guardian-owned worktrees"
+    : null;
+}
+
+export async function resolveSessionWorktree(input: GuardianToolInput = {}): Promise<SessionWorktreeResult> {
+  const sessionId = sessionIdFromInput(input);
+  if (!sessionId) return { ok: true, sessionId: null, expectedWorktree: null, actualWorktree: null, matches: true };
+
+  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 actualWorktree = typeof input.actualWorktree === "string" ? input.actualWorktree : await getRepoRoot(cwd);
+  const cache = worktreeCache(input.cache);
+  const validateBinding = input.validateBinding === true;
+  const cachedWorktree = cache?.get(sessionId);
+
+  if (typeof cachedWorktree === "string" && !validateBinding) {
+    const matches = matchesWorktree(cachedWorktree, actualWorktree);
+    return {
+      ok: matches,
+      sessionId,
+      expectedWorktree: cachedWorktree,
+      actualWorktree,
+      matches,
+      source: "cache",
+    };
+  }
+
+  const config = await configFromInput(input, repoRoot);
+  const state = stateFromInput(input.state) ?? await readState(await getGuardianPaths(repoRoot), { repoRoot, config });
+  const rawSession = state.sessions?.[sessionId];
+  const session = isRecordLike(rawSession) ? rawSession : undefined;
+  if (session && isTerminalSession(session)) {
+    return { ok: true, sessionId, expectedWorktree: null, actualWorktree, matches: true, source: "terminal-state", terminal: true, status: typeof session.status === "string" ? session.status : undefined };
+  }
+  const expectedWorktree = typeof session?.worktree_path === "string" ? session.worktree_path : null;
+  if (!session || !expectedWorktree) {
+    return { ok: true, sessionId, expectedWorktree: null, actualWorktree, matches: true, source: "state" };
+  }
+
+  cache?.set(sessionId, expectedWorktree);
+  const matches = matchesWorktree(expectedWorktree, actualWorktree);
+  if (matches && validateBinding) {
+    const binding = await validateRecordedBinding(repoRoot, config, session, actualWorktree);
+    if (!binding.ok) {
+      return {
+        ok: false,
+        reason: binding.reason,
+        sessionId,
+        expectedWorktree,
+        actualWorktree,
+        matches: false,
+        source: "state",
+      };
+    }
+  }
+  return {
+    ok: matches,
+    sessionId,
+    expectedWorktree,
+    actualWorktree,
+    matches,
+    source: "state",
+  };
+}
+
+export async function recordActiveSession(input: {
+  readonly repoRoot: string;
+  readonly config: GuardianConfig;
+  readonly sessionId: string;
+  readonly worktreePath: string;
+  readonly branch: string;
+  readonly eventType: string;
+  readonly tool?: unknown;
+}): Promise<GuardianToolResult> {
+  const headCommit = await getHeadCommit(input.worktreePath);
+  const recordedState = await recordSession(input.repoRoot, input.config, {
+    session_id: input.sessionId,
+    status: "active",
+    branch: input.branch,
+    worktree_path: input.worktreePath,
+    base_ref: `${input.config.remote}/${input.config.baseBranch}`,
+    head_commit: headCommit,
+  }, { event: { type: input.eventType, session_id: input.sessionId, tool: input.tool } });
+  return { ok: true, session: recordedState.sessions[input.sessionId], stateVersion: recordedState.state_version };
+}
+
+export async function currentWorktreeBranch(cwd: string) {
+  const worktreePath = await getRepoRoot(cwd);
+  const branch = await getCurrentBranch(worktreePath);
+  return { worktreePath, branch };
+}

package/src/start.ts

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { expandWorktreeRoot } from "./config.ts";
+import { getCurrentBranch, getHeadCommit, getRepoRoot, runGit } from "./git.ts";
+import { isTerminalSession } from "./lifecycle.ts";
+import { getGuardianPaths, readState, recordSession } from "./state.ts";
+import type { GuardianSession, GuardianToolInput, GuardianToolResult, MutableRecord } from "./types.ts";
+import { errorCode, isRecordLike } from "./types.ts";
+import { configFromInput, sessionIdFromInput } from "./session/context.ts";
+import { protectedBranchReason, validateOwnedSession } from "./session/worktree-binding.ts";
+
+async function safeRealpath(candidate: string) {
+  try {
+    return await fs.realpath(candidate);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+    return path.resolve(candidate);
+  }
+}
+
+function isSameOrInside(candidate: string, root: string) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+type CreateSessionWorktreeResult =
+  | { readonly ok: true; readonly branch: string; readonly worktreePath: string }
+  | { readonly ok: false; readonly status: "blocked"; readonly reason: string; readonly branch: string };
+
+type GuardianStartTypedSession = GuardianSession & {
+  readonly session_id: string;
+  readonly branch: string;
+  readonly worktree_path: string;
+};
+
+export type GuardianStartResult = GuardianToolResult & {
+  readonly session: GuardianStartTypedSession;
+  readonly previous: MutableRecord & {
+    readonly branch: string;
+    readonly worktree_path: string;
+    readonly reason: string;
+  };
+  readonly reason: string;
+  readonly branch: string;
+};
+
+async function resolveWorktreeTarget(repoRoot: string, config: Awaited<ReturnType<typeof configFromInput>>, requestedPath: string | undefined, branchName: string) {
+  const root = path.resolve(repoRoot, expandWorktreeRoot(config.worktreeRoot, repoRoot));
+  await fs.mkdir(root, { recursive: true });
+  const resolvedRoot = await safeRealpath(root);
+  const target = requestedPath ? path.resolve(repoRoot, requestedPath) : path.join(resolvedRoot, slug(branchName));
+  const parent = path.dirname(target);
+  await fs.mkdir(parent, { recursive: true });
+  const resolvedParent = await safeRealpath(parent);
+  const resolvedTarget = path.join(resolvedParent, path.basename(target));
+  if (!isSameOrInside(resolvedTarget, resolvedRoot)) {
+    throw new Error(`worktreePath must stay inside configured worktreeRoot: ${config.worktreeRoot}`);
+  }
+  return resolvedTarget;
+}
+
+function slug(value: unknown) {
+  return String(value ?? "work")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "work";
+}
+
+async function createSessionWorktree(repoRoot: string, config: Awaited<ReturnType<typeof configFromInput>>, input: GuardianToolInput, sessionId: string): Promise<CreateSessionWorktreeResult> {
+  const branchName = typeof input.branch === "string" ? input.branch : `${config.branchPrefix}${slug(input.taskName)}-${slug(sessionId).slice(0, 8)}`;
+  const unsafeReason = protectedBranchReason(config, branchName);
+  if (unsafeReason) return { ok: false, status: "blocked", reason: unsafeReason, branch: branchName };
+  const worktreePath = await resolveWorktreeTarget(repoRoot, config, typeof input.worktreePath === "string" ? input.worktreePath : undefined, branchName);
+  await runGit(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, `${config.remote}/${config.baseBranch}`]);
+  return { ok: true, branch: branchName, worktreePath };
+}
+
+export function guardianStart(input?: GuardianToolInput): Promise<GuardianStartResult>;
+export async function guardianStart(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 guardianPaths = await getGuardianPaths(repoRoot);
+  const state = await readState(guardianPaths, { repoRoot, config });
+  const rawExisting = state.sessions?.[sessionId];
+  const existing = isRecordLike(rawExisting) ? rawExisting : undefined;
+  if (existing && isTerminalSession(existing)) {
+    return {
+      ok: false,
+      status: "blocked",
+      reason: `session ${sessionId} is terminal (${String(existing.status)}); start a new session instead of recreating a deleted or finished worktree`,
+      session: existing,
+      stateVersion: state.state_version,
+    };
+  }
+  if (existing?.status === "active" && typeof existing.worktree_path === "string") {
+    const binding = await validateOwnedSession(repoRoot, config, existing);
+    if (binding.ok) return { ok: true, session: existing, stateVersion: state.state_version, existing: true };
+    if (input.createWorktree !== true) {
+      return {
+        ok: false,
+        status: "blocked",
+        reason: `recorded session cannot be used: ${binding.reason}; rerun guardian_start with createWorktree=true`,
+        session: existing,
+        stateVersion: state.state_version,
+      };
+    }
+    const previous = { worktree_path: existing.worktree_path, branch: existing.branch, reason: binding.reason };
+    const created = await createSessionWorktree(repoRoot, config, input, sessionId);
+    if (!created.ok) return { ...created, session: existing, stateVersion: state.state_version, previous };
+    const headCommit = await getHeadCommit(created.worktreePath);
+    const repairedSession = {
+      ...existing,
+      session_id: sessionId,
+      status: "active",
+      branch: created.branch,
+      worktree_path: created.worktreePath,
+      base_ref: `${config.remote}/${config.baseBranch}`,
+      head_commit: headCommit,
+      safety_refs: Array.isArray(existing.safety_refs) ? existing.safety_refs.filter((value): value is string => typeof value === "string") : [],
+    };
+    const repairedState = await recordSession(repoRoot, config, repairedSession, { event: { type: "guardian_start_repair", session_id: sessionId, reason: binding.reason } });
+    const recordedSession = repairedState.sessions[sessionId];
+    if (!recordedSession) throw new Error(`guardian_start repair failed to record session ${sessionId}`);
+    return { ok: true, session: recordedSession, stateVersion: repairedState.state_version, existing: false, repaired: true, previous };
+  }
+
+  let worktreePath = await getRepoRoot(cwd);
+  let branch = await getCurrentBranch(worktreePath);
+
+  if (input.createWorktree === true) {
+    const created = await createSessionWorktree(repoRoot, config, input, sessionId);
+    if (!created.ok) return { ...created, stateVersion: state.state_version };
+    worktreePath = created.worktreePath;
+    branch = created.branch;
+  }
+
+  if (!branch) throw new Error("Cannot start guardian session from detached HEAD");
+  const unsafeReason = input.createWorktree === true ? null : protectedBranchReason(config, branch);
+  if (unsafeReason) return { ok: false, status: "blocked", reason: unsafeReason, branch, worktreePath };
+  const headCommit = await getHeadCommit(worktreePath);
+  const session = {
+    session_id: sessionId,
+    status: "active",
+    branch,
+    worktree_path: worktreePath,
+    base_ref: `${config.remote}/${config.baseBranch}`,
+    head_commit: headCommit,
+    safety_refs: [],
+  };
+
+  const recordedState = await recordSession(repoRoot, config, session, { event: { type: "guardian_start", session_id: sessionId } });
+  return { ok: true, session: recordedState.sessions[sessionId], stateVersion: recordedState.state_version };
+}