feat(fn-20.4): approvals dashboard + worker API protocol

Adds the UI + worker-side half of the approval system that consumes T3's
backend CLI and daemon endpoints.

- frontend/src/pages/Approvals.tsx: new dashboard page rendering pending
  approvals as cards with kind/task badges, expandable JSON payloads,
  and Approve/Reject buttons (with reason textarea). SWR polls every 5s
  and WS subscribes to ApprovalCreated/ApprovalResolved events.
- App.tsx, Layout.tsx: register /approvals route + nav entry with
  keyboard shortcut "V".
- types.ts: add ApprovalCreated/ApprovalResolved to FlowEventType.
- agents/worker.md: migrate "Need file access:" and "Need mutation:"
  to use flowctl approval create + approval show --wait --timeout 600
  as the preferred path; keep SendMessage summary-prefix as documented
  fallback for no-daemon/non-Teams scenarios.
- skills/flow-code-work/SKILL.md: document the two-tier protocol.
- scripts/teams_e2e_test.sh: add approval-API scenario (create, list,
  approve, show --wait, reject).

Task: fn-20-abf-borrowed-enhancements-archetypes.4

Author: z23cc

agents/worker.md

@@ -78,16 +78,40 @@ SendMessage(to: "coordinator", summary: "Blocked: <TASK_ID>",
 ```
 
 4. **File access request** — when you need a file not in OWNED_FILES:
-```
-SendMessage(to: "coordinator", summary: "Need file access: <file>",
-  message: "Access request for <TASK_ID>.\nFile: <path>\nReason: <why needed>\nCurrent owner: <task-id>")
-```
+
+   **Preferred path (daemon running):** use the approval API instead of SendMessage:
+   ```bash
+   APPROVAL_ID=$($FLOWCTL approval create --task <TASK_ID> --kind file_access \
+     --payload '{"files": ["<path>"], "reason": "<why needed>", "current_owner": "<task-id>"}' \
+     --json | jq -r .id)
+   $FLOWCTL approval show "$APPROVAL_ID" --wait --timeout 600 --json
+   ```
+   - On `status: approved` → proceed with the edit.
+   - On `status: rejected` → emit a `Blocked:` summary and skip the file.
+   - On timeout → note in completion evidence and continue with alternative approach.
+
+   **Fallback (no daemon, non-Teams mode):**
+   ```
+   SendMessage(to: "coordinator", summary: "Need file access: <file>",
+     message: "Access request for <TASK_ID>.\nFile: <path>\nReason: <why needed>\nCurrent owner: <task-id>")
+   ```
+   Wait for "Access granted:" or "Access denied:" summary-prefix response.
 
 5. **Mutation request** — when the task should be split, skipped, or dependencies changed:
-```
-SendMessage(to: "coordinator", summary: "Need mutation: <TASK_ID>",
-  message: "Task <TASK_ID> needs structural change.\nType: split | skip | dep_change\nDetails: <why the mutation is needed>\nSuggested action: <split into N parts | skip because X | remove dep on Y>")
-```
+
+   **Preferred path (daemon running):**
+   ```bash
+   APPROVAL_ID=$($FLOWCTL approval create --task <TASK_ID> --kind mutation \
+     --payload '{"type": "split|skip|dep_change", "details": "<why>", "action": "<suggested>"}' \
+     --json | jq -r .id)
+   $FLOWCTL approval show "$APPROVAL_ID" --wait --timeout 600 --json
+   ```
+
+   **Fallback (no daemon, non-Teams mode):**
+   ```
+   SendMessage(to: "coordinator", summary: "Need mutation: <TASK_ID>",
+     message: "Task <TASK_ID> needs structural change.\nType: split | skip | dep_change\nDetails: <why the mutation is needed>\nSuggested action: <split into N parts | skip because X | remove dep on Y>")
+   ```
 
 **Team Lead → Worker messages (you receive these):**
 
@@ -269,14 +293,21 @@ If more files remain (tests, docs, config), repeat: parallel read → checkpoint
 1. Is this file in `OWNED_FILES`?
    - **YES** → proceed with the edit
    - **NO** → **STOP. Do NOT edit the file.** Instead:
-     1. Send a file access request:
+     1. Request approval via the API (preferred when daemon is running):
+        ```bash
+        APPROVAL_ID=$($FLOWCTL approval create --task <TASK_ID> --kind file_access \
+          --payload '{"files": ["<path>"], "reason": "<why>", "current_owner": "<task-id>"}' \
+          --json | jq -r .id)
+        $FLOWCTL approval show "$APPROVAL_ID" --wait --timeout 600 --json
+        ```
+        Fallback (no daemon): send a SendMessage summary-prefix request:
         ```
         SendMessage(to: "coordinator", summary: "Need file access: <file>",
           message: "Access request for <TASK_ID>.\nFile: <path>\nReason: <why needed>\nCurrent owner: <task-id if known>")
         ```
-     2. Wait for "Access granted:" or "Access denied:" response
-     3. If no response within 60s, skip the file and note it in your completion evidence
-     4. On "Access denied:", find an alternative approach that stays within your owned files
+     2. Wait for `status: approved`/`rejected` (API) or "Access granted:"/"Access denied:" (fallback)
+     3. If timeout, skip the file and note it in your completion evidence
+     4. On rejected/denied, find an alternative approach that stays within your owned files
 
 **This is not optional.** Do not bypass this check even if you believe the lock system will catch violations. Self-enforcement is the primary guard; hooks are the backup.
 <!-- /section:team -->
@@ -332,7 +363,7 @@ Continue until guard passes. There is no retry limit — this is not a retry loo
 - Return early with `SPEC_CONFLICT` status (see Phase 2 spec conflict protocol)
 - In Teams mode, send a `Spec conflict` message to the coordinator
 
-**Teams mode constraint:** When `TEAM_MODE=true`, only fix files in `OWNED_FILES`. If the failure is caused by a file you don't own, send a `Need file access` message and wait for a response. If access is denied or times out, note the issue in your completion summary.
+**Teams mode constraint:** When `TEAM_MODE=true`, only fix files in `OWNED_FILES`. If the failure is caused by a file you don't own, request access via `flowctl approval create --kind file_access` + `approval show --wait` (or fallback `Need file access:` SendMessage), then wait for a resolution. If access is rejected or times out, note the issue in your completion summary.
 
 ### Step 2: Review your own diff
 ```bash
@@ -592,8 +623,8 @@ If you catch yourself thinking any of these, stop and follow the correct action:
 
 | Thought | Reality |
 |---------|---------|
-| "I need to edit a file not in OWNED_FILES" | Send "Need file access:" and WAIT. Do not edit. |
-| "The coordinator isn't responding" | Wait 60s. If no response, skip the file and note it in evidence. |
+| "I need to edit a file not in OWNED_FILES" | Create a `flowctl approval create --kind file_access` (or fallback "Need file access:" message) and WAIT. Do not edit. |
+| "The coordinator isn't responding" | `approval show --wait --timeout 600` blocks ≤10min; on fallback path wait 60s. If timeout, skip the file and note it in evidence. |
 | "I'll just edit it, the lock check will catch it" | Don't rely on hooks. Self-enforce OWNED_FILES. |
 | "TEAM_MODE doesn't matter for this task" | If TEAM_MODE=true is set, follow the protocol. Always. |
 | "It's a small edit, nobody will notice" | Ownership violations break parallel safety for everyone. |

frontend/src/App.tsx

@@ -7,6 +7,7 @@ import EpicDetail from "./pages/EpicDetail";
 import DagView from "./pages/DagView";
 import Agents from "./pages/Agents";
 import Memory from "./pages/Memory";
+import Approvals from "./pages/Approvals";
 import Settings from "./pages/Settings";
 import Replay from "./pages/Replay";
 import CommandPalette from "./components/CommandPalette";
@@ -44,6 +45,7 @@ export default function App() {
           <Route path="/dag/:id" element={<DagView />} />
           <Route path="/agents" element={<Agents />} />
           <Route path="/memory" element={<Memory />} />
+          <Route path="/approvals" element={<Approvals />} />
           <Route path="/settings" element={<Settings />} />
           <Route path="/replay/:id" element={<Replay />} />
         </Route>

frontend/src/components/Layout.tsx

@@ -4,6 +4,7 @@ import {
   LayoutDashboard,
   Bot,
   Brain,
+  CheckSquare,
   Settings,
   ChevronRight,
   Menu,
@@ -23,6 +24,7 @@ const navItems = [
   { to: "/", label: "Dashboard", icon: LayoutDashboard, shortcut: "D" },
   { to: "/agents", label: "Agents", icon: Bot, shortcut: "A" },
   { to: "/memory", label: "Memory", icon: Brain, shortcut: "M" },
+  { to: "/approvals", label: "Approvals", icon: CheckSquare, shortcut: "V" },
   { to: "/settings", label: "Settings", icon: Settings, shortcut: "S" },
 ];
 
@@ -125,6 +127,10 @@ export default function Layout() {
           e.preventDefault();
           navigate("/memory");
           break;
+        case "v":
+          e.preventDefault();
+          navigate("/approvals");
+          break;
         case "s":
           e.preventDefault();
           navigate("/settings");

frontend/src/lib/types.ts

@@ -28,19 +28,33 @@ export interface EpicUpdated {
 // Heartbeat has no data (content is null in serde)
 export type Heartbeat = null;
 
+export interface ApprovalCreated {
+  id: string;
+  task_id: string;
+}
+
+export interface ApprovalResolved {
+  id: string;
+  status: string;
+}
+
 export type FlowEventType =
   | "TaskStatusChanged"
   | "DagMutated"
   | "AgentLog"
   | "EpicUpdated"
-  | "Heartbeat";
+  | "Heartbeat"
+  | "ApprovalCreated"
+  | "ApprovalResolved";
 
 export type FlowEventData =
   | TaskStatusChanged
   | DagMutated
   | AgentLog
   | EpicUpdated
-  | Heartbeat;
+  | Heartbeat
+  | ApprovalCreated
+  | ApprovalResolved;
 
 /** Envelope sent over WebSocket: TimestampedEvent from Rust */
 export interface TimestampedEvent {

frontend/src/pages/Approvals.tsx

@@ -0,0 +1,218 @@
+import { useEffect, useState } from "react";
+import useSWR from "swr";
+import { toast } from "sonner";
+import { swrFetcher, apiPost, ApiRequestError } from "../lib/api";
+import { connectEvents } from "../lib/ws";
+
+interface Approval {
+  id: string;
+  task_id: string;
+  kind: "file_access" | "mutation" | "generic";
+  payload: unknown;
+  status: "pending" | "approved" | "rejected";
+  created_at: number;
+  resolved_at: number | null;
+  resolver: string | null;
+  reason: string | null;
+}
+
+function kindBadge(kind: string): { color: string; label: string } {
+  switch (kind) {
+    case "file_access":
+      return { color: "bg-info/20 text-info", label: "File access" };
+    case "mutation":
+      return { color: "bg-purple-500/20 text-purple-400", label: "Mutation" };
+    case "generic":
+      return { color: "bg-bg-tertiary text-text-secondary", label: "Generic" };
+    default:
+      return { color: "bg-bg-tertiary text-text-muted", label: kind };
+  }
+}
+
+function formatTimestamp(epochSeconds: number): string {
+  return new Date(epochSeconds * 1000).toLocaleString();
+}
+
+export default function Approvals() {
+  const { data, error, isLoading, mutate } = useSWR<Approval[]>(
+    "/approvals?status=pending",
+    swrFetcher,
+    { refreshInterval: 5000 },
+  );
+
+  const [rejectingId, setRejectingId] = useState<string | null>(null);
+  const [rejectReason, setRejectReason] = useState("");
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [busyId, setBusyId] = useState<string | null>(null);
+
+  useEffect(() => {
+    const conn = connectEvents();
+    const refresh = () => {
+      mutate();
+    };
+    conn.on("ApprovalCreated", refresh);
+    conn.on("ApprovalResolved", refresh);
+    return () => conn.close();
+  }, [mutate]);
+
+  const approvals = data ?? [];
+
+  async function handleApprove(id: string) {
+    setBusyId(id);
+    try {
+      await apiPost(`/approvals/${id}/approve`, {});
+      toast.success(`Approved ${id}`);
+      mutate();
+    } catch (e) {
+      const msg =
+        e instanceof ApiRequestError ? e.serverMessage : String(e);
+      toast.error(`Approve failed: ${msg}`);
+    } finally {
+      setBusyId(null);
+    }
+  }
+
+  async function handleReject(id: string) {
+    setBusyId(id);
+    try {
+      await apiPost(`/approvals/${id}/reject`, {
+        reason: rejectReason || null,
+      });
+      toast.success(`Rejected ${id}`);
+      setRejectingId(null);
+      setRejectReason("");
+      mutate();
+    } catch (e) {
+      const msg =
+        e instanceof ApiRequestError ? e.serverMessage : String(e);
+      toast.error(`Reject failed: ${msg}`);
+    } finally {
+      setBusyId(null);
+    }
+  }
+
+  return (
+    <div className="flex flex-col h-full gap-4">
+      <h1 className="text-2xl font-bold">Approvals</h1>
+
+      {isLoading && <p className="text-text-muted text-sm">Loading...</p>}
+      {error && (
+        <p className="text-error text-sm">Failed to load approvals.</p>
+      )}
+
+      {!isLoading && approvals.length === 0 && (
+        <div className="flex-1 flex flex-col items-center justify-center gap-3 text-center">
+          <div className="text-4xl opacity-40">OK</div>
+          <p className="text-text-primary text-sm font-medium">
+            No pending approvals
+          </p>
+          <p className="text-text-muted text-xs max-w-md">
+            Workers will request approval here when they need access to files
+            outside their owned set or want to mutate the task DAG.
+          </p>
+        </div>
+      )}
+
+      <div className="flex-1 overflow-auto space-y-3">
+        {approvals.map((approval) => {
+          const badge = kindBadge(approval.kind);
+          const isExpanded = expandedId === approval.id;
+          const isRejecting = rejectingId === approval.id;
+          const isBusy = busyId === approval.id;
+          return (
+            <div
+              key={approval.id}
+              className="rounded-md border border-border bg-bg-secondary p-4 space-y-3"
+            >
+              <div className="flex items-center gap-2 flex-wrap">
+                <span
+                  className={`px-2 py-0.5 rounded text-xs font-medium ${badge.color}`}
+                >
+                  {badge.label}
+                </span>
+                <span className="px-2 py-0.5 rounded text-xs font-medium bg-accent/20 text-accent">
+                  {approval.task_id}
+                </span>
+                <span className="text-xs text-text-muted ml-auto">
+                  {formatTimestamp(approval.created_at)}
+                </span>
+              </div>
+
+              <div>
+                <button
+                  type="button"
+                  onClick={() =>
+                    setExpandedId(isExpanded ? null : approval.id)
+                  }
+                  className="text-xs text-text-muted hover:text-text-primary"
+                >
+                  {isExpanded ? "Hide" : "Show"} payload
+                </button>
+                {isExpanded && (
+                  <pre className="mt-2 p-2 rounded bg-bg-tertiary text-xs text-text-primary overflow-auto">
+                    {JSON.stringify(approval.payload, null, 2)}
+                  </pre>
+                )}
+              </div>
+
+              {isRejecting ? (
+                <div className="space-y-2">
+                  <textarea
+                    value={rejectReason}
+                    onChange={(e) => setRejectReason(e.target.value)}
+                    placeholder="Reason (optional)..."
+                    className="w-full px-3 py-2 rounded-md bg-bg-tertiary border border-border text-sm text-text-primary placeholder:text-text-muted focus:outline-none focus:border-border-accent"
+                    rows={2}
+                  />
+                  <div className="flex gap-2">
+                    <button
+                      type="button"
+                      disabled={isBusy}
+                      onClick={() => handleReject(approval.id)}
+                      className="px-3 py-1.5 rounded-md bg-error/20 text-error text-sm font-medium hover:bg-error/30 disabled:opacity-50"
+                    >
+                      Confirm reject
+                    </button>
+                    <button
+                      type="button"
+                      disabled={isBusy}
+                      onClick={() => {
+                        setRejectingId(null);
+                        setRejectReason("");
+                      }}
+                      className="px-3 py-1.5 rounded-md bg-bg-tertiary text-text-secondary text-sm hover:bg-bg-tertiary/70 disabled:opacity-50"
+                    >
+                      Cancel
+                    </button>
+                  </div>
+                </div>
+              ) : (
+                <div className="flex gap-2">
+                  <button
+                    type="button"
+                    disabled={isBusy}
+                    onClick={() => handleApprove(approval.id)}
+                    className="px-3 py-1.5 rounded-md bg-success/20 text-success text-sm font-medium hover:bg-success/30 disabled:opacity-50"
+                  >
+                    Approve
+                  </button>
+                  <button
+                    type="button"
+                    disabled={isBusy}
+                    onClick={() => {
+                      setRejectingId(approval.id);
+                      setRejectReason("");
+                    }}
+                    className="px-3 py-1.5 rounded-md bg-error/20 text-error text-sm font-medium hover:bg-error/30 disabled:opacity-50"
+                  >
+                    Reject
+                  </button>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}