patchwarden 0.6.4 → 1.5.0

package/src/tools/safeViews.ts

@@ -0,0 +1,273 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { auditSession } from "./auditSession.js";
+import { auditTask, type AuditTaskOutput } from "./auditTask.js";
+import { finalizeDirectSession } from "./finalizeDirectSession.js";
+import { getTaskSummary } from "./getTaskSummary.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { redactSensitiveValue } from "../security/contentRedaction.js";
+import { readDirectSession, type DirectSessionRecord, type DirectSessionVerificationRun } from "../direct/directSessionStore.js";
+import type { ChangedFile, ClassifiedChange } from "../runner/changeCapture.js";
+
+export interface SafeViewOptions {
+  max_items?: number;
+}
+
+export function safeResult(taskId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  const summary = getTaskSummary(taskId, { view: "compact", max_items: maxItems });
+  return redact({
+    task_id: summary.task_id,
+    status: summary.status,
+    terminal: summary.terminal,
+    acceptance_status: summary.acceptance_status,
+    phase: summary.phase,
+    repo_path: summary.repo_path,
+    changed_files_total: summary.changed_files_total,
+    out_of_scope_changes_total: summary.out_of_scope_changes_total,
+    artifact_hygiene_counts: summary.artifact_hygiene.counts,
+    release_artifacts_count: summary.release_artifacts_count,
+    artifact_status: summary.artifact_status,
+    verification: summary.verification_summary,
+    warnings: limitStrings(summary.warnings, maxItems),
+    errors: limitStrings(summary.errors, maxItems),
+    failure_reason: summary.failure_reason,
+    failed_command: summary.failed_command,
+    next_action: summary.suggested_next_action,
+    execution_blocked: summary.execution_blocked,
+    pending_reason: summary.pending_reason,
+    redacted: summary.redacted,
+    redaction_categories: summary.redaction_categories,
+  });
+}
+
+export function safeTestSummary(taskId: string) {
+  const { taskDir, config } = getTaskDir(taskId);
+  const verify = readJson(join(taskDir, "verify.json"), config);
+  const summary = getTaskSummary(taskId, { view: "compact", max_items: 8 });
+  const commands = asArray(verify.commands).map((entry: any) => ({
+    command: String(entry.command || ""),
+    status: String(entry.status || "unknown"),
+    exit_code: entry.exit_code ?? null,
+    duration_ms: Number(entry.duration_ms || 0),
+  }));
+  return redact({
+    task_id: taskId,
+    status: String(verify.status || summary.verification_summary.status || "not_available"),
+    command_count: commands.length,
+    passed_commands: commands.filter((entry) => entry.status === "passed").length,
+    failed_commands: commands.filter((entry) => ["failed", "timed_out", "canceled"].includes(entry.status)).length,
+    skipped_commands: commands.filter((entry) => entry.status === "skipped").length,
+    commands,
+    headline: summary.verification_summary.headline,
+  });
+}
+
+export function safeDiffSummary(taskId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  const { taskDir, config } = getTaskDir(taskId);
+  const changes = readJson(join(taskDir, "changed-files.json"), config);
+  const changedFiles = asArray(changes.changed_files) as ChangedFile[];
+  const hygiene = asRecord(changes.artifact_hygiene);
+  return redact({
+    task_id: taskId,
+    changed_files_total: changedFiles.length,
+    additions: Number(changes.additions || 0),
+    deletions: Number(changes.deletions || 0),
+    diff_available: Boolean(changes.diff_available),
+    diff_truncated: Boolean(changes.diff_truncated),
+    patch_mode: changes.patch_mode || null,
+    files: changedFiles.slice(0, maxItems).map((file) => ({
+      path: file.path,
+      old_path: file.old_path || null,
+      change: file.change,
+      kind: file.kind,
+      tracked: Boolean(file.tracked),
+      ignored: Boolean(file.ignored),
+    })),
+    artifact_hygiene_counts: asRecord(hygiene.counts),
+    large_diff_omitted: true,
+    truncated: changedFiles.length > maxItems,
+  });
+}
+
+export function safeAudit(taskId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  return auditToSafe(auditTask(taskId) as AuditTaskOutput, maxItems);
+}
+
+export function safeDirectSummary(sessionId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  const session = readDirectSession(sessionId);
+  return directSessionToSafe(session, maxItems, "summary");
+}
+
+export function safeFinalizeDirectSession(sessionId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  const finalized = finalizeDirectSession({ session_id: sessionId });
+  const session = readDirectSession(sessionId);
+  return redact({
+    ...directSessionToSafe(session, maxItems, "finalize"),
+    finalized: finalized.finalized,
+    next_action: finalized.next_action,
+  });
+}
+
+export function safeAuditDirectSession(sessionId: string, options: SafeViewOptions = {}) {
+  const maxItems = normalizeMaxItems(options.max_items);
+  const audit = auditSession({ session_id: sessionId });
+  return redact({
+    session_id: audit.session_id,
+    decision: audit.decision,
+    reason_codes: audit.reason_codes.slice(0, maxItems),
+    blocking_findings: limitStrings(audit.blocking_findings, maxItems),
+    warnings: limitStrings(audit.warnings, maxItems),
+    evidence: {
+      changed_files_total: audit.evidence.changed_files_total,
+      verification_runs: summarizeVerificationRuns(audit.evidence.verification_runs),
+      diff_available: Boolean(audit.evidence.diff_path),
+      summary_available: Boolean(audit.evidence.summary_path),
+      audit_available: Boolean(audit.evidence.audit_path),
+    },
+    next_action: audit.next_action,
+  });
+}
+
+function auditToSafe(audit: AuditTaskOutput, maxItems: number) {
+  const checks = audit.checks.map((check) => ({
+    name: check.name,
+    result: check.result,
+    detail: truncate(check.detail, 240),
+  }));
+  return redact({
+    task_id: audit.task_id,
+    verdict: audit.verdict,
+    acceptance: {
+      verdict: audit.acceptance.verdict,
+      status: audit.acceptance.status,
+      reason: truncate(audit.acceptance.reason, 240),
+      fail_checks: audit.acceptance.fail_checks.slice(0, maxItems).map((check) => check.name),
+      warn_checks: audit.acceptance.warn_checks.slice(0, maxItems).map((check) => check.name),
+      next_suggested_task: truncate(audit.acceptance.next_suggested_task, 240),
+    },
+    check_counts: {
+      pass: checks.filter((check) => check.result === "pass").length,
+      warn: checks.filter((check) => check.result === "warn").length,
+      fail: checks.filter((check) => check.result === "fail").length,
+    },
+    checks: checks.slice(0, maxItems),
+    fail_checks: checks.filter((check) => check.result === "fail").slice(0, maxItems),
+    warn_checks: checks.filter((check) => check.result === "warn").slice(0, maxItems),
+    possible_false_positives: audit.possible_false_positives.slice(0, maxItems).map((item) => ({
+      check: item.check,
+      reason: truncate(item.reason, 240),
+    })),
+    manual_verification_required: audit.manual_verification_required,
+    manual_verification_items: limitStrings(audit.manual_verification_items, maxItems),
+    recommended_next_actions: limitStrings(audit.recommended_next_actions, maxItems),
+  });
+}
+
+function directSessionToSafe(session: DirectSessionRecord, maxItems: number, view: "summary" | "finalize") {
+  const artifacts = session.change_artifacts;
+  const changedFiles = artifacts?.changed_files || [];
+  return redact({
+    view,
+    session_id: session.session_id,
+    title: session.title || "",
+    repo_path: session.repo_path,
+    created_at: session.created_at,
+    expires_at: session.expires_at,
+    finalized: session.finalized,
+    finalized_at: session.finalized_at,
+    audited: session.audited,
+    changed_files_total: changedFiles.length,
+    files: changedFiles.slice(0, maxItems).map((file) => ({
+      path: file.path,
+      old_path: file.old_path || null,
+      change: file.change,
+      kind: file.kind,
+      tracked: Boolean(file.tracked),
+      ignored: Boolean(file.ignored),
+    })),
+    artifact_hygiene_counts: artifacts?.artifact_hygiene.counts || {},
+    source_changes: limitClassified(artifacts?.artifact_hygiene.source_changes, maxItems),
+    tracked_build_artifacts: limitClassified(artifacts?.artifact_hygiene.tracked_build_artifacts, maxItems),
+    runtime_generated_files: limitClassified(artifacts?.artifact_hygiene.runtime_generated_files, maxItems),
+    suspicious_changes: limitClassified(artifacts?.artifact_hygiene.suspicious_changes, maxItems),
+    verification: summarizeVerificationRuns(session.verification_runs),
+    large_diff_omitted: true,
+    truncated: changedFiles.length > maxItems,
+  });
+}
+
+function summarizeVerificationRuns(runs: DirectSessionVerificationRun[]) {
+  return runs.map((run) => ({
+    command: run.command,
+    exit_code: run.exit_code,
+    passed: run.passed,
+    timed_out: run.timed_out,
+    redacted: Boolean(run.redacted),
+    redaction_categories: run.redaction_categories || [],
+    started_at: run.started_at,
+    finished_at: run.finished_at,
+  }));
+}
+
+function limitClassified(value: ClassifiedChange[] | undefined, maxItems: number) {
+  return (value || []).slice(0, maxItems).map((entry) => ({
+    path: entry.path,
+    change: entry.change,
+    kind: entry.kind,
+    tracked: entry.tracked,
+    ignored: entry.ignored,
+    reason: truncate(entry.reason, 160),
+  }));
+}
+
+function getTaskDir(taskId: string) {
+  const config = getConfig();
+  const taskDir = resolve(getTasksDir(config), taskId);
+  guardReadPath(join(taskDir, "status.json"), config.workspaceRoot, config.tasksDir);
+  return { config, taskDir };
+}
+
+function readJson(path: string, config: ReturnType<typeof getConfig>): Record<string, any> {
+  guardReadPath(path, config.workspaceRoot, config.tasksDir);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf-8").replace(/^\uFEFF/, "");
+    return asRecord(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+
+function normalizeMaxItems(value: number | undefined): number {
+  if (value === undefined) return 8;
+  if (!Number.isInteger(value) || value < 1 || value > 50) {
+    throw new Error("max_items must be an integer from 1 to 50.");
+  }
+  return value;
+}
+
+function asArray(value: unknown): any[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function asRecord(value: unknown): Record<string, any> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+}
+
+function limitStrings(values: string[], maxItems: number): string[] {
+  return values.slice(0, maxItems).map((value) => truncate(value, 240));
+}
+
+function truncate(value: string, maxChars: number): string {
+  return value.length <= maxChars ? value : `${value.slice(0, maxChars)}...`;
+}
+
+function redact<T>(value: T): T {
+  return redactSensitiveValue(value).value as T;
+}

package/src/tools/schemaDriftCheck.ts

@@ -0,0 +1,120 @@
+/**
+ * v0.9.0: Schema 漂移检测模块。
+ *
+ * 检测 registry 元数据与实际工具 schema 是否漂移，
+ * 并聚合为可被 doctor 自检消费的 SchemaDriftResult。
+ *
+ * 本模块只做检测和报告，不做运行时阻断。
+ */
+
+import { computeSchemaDigest } from "./toolRegistry.js";
+import type { PatchWardenToolMeta } from "./toolRegistry.js";
+import { CHATGPT_CORE_TOOL_NAMES } from "./toolCatalog.js";
+
+// ── 结果类型 ──────────────────────────────────────────────────────
+
+export interface SchemaDriftResult {
+  /** true 表示无 drift，false 表示有 drift */
+  ok: boolean;
+  /** drift 描述列表（每个 drift 一条警告消息） */
+  warnings: string[];
+}
+
+/** toolDefs Map 的值类型：至少包含 inputSchema。 */
+export interface ToolDefLike {
+  inputSchema: unknown;
+}
+
+/** chatgpt_core profile 的预期工具数（来自 CHATGPT_CORE_TOOL_NAMES）。 */
+const EXPECTED_CORE_COUNT = CHATGPT_CORE_TOOL_NAMES.length;
+
+// ── 检查 1: registry schema digest 一致性 ─────────────────────────
+
+/**
+ * 检查 registry 中记录的 inputSchemaDigest 与实际 toolDef 的 inputSchema digest 是否一致。
+ * toolDefs 中找不到的工具会被跳过（不报 drift）。
+ */
+export function checkRegistrySchemaDigest(
+  registry: PatchWardenToolMeta[],
+  toolDefs: Map<string, ToolDefLike>,
+): SchemaDriftResult {
+  const warnings: string[] = [];
+  for (const meta of registry) {
+    const toolDef = toolDefs.get(meta.name);
+    if (!toolDef) continue; // toolDefs 中找不到该工具时跳过（不报 drift）
+    const actualDigest = computeSchemaDigest(toolDef.inputSchema);
+    if (actualDigest !== meta.inputSchemaDigest) {
+      warnings.push(
+        `Schema drift for tool '${meta.name}': registry digest ${meta.inputSchemaDigest} != actual digest ${actualDigest}`,
+      );
+    }
+  }
+  return { ok: warnings.length === 0, warnings };
+}
+
+// ── 检查 2: chatgpt_core manifest 稳定性 ──────────────────────────
+
+/**
+ * 校验 chatgpt_core profile 的工具 manifest 是否稳定。
+ *
+ * toolCatalog.ts 未导出独立的 manifest hash 计算函数（stableJson 为私有），
+ * 因此采用 fallback 方案：校验 CHATGPT_CORE_TOOL_NAMES 中的工具名
+ * 全部存在于 toolDefs 中（集合比较，不比较顺序——Map 迭代顺序取决于构造
+ * 方式，不一定与 chatgpt_core profile 顺序一致）。
+ *
+ * 真正的顺序稳定性由 CHATGPT_CORE_TOOL_NAMES 常量本身保证（顺序固定），
+ * 如果常量被修改，这里的名称集合比较也会检测到变化。
+ */
+export function checkChatgptCoreManifestStable(
+  toolDefs: Map<string, ToolDefLike>,
+): SchemaDriftResult {
+  const warnings: string[] = [];
+  const expected = [...CHATGPT_CORE_TOOL_NAMES];
+  // 检查 CHATGPT_CORE_TOOL_NAMES 中的每个工具是否都存在于 toolDefs
+  const missing = expected.filter((name) => !toolDefs.has(name));
+  if (missing.length > 0) {
+    warnings.push(
+      `chatgpt_core manifest has missing tools: ${missing.join(", ")} (expected ${EXPECTED_CORE_COUNT}, got ${EXPECTED_CORE_COUNT - missing.length})`,
+    );
+  }
+  return { ok: warnings.length === 0, warnings };
+}
+
+// ── 检查 3: chatgpt_core profile 工具数未变 ───────────────────────
+
+/**
+ * 校验 chatgpt_core profile 的工具数仍与 CHATGPT_CORE_TOOL_NAMES 一致。
+ * 用于检测是否有新工具被意外追加到 chatgpt_core profile。
+ */
+export function checkNewToolsProfileAppend(
+  registry: PatchWardenToolMeta[],
+): SchemaDriftResult {
+  const warnings: string[] = [];
+  const coreCount = registry.filter((t) => t.profiles.includes("chatgpt_core")).length;
+  if (coreCount !== EXPECTED_CORE_COUNT) {
+    warnings.push(
+      `chatgpt_core profile tool count changed: expected ${EXPECTED_CORE_COUNT}, got ${coreCount}`,
+    );
+  }
+  return { ok: warnings.length === 0, warnings };
+}
+
+// ── 聚合检查 ──────────────────────────────────────────────────────
+
+/**
+ * 聚合执行所有 schema drift 检查，合并 warnings。
+ * ok = warnings.length === 0
+ */
+export function runAllSchemaDriftChecks(
+  registry: PatchWardenToolMeta[],
+  toolDefs: Map<string, ToolDefLike>,
+): SchemaDriftResult {
+  const warnings: string[] = [];
+  const r1 = checkRegistrySchemaDigest(registry, toolDefs);
+  warnings.push(...r1.warnings);
+  const r2 = checkChatgptCoreManifestStable(toolDefs);
+  warnings.push(...r2.warnings);
+  const r3 = checkNewToolsProfileAppend(registry);
+  warnings.push(...r3.warnings);
+  return { ok: warnings.length === 0, warnings };
+}

package/src/tools/taskLineage.ts

@@ -0,0 +1,300 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { redactSensitiveValue } from "../security/contentRedaction.js";
+import { PatchWardenError } from "../errors.js";
+
+export type TaskLoopStopReason =
+  | "success"
+  | "max_iterations_reached"
+  | "verification_failed"
+  | "high_risk_blocked"
+  | "user_confirmation_required"
+  | "agent_timeout"
+  | "policy_blocked"
+  | "watcher_blocked"
+  | "direct_profile_disabled"
+  | "direct_verification_failed"
+  | "direct_audit_failed";
+
+export interface TaskLineageDirectSession {
+  session_id: string;
+  status?: "passed" | "failed" | "skipped";
+  command_count?: number;
+  passed_commands?: number;
+  failed_commands?: number;
+  timed_out_commands?: number;
+  audit_decision?: "pass" | "warn" | "fail" | "not_run";
+  changed_files_total?: number;
+  next_action?: string;
+}
+
+export interface TaskLineageWorktree {
+  isolation_mode: "current_repo" | "worktree";
+  worktree_id?: string;
+  worktree_path?: string;
+  branch?: string;
+  requested_base_branch?: string;
+  cleanup: "keep" | "archive" | "delete_ignored_only";
+  status: "not_used" | "active" | "failed";
+  next_action: string;
+}
+
+export interface TaskLineageAgentRouting {
+  requested_agent: string | null;
+  selected_agent: string;
+  reason: string;
+  fallback: boolean;
+}
+
+export interface TaskLineageRound {
+  iteration: number;
+  task_id: string;
+  role: "main" | "fix_tests" | "cleanup";
+  status: string;
+  terminal: boolean;
+  verification_status: string;
+  audit_verdict: string;
+  fail_checks: string[];
+  warn_checks: string[];
+  next_action: string;
+}
+
+export interface TaskLineageRecord {
+  lineage_id: string;
+  goal: string;
+  repo_path: string;
+  created_at: string;
+  updated_at: string;
+  final_status: "accepted" | "needs_fix" | "blocked" | "failed";
+  stop_reason: TaskLoopStopReason;
+  next_action: string;
+  main_task: string | null;
+  fix_tasks: string[];
+  cleanup_tasks: string[];
+  direct_sessions: Array<string | TaskLineageDirectSession>;
+  rounds: TaskLineageRound[];
+  warnings: string[];
+  errors: string[];
+  worktree?: TaskLineageWorktree;
+  agent_routing?: TaskLineageAgentRouting;
+}
+
+export interface SafeTaskLineage {
+  lineage_id: string;
+  goal: string;
+  repo_path: string;
+  created_at: string;
+  updated_at: string;
+  final_status: TaskLineageRecord["final_status"];
+  stop_reason: TaskLoopStopReason;
+  next_action: string;
+  tasks: {
+    main: string | null;
+    fix: string[];
+    cleanup: string[];
+    direct_sessions: TaskLineageDirectSession[];
+  };
+  worktree: TaskLineageWorktree;
+  agent_routing: TaskLineageAgentRouting | null;
+  verification: {
+    latest_status: string;
+    passed: boolean;
+  };
+  rounds: TaskLineageRound[];
+  warnings: string[];
+  errors: string[];
+  truncated: boolean;
+}
+
+export function createLineageId(now = new Date()): string {
+  const stamp = now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  return `lineage_${stamp}_${randomBytes(4).toString("hex")}`;
+}
+
+export function writeTaskLineage(record: TaskLineageRecord): SafeTaskLineage {
+  const config = getConfig();
+  const lineageDir = resolve(config.workspaceRoot, ".patchwarden", "lineages", record.lineage_id);
+  mkdirSync(lineageDir, { recursive: true });
+  const safeRecord = redactSensitiveValue(record).value as TaskLineageRecord;
+  writeFileSync(join(lineageDir, "lineage.json"), JSON.stringify(safeRecord, null, 2) + "\n", "utf-8");
+  writeFileSync(join(lineageDir, "SUMMARY.md"), buildSummaryMarkdown(safeRecord), "utf-8");
+  return toSafeTaskLineage(safeRecord);
+}
+
+export function getTaskLineage(lineageId: string, options: { max_items?: number } = {}): SafeTaskLineage {
+  const maxItems = normalizeMaxItems(options.max_items);
+  if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+    throw new PatchWardenError(
+      "invalid_lineage_id",
+      "lineage_id may contain only letters, numbers, underscores, and hyphens.",
+      "Pass a lineage_id returned by run_task_loop.",
+      true,
+      { lineage_id: lineageId }
+    );
+  }
+  const config = getConfig();
+  const lineageFile = resolve(config.workspaceRoot, ".patchwarden", "lineages", lineageId, "lineage.json");
+  guardReadPath(lineageFile, config.workspaceRoot, ".patchwarden/lineages");
+  if (!existsSync(lineageFile)) {
+    throw new PatchWardenError(
+      "lineage_not_found",
+      `Task lineage not found: "${lineageId}".`,
+      "Pass a lineage_id returned by run_task_loop.",
+      true,
+      { lineage_id: lineageId }
+    );
+  }
+  const raw = readFileSync(lineageFile, "utf-8").replace(/^\uFEFF/, "");
+  const record = JSON.parse(raw) as TaskLineageRecord;
+  return toSafeTaskLineage(redactSensitiveValue(record).value as TaskLineageRecord, maxItems);
+}
+
+export function toSafeTaskLineage(record: TaskLineageRecord, maxItems = 8): SafeTaskLineage {
+  const rounds = record.rounds.slice(0, maxItems);
+  const latest = record.rounds[record.rounds.length - 1];
+  const directSessions = normalizeDirectSessions(record.direct_sessions);
+  return {
+    lineage_id: record.lineage_id,
+    goal: record.goal,
+    repo_path: record.repo_path,
+    created_at: record.created_at,
+    updated_at: record.updated_at,
+    final_status: record.final_status,
+    stop_reason: record.stop_reason,
+    next_action: record.next_action,
+    tasks: {
+      main: record.main_task,
+      fix: record.fix_tasks.slice(0, maxItems),
+      cleanup: record.cleanup_tasks.slice(0, maxItems),
+      direct_sessions: directSessions.slice(0, maxItems),
+    },
+    worktree: normalizeWorktree(record.worktree),
+    agent_routing: record.agent_routing ? {
+      requested_agent: record.agent_routing.requested_agent,
+      selected_agent: truncate(String(record.agent_routing.selected_agent), 120),
+      reason: truncate(String(record.agent_routing.reason), 240),
+      fallback: Boolean(record.agent_routing.fallback),
+    } : null,
+    verification: {
+      latest_status: latest?.verification_status || "not_available",
+      passed: latest?.verification_status === "passed",
+    },
+    rounds,
+    warnings: record.warnings.slice(0, maxItems).map((value) => truncate(value, 240)),
+    errors: record.errors.slice(0, maxItems).map((value) => truncate(value, 240)),
+    truncated:
+      record.rounds.length > maxItems ||
+      record.fix_tasks.length > maxItems ||
+      record.cleanup_tasks.length > maxItems ||
+      directSessions.length > maxItems ||
+      record.warnings.length > maxItems ||
+      record.errors.length > maxItems,
+  };
+}
+
+function buildSummaryMarkdown(record: TaskLineageRecord): string {
+  const rounds = record.rounds.map((round) =>
+    `- ${round.role} ${round.task_id}: ${round.status}, verification=${round.verification_status}, audit=${round.audit_verdict}`
+  );
+  return [
+    "# PatchWarden Task Lineage",
+    "",
+    `- Lineage: ${record.lineage_id}`,
+    `- Goal: ${record.goal}`,
+    `- Repo: ${record.repo_path}`,
+    `- Final status: ${record.final_status}`,
+    `- Stop reason: ${record.stop_reason}`,
+    `- Next action: ${record.next_action}`,
+    `- Isolation: ${normalizeWorktree(record.worktree).isolation_mode}`,
+    `- Worktree: ${formatWorktree(record.worktree)}`,
+    `- Agent routing: ${formatAgentRouting(record.agent_routing)}`,
+    "",
+    "## Tasks",
+    `- Main: ${record.main_task || "none"}`,
+    `- Fix tasks: ${record.fix_tasks.length > 0 ? record.fix_tasks.join(", ") : "none"}`,
+    `- Cleanup tasks: ${record.cleanup_tasks.length > 0 ? record.cleanup_tasks.join(", ") : "none"}`,
+    `- Direct sessions: ${formatDirectSessions(record.direct_sessions)}`,
+    "",
+    "## Rounds",
+    ...(rounds.length > 0 ? rounds : ["- None."]),
+    "",
+  ].join("\n");
+}
+
+function normalizeWorktree(value: TaskLineageWorktree | undefined): TaskLineageWorktree {
+  if (!value) {
+    return {
+      isolation_mode: "current_repo",
+      cleanup: "keep",
+      status: "not_used",
+      next_action: "none",
+    };
+  }
+  return {
+    isolation_mode: value.isolation_mode === "worktree" ? "worktree" : "current_repo",
+    worktree_id: value.worktree_id ? truncate(String(value.worktree_id), 120) : undefined,
+    worktree_path: value.worktree_path ? truncate(String(value.worktree_path), 260) : undefined,
+    branch: value.branch ? truncate(String(value.branch), 160) : undefined,
+    requested_base_branch: value.requested_base_branch ? truncate(String(value.requested_base_branch), 160) : undefined,
+    cleanup: value.cleanup,
+    status: value.status,
+    next_action: truncate(String(value.next_action || "review_worktree"), 240),
+  };
+}
+
+function formatWorktree(value: TaskLineageWorktree | undefined): string {
+  const worktree = normalizeWorktree(value);
+  if (worktree.isolation_mode !== "worktree") return "not used";
+  const id = worktree.worktree_id || "unknown";
+  const status = worktree.status || "unknown";
+  const branch = worktree.branch ? ` branch=${worktree.branch}` : "";
+  return `${id} status=${status}${branch}`;
+}
+
+function formatAgentRouting(value: TaskLineageAgentRouting | undefined): string {
+  if (!value) return "not recorded";
+  const requested = value.requested_agent ? ` requested=${value.requested_agent}` : "";
+  return `${value.selected_agent}${requested} reason=${truncate(value.reason, 160)}`;
+}
+
+function normalizeDirectSessions(value: Array<string | TaskLineageDirectSession>): TaskLineageDirectSession[] {
+  return value.map((entry) => {
+    if (typeof entry === "string") return { session_id: entry };
+    return {
+      session_id: String(entry.session_id || ""),
+      status: entry.status,
+      command_count: entry.command_count,
+      passed_commands: entry.passed_commands,
+      failed_commands: entry.failed_commands,
+      timed_out_commands: entry.timed_out_commands,
+      audit_decision: entry.audit_decision,
+      changed_files_total: entry.changed_files_total,
+      next_action: entry.next_action ? truncate(String(entry.next_action), 240) : undefined,
+    };
+  }).filter((entry) => entry.session_id !== "");
+}
+
+function formatDirectSessions(value: Array<string | TaskLineageDirectSession>): string {
+  const sessions = normalizeDirectSessions(value);
+  if (sessions.length === 0) return "none";
+  return sessions.map((entry) => {
+    const status = entry.status ? ` status=${entry.status}` : "";
+    const audit = entry.audit_decision ? ` audit=${entry.audit_decision}` : "";
+    return `${entry.session_id}${status}${audit}`;
+  }).join(", ");
+}
+
+function normalizeMaxItems(value: number | undefined): number {
+  if (value === undefined) return 8;
+  if (!Number.isInteger(value) || value < 1 || value > 50) {
+    throw new Error("max_items must be an integer from 1 to 50.");
+  }
+  return value;
+}
+
+function truncate(value: string, maxChars: number): string {
+  return value.length <= maxChars ? value : `${value.slice(0, maxChars)}...`;
+}