patchwarden 1.1.0 → 1.5.1

package/scripts/checks/lifecycle-smoke.js

@@ -175,7 +175,7 @@ try {
   await test("git diff captures tracked and untracked task changes", async () => {
     writeFileSync(join(repoPath, "preexisting-user-file.txt"), "preexisting and untouched\n", "utf-8");
     const plan = savePlan({ title: "Change capture", content: "Modify fixture files." });
-    const task = createTask({
+    const task = await createTask({
       plan_id: plan.plan_id,
       agent: "writer",
       repo_path: "repo",
@@ -231,7 +231,7 @@ try {
   });
 
   await test("inspect_only template fails when the agent changes repository files", async () => {
-    const task = createTask({
+    const task = await createTask({
       template: "inspect_only",
       goal: "Inspect the fixture without modifying files",
       agent: "writer",
@@ -249,7 +249,7 @@ try {
 
   await test("legacy test_command becomes one independent verification command", async () => {
     const plan = savePlan({ title: "Legacy verification", content: "No changes." });
-    const task = createTask({
+    const task = await createTask({
       plan_id: plan.plan_id,
       agent: "noop",
       repo_path: "repo",
@@ -267,7 +267,7 @@ try {
 
   await test("no-change task returns an explicit empty diff result", async () => {
     const plan = savePlan({ title: "No diff", content: "Do not change files." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`No-op task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
@@ -288,7 +288,7 @@ try {
 
   await test("large diff response is truncated while diff.patch remains complete", async () => {
     const plan = savePlan({ title: "Large diff", content: "Create a large text file." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "largewriter", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "largewriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`Large task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
@@ -300,7 +300,7 @@ try {
 
   await test("non-Git repositories return hash-only evidence with a reason", async () => {
     const plan = savePlan({ title: "Non-Git evidence", content: "Modify files in a non-Git repository." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "writer", repo_path: "plain-repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "writer", repo_path: "plain-repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`Non-Git task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
@@ -315,7 +315,7 @@ try {
 
   await test("binary Git changes remain reviewable as a textual Git binary patch", async () => {
     const plan = savePlan({ title: "Binary evidence", content: "Create a binary fixture." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "binarywriter", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "binarywriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`Binary task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
@@ -326,7 +326,7 @@ try {
 
   await test("artifact hygiene separates source, ignored output, runtime data, and suspicious changes", async () => {
     const plan = savePlan({ title: "Artifact hygiene", content: "Generate representative task outputs." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "artifactwriter", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "artifactwriter", repo_path: "repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`Artifact task failed: ${JSON.stringify(result)}`);
     const standard = getTaskSummary(task.task_id);
@@ -355,7 +355,7 @@ try {
 
   await test("deleted tracked files are identified with file stats", async () => {
     const plan = savePlan({ title: "Delete fixture", content: "Delete the designated fixture file." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "deleter", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "deleter", repo_path: "repo" });
     const result = await runTask(task.task_id);
     if (!isDoneStatus(result.status)) throw new Error(`Delete task failed: ${JSON.stringify(result)}`);
     const diff = getDiff(task.task_id);
@@ -366,7 +366,7 @@ try {
 
   await test("wait_for_task stays in the tool loop and returns terminal acceptance", async () => {
     const plan = savePlan({ title: "Wait loop", content: "Finish normally." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "writer", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "writer", repo_path: "repo" });
     const running = runTask(task.task_id);
     const waited = await waitForTask(task.task_id, 5);
     await raceWithTimeout(running, 15000, "wait_for_task loop did not terminate within 15s");
@@ -380,7 +380,7 @@ try {
 
   await test("wait_for_task explicitly requires another call when the task is not terminal", async () => {
     const plan = savePlan({ title: "Pending wait", content: "Remain queued for this check." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo" });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo" });
     const waited = await waitForTask(task.task_id, 1);
     if (waited.terminal || !waited.timed_out || !waited.continuation_required) {
       throw new Error(`Expected continuation response: ${JSON.stringify(waited)}`);
@@ -390,11 +390,17 @@ try {
 
   await test("running task summary includes heartbeat, phase, command, and elapsed time", async () => {
     const plan = savePlan({ title: "Running summary", content: "Wait." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
     const running = runTask(task.task_id);
     await waitForRunning(getTaskStatus, task.task_id);
-    await sleep(50);
-    const summary = getTaskSummary(task.task_id);
+    // Wait for the task to transition from "preparing" to actually running a command.
+    // Async snapshot may delay the preparing phase, so poll until current_command appears.
+    let summary;
+    for (let attempt = 0; attempt < 100; attempt++) {
+      await sleep(50);
+      summary = getTaskSummary(task.task_id);
+      if (summary.current_command) break;
+    }
     if (summary.terminal || !summary.last_heartbeat_at || !summary.phase || !summary.current_command || summary.elapsed_ms < 0) {
       throw new Error(`Running summary incomplete: ${JSON.stringify(summary)}`);
     }
@@ -404,7 +410,7 @@ try {
 
   await test("verification failure produces failed_verification and structured evidence", async () => {
     const plan = savePlan({ title: "Verify failure", content: "Finish normally." });
-    const task = createTask({
+    const task = await createTask({
       plan_id: plan.plan_id,
       agent: "writer",
       repo_path: "repo",
@@ -434,7 +440,7 @@ try {
 
   await test("out-of-scope workspace changes fail the task and generate a rollback plan", async () => {
     const plan = savePlan({ title: "Scope violation", content: "Do not leave the repository." });
-    const task = createTask({
+    const task = await createTask({
       plan_id: plan.plan_id,
       agent: "scopebreaker",
       repo_path: "repo",
@@ -505,7 +511,7 @@ try {
     reloadConfig(cfg2);
 
     const plan = savePlan({ title: "Noop with external dirty", content: "Do nothing." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo", verify_commands: ["node --check main.js"] });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "noop", repo_path: "repo", verify_commands: ["node --check main.js"] });
     const result = await runTask(task.task_id);
 
     if (!isDoneStatus(result.status)) {
@@ -590,7 +596,7 @@ try {
     reloadConfig(cfg2);
 
     const plan = savePlan({ title: "External dirty modifier", content: "Modify external tracked file." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "extmod", repo_path: "repo", verify_commands: ["node --check main.js"] });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "extmod", repo_path: "repo", verify_commands: ["node --check main.js"] });
     const result = await runTask(task.task_id);
 
     if (result.status !== "failed_scope_violation") {
@@ -675,7 +681,7 @@ try {
     reloadConfig(cfg2);
 
     const plan = savePlan({ title: "Clean external modifier", content: "Modify clean external tracked file." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "extmod", repo_path: "repo", verify_commands: ["node --check main.js"] });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "extmod", repo_path: "repo", verify_commands: ["node --check main.js"] });
     const result = await runTask(task.task_id);
 
     if (result.status !== "failed_scope_violation") {
@@ -752,7 +758,7 @@ try {
     reloadConfig(cfg2);
 
     const plan = savePlan({ title: "External rename", content: "Rename external tracked file." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "extrenamer", repo_path: "repo", verify_commands: ["node --check main.js"] });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "extrenamer", repo_path: "repo", verify_commands: ["node --check main.js"] });
     const result = await runTask(task.task_id);
 
     if (result.status !== "failed_scope_violation") {
@@ -794,7 +800,7 @@ try {
 
   await test("timeout terminates a long-running agent", async () => {
     const plan = savePlan({ title: "Timeout", content: "Wait." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 1 });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 1 });
     const started = Date.now();
     const result = await runTask(task.task_id);
     if (result.status !== "failed" || !result.error?.includes("timed out")) {
@@ -810,7 +816,7 @@ try {
 
   await test("cancel_task safely stops a running agent", async () => {
     const plan = savePlan({ title: "Cancel", content: "Wait." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
     const running = runTask(task.task_id);
     await waitForRunning(getTaskStatus, task.task_id);
     const request = cancelTask(task.task_id);
@@ -823,7 +829,7 @@ try {
 
   await test("kill_task immediately stops a running agent", async () => {
     const plan = savePlan({ title: "Kill", content: "Wait." });
-    const task = createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
+    const task = await createTask({ plan_id: plan.plan_id, agent: "slow", repo_path: "repo", timeout_seconds: 30 });
     const running = runTask(task.task_id);
     await waitForRunning(getTaskStatus, task.task_id);
     const request = killTask(task.task_id);

package/scripts/checks/mcp-manifest-check.js

@@ -105,6 +105,11 @@ try {
       throw new Error("get_task_summary schema must expose view and max_items");
     }
     const safeRequirements = {
+      run_task_loop: ["repo_path", "goal", "verify_commands", "direct_verify", "isolation_mode", "worktree_cleanup"],
+      recommend_agent_for_task: ["repo_path", "goal"],
+      get_task_lineage: ["lineage_id"],
+      export_task_evidence_pack: ["lineage_id"],
+      get_project_policy: ["repo_path"],
       safe_result: ["task_id"],
       safe_audit: ["task_id"],
       safe_test_summary: ["task_id"],
@@ -124,6 +129,7 @@ try {
       create_direct_session: ["repo_path"],
       apply_patch: ["session_id", "path", "expected_sha256", "operations"],
       run_verification: ["session_id", "command"],
+      run_direct_verification_bundle: ["session_id", "commands"],
       finalize_direct_session: ["session_id"],
       audit_session: ["session_id"],
       safe_direct_summary: ["session_id"],
@@ -200,6 +206,11 @@ try {
       health_check: ["detail"],
       list_tasks: ["repo_path", "active_only"],
       get_task_summary: ["view", "max_items"],
+      run_task_loop: ["repo_path", "goal", "verify_commands", "direct_verify", "isolation_mode", "worktree_cleanup"],
+      recommend_agent_for_task: ["repo_path", "goal"],
+      get_task_lineage: ["lineage_id"],
+      export_task_evidence_pack: ["lineage_id"],
+      get_project_policy: ["repo_path"],
       safe_result: ["task_id"],
       safe_audit: ["task_id"],
       safe_test_summary: ["task_id"],
@@ -208,6 +219,7 @@ try {
       create_direct_session: ["repo_path"],
       apply_patch: ["session_id", "path", "expected_sha256", "operations"],
       run_verification: ["session_id", "command"],
+      run_direct_verification_bundle: ["session_id", "commands"],
       finalize_direct_session: ["session_id"],
       audit_session: ["session_id"],
       safe_direct_summary: ["session_id"],

package/scripts/checks/mcp-smoke.js

@@ -117,12 +117,16 @@ try {
     "discard_worktree",
     "discover_tools",
     "explain_tool",
+    "export_goal_report",
     "export_handoff",
+    "export_task_evidence_pack",
     "finalize_direct_session",
     "get_diff",
     "get_plan",
+    "get_project_policy",
     "get_result",
     "get_result_json",
+    "get_task_lineage",
     "get_task_log_tail",
     "get_task_progress",
     "get_task_status",
@@ -130,6 +134,7 @@ try {
     "get_task_summary",
     "get_test_log",
     "health_check",
+    "import_speckit_tasks",
     "invoke_discovered_tool",
     "kill_task",
     "list_agents",
@@ -139,9 +144,16 @@ try {
     "merge_worktree",
     "read_goal",
     "read_workspace_file",
+    "recommend_agent_for_task",
     "reconcile_tasks",
     "reject_subgoal",
+    "release_check",
+    "release_cleanup",
+    "release_prepare",
+    "release_verify",
     "retry_task",
+    "run_direct_verification_bundle",
+    "run_task_loop",
     "run_verification",
     "safe_audit",
     "safe_audit_direct_session",
@@ -167,7 +179,7 @@ try {
   if (!tools._meta || typeof tools._meta.tool_manifest_sha256 !== "string" || tools._meta.tool_manifest_sha256.length !== 64) {
     throw new Error(`tools/list _meta missing manifest hash: ${JSON.stringify(tools._meta || null)}`);
   }
-  if (tools._meta.tool_profile !== "full" || tools._meta.tool_count !== 54) {
+  if (tools._meta.tool_profile !== "full" || tools._meta.tool_count !== 66) {
     throw new Error(`tools/list _meta profile/count mismatch: ${JSON.stringify(tools._meta)}`);
   }
   if (typeof tools._meta.schema_epoch !== "string" || typeof tools._meta.server_version !== "string") {
@@ -417,7 +429,7 @@ try {
   await disabledClient.close();
   ok("chatgpt_direct disabled exposes only health_check with diagnostic");
 
-  // 2. chatgpt_direct enabled: 13 tools + minimal create_direct_session
+  // 2. chatgpt_direct enabled: 14 tools + minimal create_direct_session
   const enabledConfigPath = join(tempRoot, "direct-enabled.json");
   const directRepo = join(workspaceRoot, "direct-fixture");
   mkdirSync(join(directRepo, "src"), { recursive: true });
@@ -473,6 +485,7 @@ try {
     "health_check",
     "list_workspace",
     "read_workspace_file",
+    "run_direct_verification_bundle",
     "run_verification",
     "safe_audit_direct_session",
     "safe_direct_summary",
@@ -483,8 +496,8 @@ try {
   if (JSON.stringify(enabledNames) !== JSON.stringify(expectedDirect)) {
     throw new Error(`chatgpt_direct enabled tools mismatch: ${enabledNames.join(", ")}`);
   }
-  if (enabledTools._meta.tool_count !== 13) {
-    throw new Error(`chatgpt_direct enabled tool_count should be 13, got ${enabledTools._meta.tool_count}`);
+  if (enabledTools._meta.tool_count !== 14) {
+    throw new Error(`chatgpt_direct enabled tool_count should be 14, got ${enabledTools._meta.tool_count}`);
   }
 
   // Minimal create_direct_session
@@ -497,6 +510,19 @@ try {
   if (!sessionResult.session_id || !sessionResult.session_id.startsWith("direct_")) {
     throw new Error(`create_direct_session failed: ${JSON.stringify(sessionResult)}`);
   }
+  const bundleResult = JSON.parse(
+    (await enabledClient.callTool({
+      name: "run_direct_verification_bundle",
+      arguments: { session_id: sessionResult.session_id, commands: ["npm test"], timeout_seconds: 30 },
+    })).content?.[0]?.text || "{}"
+  );
+  if (bundleResult.status !== "passed" || bundleResult.command_count !== 1 || bundleResult.passed_commands !== 1) {
+    throw new Error(`run_direct_verification_bundle failed: ${JSON.stringify(bundleResult)}`);
+  }
+  const bundleText = JSON.stringify(bundleResult).toLowerCase();
+  if (bundleText.includes("stdout_tail") || bundleText.includes("stderr_tail") || bundleText.includes("verification.log")) {
+    throw new Error("run_direct_verification_bundle leaked log tail fields");
+  }
 
   const enabledHealth = JSON.parse(
     (await enabledClient.callTool({ name: "health_check", arguments: {} })).content?.[0]?.text || "{}"
@@ -504,12 +530,12 @@ try {
   if (enabledHealth.direct_profile_enabled !== true) {
     throw new Error(`direct_profile_enabled should be true, got ${enabledHealth.direct_profile_enabled}`);
   }
-  if (enabledHealth.direct_tool_count !== 13) {
-    throw new Error(`direct_tool_count should be 13, got ${enabledHealth.direct_tool_count}`);
+  if (enabledHealth.direct_tool_count !== 14) {
+    throw new Error(`direct_tool_count should be 14, got ${enabledHealth.direct_tool_count}`);
   }
 
   await enabledClient.close();
-  ok("chatgpt_direct enabled exposes 13 tools and create_direct_session works");
+  ok("chatgpt_direct enabled exposes 14 tools and create_direct_session works");
 } catch (error) {
   fail("MCP smoke test", error);
 } finally {

package/scripts/checks/watcher-supervisor-smoke.js

@@ -105,7 +105,7 @@ function createFixture(name) {
     server_version: "0.6.0",
     schema_epoch: "2026-06-22-v6",
     tool_profile: "chatgpt_core",
-    tool_count: 21,
+    tool_count: 26,
     tool_names: [],
     tool_manifest_sha256: "a".repeat(64),
   });

package/scripts/generate-demo-gif.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+ROOT = Path(__file__).resolve().parents[1]
+OUT = ROOT / "docs" / "assets" / "patchwarden-oss-demo.gif"
+
+W, H = 1280, 720
+BG = (246, 248, 245)
+INK = (32, 39, 39)
+MUTED = (91, 101, 101)
+GREEN = (38, 124, 92)
+TEAL = (25, 112, 116)
+BLUE = (48, 92, 160)
+ORANGE = (183, 104, 36)
+RED = (165, 62, 62)
+LINE = (205, 214, 208)
+PANEL = (255, 255, 252)
+SHADOW = (218, 224, 219)
+TERMINAL = (27, 34, 34)
+TERMINAL_TEXT = (208, 230, 218)
+
+
+def font(size: int, bold: bool = False) -> ImageFont.FreeTypeFont:
+    candidates = [
+        "C:/Windows/Fonts/segoeuib.ttf" if bold else "C:/Windows/Fonts/segoeui.ttf",
+        "C:/Windows/Fonts/arialbd.ttf" if bold else "C:/Windows/Fonts/arial.ttf",
+    ]
+    for candidate in candidates:
+        try:
+            return ImageFont.truetype(candidate, size)
+        except OSError:
+            pass
+    return ImageFont.load_default()
+
+
+F_TITLE = font(44, True)
+F_H2 = font(27, True)
+F_BODY = font(22)
+F_SMALL = font(18)
+F_MONO = font(19)
+F_MONO_SMALL = font(16)
+
+
+def rounded(draw: ImageDraw.ImageDraw, box, fill, outline=None, radius=18, width=2):
+    x0, y0, x1, y1 = box
+    draw.rounded_rectangle((x0 + 6, y0 + 8, x1 + 6, y1 + 8), radius, fill=SHADOW)
+    draw.rounded_rectangle(box, radius, fill=fill, outline=outline or LINE, width=width)
+
+
+def label(draw: ImageDraw.ImageDraw, xy, text, fill=INK, fnt=F_BODY, anchor=None):
+    draw.text(xy, text, fill=fill, font=fnt, anchor=anchor)
+
+
+def pill(draw: ImageDraw.ImageDraw, xy, text, fill, text_fill=(255, 255, 255)):
+    x, y = xy
+    bbox = draw.textbbox((0, 0), text, font=F_SMALL)
+    pad_x = 14
+    pad_y = 7
+    w = bbox[2] - bbox[0] + pad_x * 2
+    h = bbox[3] - bbox[1] + pad_y * 2
+    draw.rounded_rectangle((x, y, x + w, y + h), h // 2, fill=fill)
+    draw.text((x + pad_x, y + pad_y - 1), text, fill=text_fill, font=F_SMALL)
+
+
+def wrap(draw: ImageDraw.ImageDraw, text: str, width: int, fnt=F_BODY) -> list[str]:
+    lines: list[str] = []
+    current = ""
+    for word in text.split():
+        test = f"{current} {word}".strip()
+        if draw.textlength(test, font=fnt) <= width:
+            current = test
+        else:
+            if current:
+                lines.append(current)
+            current = word
+    if current:
+        lines.append(current)
+    return lines
+
+
+def draw_panel_text(draw, box, title, body, accent):
+    x0, y0, x1, y1 = box
+    rounded(draw, box, PANEL, LINE)
+    draw.rectangle((x0, y0, x0 + 8, y1), fill=accent)
+    label(draw, (x0 + 28, y0 + 24), title, fnt=F_H2)
+    y = y0 + 68
+    for line in wrap(draw, body, x1 - x0 - 56, F_BODY):
+        label(draw, (x0 + 28, y), line, fill=MUTED, fnt=F_BODY)
+        y += 30
+
+
+def draw_terminal(draw, box, lines):
+    rounded(draw, box, TERMINAL, (66, 78, 78), radius=16)
+    x0, y0, x1, _ = box
+    draw.ellipse((x0 + 20, y0 + 18, x0 + 32, y0 + 30), fill=(236, 98, 86))
+    draw.ellipse((x0 + 42, y0 + 18, x0 + 54, y0 + 30), fill=(241, 190, 76))
+    draw.ellipse((x0 + 64, y0 + 18, x0 + 76, y0 + 30), fill=(99, 198, 103))
+    y = y0 + 54
+    for line, color in lines:
+        label(draw, (x0 + 24, y), line, fill=color, fnt=F_MONO_SMALL)
+        y += 25
+        if y > box[3] - 24:
+            break
+
+
+def draw_progress(draw, active: int):
+    steps = [
+        ("Plan", BLUE),
+        ("Guard", TEAL),
+        ("Execute", ORANGE),
+        ("Evidence", GREEN),
+        ("Review", GREEN),
+    ]
+    start_x = 165
+    y = 650
+    gap = 235
+    for i, (name, color) in enumerate(steps):
+        x = start_x + gap * i
+        if i > 0:
+            line_color = color if i <= active else LINE
+            draw.line((x - gap + 48, y, x - 48, y), fill=line_color, width=5)
+        fill = color if i <= active else (226, 232, 228)
+        text = (255, 255, 255) if i <= active else MUTED
+        draw.ellipse((x - 28, y - 28, x + 28, y + 28), fill=fill)
+        label(draw, (x, y - 1), str(i + 1), fill=text, fnt=F_H2, anchor="mm")
+        label(draw, (x, y + 44), name, fill=INK if i <= active else MUTED, fnt=F_SMALL, anchor="mm")
+
+
+def base(title: str, subtitle: str, active: int) -> tuple[Image.Image, ImageDraw.ImageDraw]:
+    img = Image.new("RGB", (W, H), BG)
+    draw = ImageDraw.Draw(img)
+    label(draw, (64, 42), title, fnt=F_TITLE)
+    label(draw, (66, 96), subtitle, fill=MUTED, fnt=F_BODY)
+    pill(draw, (1040, 48), "privacy-safe demo", GREEN)
+    draw_progress(draw, active)
+    return img, draw
+
+
+def frame_intro():
+    img, draw = base(
+        "PatchWarden OSS Demo",
+        "A safe MCP task loop for ChatGPT, Codex, OpenCode, and local maintainers.",
+        0,
+    )
+    draw_panel_text(
+        draw,
+        (90, 170, 1190, 530),
+        "What this GIF shows",
+        "A model plans work, PatchWarden turns it into a bounded task, a registered local agent executes it, and the maintainer reviews redacted evidence before accepting anything.",
+        GREEN,
+    )
+    pill(draw, (130, 420), "no API keys", BLUE)
+    pill(draw, (280, 420), "no real account names", TEAL)
+    pill(draw, (520, 420), "no unrestricted shell", ORANGE)
+    pill(draw, (770, 420), "no auto-publish", RED)
+    return img
+
+
+def frame_plan():
+    img, draw = base(
+        "1. Model creates a bounded plan",
+        "The upstream client asks for a small maintainer task, not a raw shell command.",
+        0,
+    )
+    draw_panel_text(
+        draw,
+        (70, 160, 590, 520),
+        "ChatGPT / Codex",
+        "Goal: update docs for a small OSS workflow. Verify with npm.cmd test. Return summary, diff, and evidence only.",
+        BLUE,
+    )
+    draw_panel_text(
+        draw,
+        (690, 160, 1210, 520),
+        "PatchWarden MCP",
+        "Receives structured task input with repo_path, agent, template, and allowlisted verification commands.",
+        TEAL,
+    )
+    draw.line((600, 340, 680, 340), fill=BLUE, width=6)
+    draw.polygon([(680, 340), (660, 328), (660, 352)], fill=BLUE)
+    return img
+
+
+def frame_guard():
+    img, draw = base(
+        "2. PatchWarden checks the safety boundary",
+        "Local policy decides what can run and where files may change.",
+        1,
+    )
+    draw_panel_text(
+        draw,
+        (70, 160, 1210, 330),
+        "Guardrails",
+        "repo_path must stay under workspaceRoot. Agent launch commands come from trusted config. Verification commands must exactly match allowedTestCommands.",
+        TEAL,
+    )
+    draw_panel_text(
+        draw,
+        (70, 380, 580, 540),
+        "Blocked by default",
+        ".env, tokens, SSH keys, cookies, credential files, out-of-workspace writes, and arbitrary shell.",
+        RED,
+    )
+    draw_panel_text(
+        draw,
+        (700, 380, 1210, 540),
+        "Allowed",
+        "A pre-registered local agent can work on the requested repository and produce auditable evidence.",
+        GREEN,
+    )
+    return img
+
+
+def frame_execute():
+    img, draw = base(
+        "3. Watcher launches the registered agent",
+        "The task is executed locally while PatchWarden records status and scope evidence.",
+        2,
+    )
+    draw_terminal(
+        draw,
+        (80, 160, 1200, 540),
+        [
+            ("> patchwarden watcher", TERMINAL_TEXT),
+            ("queued task_20260709_demo", (156, 205, 255)),
+            ("repo_path: demo-oss-project", TERMINAL_TEXT),
+            ("agent: opencode (registered)", TERMINAL_TEXT),
+            ("verify: npm.cmd test (allowlisted)", TERMINAL_TEXT),
+            ("scope: inside workspaceRoot", (142, 222, 170)),
+            ("status: running -> done", (142, 222, 170)),
+        ],
+    )
+    return img
+
+
+def frame_evidence():
+    img, draw = base(
+        "4. Evidence is written for review",
+        "The maintainer can inspect safe summaries before opening deeper logs or diffs.",
+        3,
+    )
+    draw_panel_text(
+        draw,
+        (80, 150, 410, 540),
+        "result.json",
+        "status, warnings, changed-file groups, and recommended next actions.",
+        GREEN,
+    )
+    draw_panel_text(
+        draw,
+        (475, 150, 805, 540),
+        "diff.patch",
+        "Git diff evidence when available, kept separate from the model plan.",
+        BLUE,
+    )
+    draw_panel_text(
+        draw,
+        (870, 150, 1200, 540),
+        "verify.json",
+        "Exact commands, exit codes, and verification status.",
+        ORANGE,
+    )
+    return img
+
+
+def frame_review():
+    img, draw = base(
+        "5. Maintainer accepts, fixes, or rejects",
+        "PatchWarden supports review. It does not silently push, publish, or restart services.",
+        4,
+    )
+    draw_panel_text(
+        draw,
+        (80, 160, 1200, 520),
+        "OSS maintainer handoff",
+        "Use safe_result, safe_audit, safe_test_summary, and evidence packs to decide the next step. Release actions still require separate human confirmation and GitHub/npm verification.",
+        GREEN,
+    )
+    pill(draw, (165, 410), "reviewable", GREEN)
+    pill(draw, (360, 410), "redacted", TEAL)
+    pill(draw, (525, 410), "bounded", BLUE)
+    pill(draw, (680, 410), "confirmation-gated", ORANGE)
+    return img
+
+
+def hold(frames, image, count):
+    for _ in range(count):
+        frames.append(image.copy())
+
+
+def main():
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    scenes = [
+        frame_intro(),
+        frame_plan(),
+        frame_guard(),
+        frame_execute(),
+        frame_evidence(),
+        frame_review(),
+    ]
+    frames: list[Image.Image] = []
+    for scene in scenes:
+        hold(frames, scene, 12)
+    frames[0].save(
+        OUT,
+        save_all=True,
+        append_images=frames[1:],
+        duration=120,
+        loop=0,
+        optimize=True,
+    )
+    print(OUT)
+
+
+if __name__ == "__main__":
+    main()