From 9fb5b6d48d2c5aef7d956355e5149059c49b3830 Mon Sep 17 00:00:00 2001
From: GautamTalksDev <developwith.gt@gmail.com>
Date: Sun, 30 Aug 2026 02:05:39 -0400
Subject: [PATCH 1/3] feat: add guided demo recording flow

Automate the paced scan, human CI approval gate, execution results, and verified audit-ledger finish while keeping the controls isolated to demo and replay modes.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/web/src/App.tsx                          |  33 ++
 apps/web/src/api/client.ts                    |  88 ++++-
 apps/web/src/api/types.ts                     |  20 +
 apps/web/src/components/ApprovalCardView.tsx  |  29 +-
 apps/web/src/components/ApprovalQueue.tsx     |  36 +-
 apps/web/src/components/GuidedDemoPanel.tsx   | 220 +++++++++++
 apps/web/src/hooks/useGuidedDemo.ts           | 349 ++++++++++++++++++
 apps/web/src/hooks/useScanSession.ts          |  18 +-
 docs/CONNECTORS.md                            |  13 +-
 docs/EXECUTE.md                               |  62 +++-
 docs/UI.md                                    |  11 +
 fixtures/test-org/manifest.json               |   2 +-
 .../connectors/src/github.contract.test.ts    |  57 ++-
 packages/connectors/src/github/connector.ts   | 193 ++++++++--
 packages/connectors/src/github/tools.ts       |   3 +
 .../connectors/src/revoke.contract.test.ts    |  55 +++
 packages/core/src/grant.ts                    |  35 +-
 packages/core/src/identity/run.ts             |  15 +-
 scripts/demo.ts                               |   1 +
 scripts/test-org/live.ts                      | 103 ++++--
 20 files changed, 1195 insertions(+), 148 deletions(-)
 create mode 100644 apps/web/src/components/GuidedDemoPanel.tsx
 create mode 100644 apps/web/src/hooks/useGuidedDemo.ts

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 1ac3f23..7a2ce6c 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -1,11 +1,24 @@
 import { AgentActivity } from "./components/AgentActivity.js";
 import { ApprovalQueue } from "./components/ApprovalQueue.js";
 import { ErrorBanner } from "./components/ErrorBanner.js";
+import { GuidedDemoPanel } from "./components/GuidedDemoPanel.js";
 import { useScanSession } from "./hooks/useScanSession.js";
+import { useGuidedDemo } from "./hooks/useGuidedDemo.js";
 import { classifyClientError, recoveryFor, type ProductErrorKind } from "./lib/errors.js";
 
 export function App() {
   const session = useScanSession();
+  const demoMode =
+    import.meta.env.VITE_DEMO_MODE === "1" ||
+    import.meta.env.VITE_SCAN_DRIVER === "replay" ||
+    session.activity.driver === "replay";
+  const guided = useGuidedDemo({
+    activity: session.activity,
+    cards: session.cards,
+    beginScan: session.beginScan,
+    updateCard: session.updateCard,
+    cancelScan: session.cancelScan,
+  });
   const costs = session.activity.costs;
   const capped = session.activity.status === "cost_capped";
   const partial = session.activity.status === "partial";
@@ -44,6 +57,15 @@ export function App() {
             : "no active scan"}
           {session.activity.driver ? ` · ${session.activity.driver}` : ""}
         </div>
+        {demoMode && !guided.active ? (
+          <button
+            type="button"
+            onClick={() => void guided.run()}
+            className="border border-[var(--color-ink)] bg-[var(--color-ink)] px-3 py-1.5 text-[12px] font-semibold text-white hover:bg-[var(--color-ink-2)]"
+          >
+            Run guided demo
+          </button>
+        ) : null}
       </header>
 
       {showBanner && message ? (
@@ -72,9 +94,20 @@ export function App() {
           scanId={session.activity.scanId}
           scanStatus={session.activity.status}
           onCardUpdated={session.updateCard}
+          guidedMode={demoMode && guided.state.phase !== "idle"}
+          guidedCardId={guided.state.targetCardId}
         />
       </div>
 
+      {demoMode && guided.state.phase !== "idle" ? (
+        <GuidedDemoPanel
+          state={guided.state}
+          cards={session.cards}
+          onContinue={guided.continueGate}
+          onStop={guided.stop}
+        />
+      ) : null}
+
       <footer className="flex shrink-0 flex-wrap items-center justify-between gap-3 border-t border-[var(--color-line)] bg-[var(--color-panel)] px-5 py-2 font-mono text-[11px] text-[var(--color-mute)]">
         <div className="flex flex-wrap gap-x-4 gap-y-1">
           <span>
diff --git a/apps/web/src/api/client.ts b/apps/web/src/api/client.ts
index 807f188..8cdf2a7 100644
--- a/apps/web/src/api/client.ts
+++ b/apps/web/src/api/client.ts
@@ -1,7 +1,23 @@
-import type { ApiCard, ExecuteResult, ScanCostSnapshot, ScanProgressEvent } from "./types.js";
+import type {
+  ApiCard,
+  AuditRecord,
+  AuditVerification,
+  ExecuteResult,
+  ScanCostSnapshot,
+  ScanProgressEvent,
+} from "./types.js";
 
 const base = (import.meta.env.VITE_API_BASE_URL as string | undefined)?.replace(/\/$/, "") ?? "";
 
+export interface ExecuteResponse {
+  scanId: string;
+  dryRun: boolean;
+  executed: number;
+  failed: number;
+  skipped: number;
+  results: ExecuteResult[];
+}
+
 async function request<T>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(`${base}${path}`, {
     ...init,
@@ -75,20 +91,74 @@ export async function executeScan(
   scanId: string,
   approvedBy = "operator",
   dryRun = true,
-): Promise<{
-  scanId: string;
-  dryRun: boolean;
-  executed: number;
-  failed: number;
-  skipped: number;
-  results: ExecuteResult[];
-}> {
+): Promise<ExecuteResponse> {
   return request(`/scans/${scanId}/execute`, {
     method: "POST",
     body: JSON.stringify({ approvedBy, dryRun }),
   });
 }
 
+export async function executeScanStream(
+  scanId: string,
+  approvedBy = "operator",
+  dryRun = true,
+  signal?: AbortSignal,
+  onEvent?: (event: ScanProgressEvent) => void | Promise<void>,
+): Promise<ExecuteResponse> {
+  const res = await fetch(`${base}/scans/${scanId}/execute`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "text/event-stream",
+    },
+    body: JSON.stringify({ approvedBy, dryRun }),
+    signal,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${res.status} /scans/${scanId}/execute: ${text}`);
+  }
+  if (!res.body) throw new Error("Execute stream returned no body.");
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let summary: ExecuteResponse | null = null;
+
+  const consume = async (chunk: string) => {
+    buffer += chunk;
+    const frames = buffer.split(/\r?\n\r?\n/);
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const eventName = frame.match(/^event: (.+)$/m)?.[1] ?? "message";
+      const data = frame.match(/^data: (.+)$/m)?.[1];
+      if (!data) continue;
+      const event = JSON.parse(data) as ScanProgressEvent;
+      if (eventName === "execute.done") {
+        summary = event as unknown as ExecuteResponse;
+      } else {
+        await onEvent?.({ ...event, type: event.type || eventName });
+      }
+    }
+  };
+
+  while (true) {
+    const next = await reader.read();
+    if (next.done) break;
+    await consume(decoder.decode(next.value, { stream: true }));
+  }
+  await consume(decoder.decode());
+  if (!summary) throw new Error("Execute stream ended before execute.done.");
+  return summary;
+}
+
+export async function fetchAudit(): Promise<{
+  records: AuditRecord[];
+  verification: AuditVerification;
+}> {
+  return request("/audit");
+}
+
 /**
  * Subscribe to scan SSE. Returns an unsubscribe function.
  * Replays snapshot history, then live events.
diff --git a/apps/web/src/api/types.ts b/apps/web/src/api/types.ts
index 374b1a6..c4cfb69 100644
--- a/apps/web/src/api/types.ts
+++ b/apps/web/src/api/types.ts
@@ -90,3 +90,23 @@ export interface ExecuteResult {
     params: Record<string, unknown>;
   };
 }
+
+export interface AuditRecord {
+  id: string;
+  cardId: string;
+  action: string;
+  approvedBy: string;
+  approvedAt: string;
+  executedAt: string;
+  result: "success" | "failed" | "partial";
+  error?: string | null;
+  prevHash: string;
+  hash: string;
+}
+
+export interface AuditVerification {
+  ok: boolean;
+  count: number;
+  index?: number;
+  reason?: string;
+}
diff --git a/apps/web/src/components/ApprovalCardView.tsx b/apps/web/src/components/ApprovalCardView.tsx
index fb29e74..098e739 100644
--- a/apps/web/src/components/ApprovalCardView.tsx
+++ b/apps/web/src/components/ApprovalCardView.tsx
@@ -20,6 +20,7 @@ export function ApprovalCardView({
   onApprove,
   onHold,
   onReject,
+  actionsDisabled = false,
 }: {
   card: ApiCard;
   selected: boolean;
@@ -30,6 +31,7 @@ export function ApprovalCardView({
   onApprove: () => void;
   onHold: () => void;
   onReject: () => void;
+  actionsDisabled?: boolean;
 }) {
   const stale = staleness(card.grant.lastUsedAt);
   const pending = card.status === "pending";
@@ -37,6 +39,7 @@ export function ApprovalCardView({
 
   return (
     <article
+      id={`approval-card-${card.id}`}
       role="listitem"
       tabIndex={0}
       onFocus={onFocus}
@@ -52,7 +55,7 @@ export function ApprovalCardView({
           <input
             type="checkbox"
             checked={checked}
-            disabled={!pending}
+            disabled={!pending || actionsDisabled}
             onChange={onToggleCheck}
             className="h-3.5 w-3.5 accent-[var(--color-ink)]"
             aria-label={`Select ${who}`}
@@ -63,9 +66,7 @@ export function ApprovalCardView({
           <div className="flex flex-wrap items-start justify-between gap-x-3 gap-y-1">
             <div className="min-w-0">
               <div className="flex flex-wrap items-center gap-2">
-                <h3 className="truncate text-[14px] font-semibold tracking-tight">
-                  {who}
-                </h3>
+                <h3 className="truncate text-[14px] font-semibold tracking-tight">{who}</h3>
                 <ConfidenceBadge confidence={card.attribution.confidence} />
                 {card.irreversible ? (
                   <span className="border border-[var(--color-irrev)] bg-[var(--color-irrev-soft)] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-[0.06em] text-[var(--color-irrev)]">
@@ -115,7 +116,10 @@ export function ApprovalCardView({
           </div>
 
           <div className="mt-2.5 flex flex-wrap gap-x-4 gap-y-1 text-[12px]">
-            <Meta label="Created" value={formatWhen(card.grant.createdAt ?? card.grant.discoveredAt)} />
+            <Meta
+              label="Created"
+              value={formatWhen(card.grant.createdAt ?? card.grant.discoveredAt)}
+            />
             <Meta
               label="Last used"
               value={
@@ -155,16 +159,13 @@ export function ApprovalCardView({
 
           <ul className="mt-2 space-y-0.5 border-t border-[var(--color-line)] pt-2">
             {card.risk.reasons.map((r) => (
-              <li
-                key={r}
-                className="font-mono text-[11px] leading-snug text-[var(--color-mute)]"
-              >
+              <li key={r} className="font-mono text-[11px] leading-snug text-[var(--color-mute)]">
                 {r}
               </li>
             ))}
           </ul>
 
-          {pending ? (
+          {pending && !actionsDisabled ? (
             <div className="mt-3 flex flex-wrap gap-1.5">
               <ActionButton onClick={onApprove} variant="primary">
                 Approve
@@ -191,13 +192,7 @@ function ConfidenceBadge({ confidence }: { confidence: string }) {
   );
 }
 
-function Meta({
-  label,
-  value,
-}: {
-  label: string;
-  value: ReactNode;
-}) {
+function Meta({ label, value }: { label: string; value: ReactNode }) {
   return (
     <div>
       <span className="text-[10px] uppercase tracking-[0.06em] text-[var(--color-faint)]">
diff --git a/apps/web/src/components/ApprovalQueue.tsx b/apps/web/src/components/ApprovalQueue.tsx
index f49a59f..7193fd4 100644
--- a/apps/web/src/components/ApprovalQueue.tsx
+++ b/apps/web/src/components/ApprovalQueue.tsx
@@ -13,12 +13,16 @@ export function ApprovalQueue({
   scanId,
   scanStatus,
   onCardUpdated,
+  guidedMode = false,
+  guidedCardId = null,
 }: {
   cards: ApiCard[];
   systemIds: string[];
   scanId: string | null;
   scanStatus: string;
   onCardUpdated: (card: ApiCard) => void;
+  guidedMode?: boolean;
+  guidedCardId?: string | null;
 }) {
   const ordered = useMemo(() => sortCards(cards), [cards]);
   const unattributed = ordered.filter(isUnattributed);
@@ -37,6 +41,14 @@ export function ApprovalQueue({
     setFocusIndex(0);
   }, [scanId]);
 
+  useEffect(() => {
+    if (!guidedCardId) return;
+    document.getElementById(`approval-card-${guidedCardId}`)?.scrollIntoView({
+      behavior: "smooth",
+      block: "center",
+    });
+  }, [guidedCardId]);
+
   useEffect(() => {
     function onKey(e: KeyboardEvent) {
       const tag = (e.target as HTMLElement | null)?.tagName;
@@ -142,7 +154,7 @@ export function ApprovalQueue({
             </p>
           </div>
           <div className="flex flex-wrap items-center gap-2">
-            {pendingCount > 0 && checked.size === 0 ? (
+            {!guidedMode && pendingCount > 0 && checked.size === 0 ? (
               <button
                 type="button"
                 className="border border-[var(--color-line-strong)] bg-white px-2.5 py-1.5 text-[12px] font-medium text-[var(--color-mute)] hover:border-[var(--color-ink)] hover:text-[var(--color-ink)]"
@@ -155,7 +167,7 @@ export function ApprovalQueue({
                 Select all pending
               </button>
             ) : null}
-            {checked.size > 0 ? (
+            {!guidedMode && checked.size > 0 ? (
               <>
                 <span className="font-mono text-[12px] text-[var(--color-mute)]">
                   {checked.size} selected
@@ -183,14 +195,16 @@ export function ApprovalQueue({
                 </button>
               </>
             ) : null}
-            <button
-              type="button"
-              disabled={!scanId || approved.length === 0}
-              onClick={() => setExecuteOpen(true)}
-              className="border border-[var(--color-ink)] bg-white px-3 py-1.5 text-[12px] font-semibold text-[var(--color-ink)] hover:bg-[var(--color-ink)] hover:text-white disabled:opacity-40"
-            >
-              Execute approved ({approved.length})
-            </button>
+            {!guidedMode ? (
+              <button
+                type="button"
+                disabled={!scanId || approved.length === 0}
+                onClick={() => setExecuteOpen(true)}
+                className="border border-[var(--color-ink)] bg-white px-3 py-1.5 text-[12px] font-semibold text-[var(--color-ink)] hover:bg-[var(--color-ink)] hover:text-white disabled:opacity-40"
+              >
+                Execute approved ({approved.length})
+              </button>
+            ) : null}
           </div>
         </div>
       </header>
@@ -259,6 +273,7 @@ export function ApprovalQueue({
                       onApprove={() => void decide(card, "approve")}
                       onHold={() => setHoldTarget(card)}
                       onReject={() => void decide(card, "reject")}
+                      actionsDisabled={guidedMode}
                     />
                   ))}
                 </div>
@@ -292,6 +307,7 @@ export function ApprovalQueue({
                       onApprove={() => void decide(card, "approve")}
                       onHold={() => setHoldTarget(card)}
                       onReject={() => void decide(card, "reject")}
+                      actionsDisabled={guidedMode}
                     />
                   ))}
                 </div>
diff --git a/apps/web/src/components/GuidedDemoPanel.tsx b/apps/web/src/components/GuidedDemoPanel.tsx
new file mode 100644
index 0000000..97e71ac
--- /dev/null
+++ b/apps/web/src/components/GuidedDemoPanel.tsx
@@ -0,0 +1,220 @@
+import type { ApiCard, AuditRecord, AuditVerification, ExecuteResult } from "../api/types.js";
+import { actionVerb, principalLabel, systemLabel } from "../lib/format.js";
+import type { GuidedDemoPhase, GuidedDemoState } from "../hooks/useGuidedDemo.js";
+
+export function GuidedDemoPanel({
+  state,
+  cards,
+  onContinue,
+  onStop,
+}: {
+  state: GuidedDemoState;
+  cards: ApiCard[];
+  onContinue: () => void;
+  onStop: () => void;
+}) {
+  const target = state.targetCardId
+    ? cards.find((card) => card.id === state.targetCardId)
+    : undefined;
+  const active =
+    state.phase !== "idle" &&
+    state.phase !== "stopped" &&
+    state.phase !== "error" &&
+    state.phase !== "ledger";
+
+  return (
+    <aside
+      className="fixed right-5 top-[4.25rem] z-30 w-[min(390px,calc(100vw-2.5rem))] border border-[var(--color-ink)] bg-white shadow-lg"
+      aria-live="polite"
+      aria-label="Guided demo status"
+    >
+      <header className="flex items-start justify-between gap-3 border-b border-[var(--color-line)] bg-[var(--color-ink)] px-4 py-3 text-white">
+        <div>
+          <div className="font-mono text-[10px] uppercase tracking-[0.12em] text-white/65">
+            Guided demo
+          </div>
+          <h2 className="mt-0.5 text-[14px] font-semibold">{titleForPhase(state.phase)}</h2>
+        </div>
+        {active ? (
+          <button
+            type="button"
+            onClick={onStop}
+            className="border border-white/50 px-2.5 py-1 text-[11px] font-semibold text-white hover:bg-white hover:text-[var(--color-ink)]"
+          >
+            Stop
+          </button>
+        ) : null}
+      </header>
+
+      <div className="max-h-[calc(100vh-8rem)] overflow-y-auto px-4 py-3">
+        {state.message ? (
+          <p className="text-[12px] leading-relaxed text-[var(--color-ink-2)]">{state.message}</p>
+        ) : null}
+
+        {state.phase === "waiting" && target ? (
+          <div className="mt-3 border-2 border-[var(--color-hold)] bg-[#fffaf0] px-3 py-3">
+            <div className="font-mono text-[10px] font-semibold uppercase tracking-[0.1em] text-[var(--color-hold)]">
+              Human approval gate
+            </div>
+            <h3 className="mt-1 text-[14px] font-semibold">{principalLabel(target)}</h3>
+            <p className="mt-0.5 text-[12px] text-[var(--color-mute)]">
+              {systemLabel(target.grant.system)} · {target.grant.resource.displayName} ·{" "}
+              {actionVerb(target.proposedAction.kind)}
+            </p>
+            <p className="mt-2 text-[12px] leading-relaxed text-[var(--color-ink-2)]">
+              {target.protectedReason ?? "Protected CI infrastructure."}
+            </p>
+            <p className="mt-2 font-mono text-[11px] text-[var(--color-hold)]">
+              The run is paused. Do not decide this card from the queue.
+            </p>
+            <button
+              type="button"
+              onClick={onContinue}
+              className="mt-3 w-full border border-[var(--color-ink)] bg-[var(--color-ink)] px-3 py-2 text-[12px] font-semibold text-white hover:bg-[var(--color-ink-2)]"
+            >
+              Continue
+            </button>
+          </div>
+        ) : null}
+
+        {state.error ? (
+          <div className="mt-3 border border-[var(--color-irrev)] bg-[var(--color-irrev-soft)] px-3 py-2 text-[12px] text-[var(--color-irrev)]">
+            {state.error}
+          </div>
+        ) : null}
+
+        {state.phase === "executing" || state.phase === "verifying" ? (
+          <ResultList results={state.results} cards={cards} />
+        ) : null}
+
+        {state.phase === "ledger" ? (
+          <Ledger
+            records={state.auditRecords}
+            verification={state.verification}
+            cards={cards}
+            results={state.results}
+          />
+        ) : null}
+      </div>
+    </aside>
+  );
+}
+
+function titleForPhase(phase: GuidedDemoPhase): string {
+  switch (phase) {
+    case "scanning":
+      return "Scanning systems";
+    case "headline":
+      return "Queue ready";
+    case "approving":
+      return "Approving safe cards";
+    case "waiting":
+      return "Approval required";
+    case "holding":
+      return "Recording human hold";
+    case "executing":
+      return "Executing approved cards";
+    case "verifying":
+      return "Verifying ledger";
+    case "ledger":
+      return "Audit ledger";
+    case "stopped":
+      return "Take stopped";
+    case "error":
+      return "Take failed";
+    default:
+      return "Ready";
+  }
+}
+
+function ResultList({ results, cards }: { results: ExecuteResult[]; cards: ApiCard[] }) {
+  if (results.length === 0) {
+    return (
+      <p className="mt-3 font-mono text-[11px] text-[var(--color-faint)]">Waiting for results…</p>
+    );
+  }
+  return (
+    <div className="mt-3">
+      <div className="font-mono text-[10px] uppercase tracking-[0.1em] text-[var(--color-faint)]">
+        Per-card results
+      </div>
+      <ul className="mt-1.5 space-y-1">
+        {results.map((result) => {
+          const card = cards.find((candidate) => candidate.id === result.cardId);
+          return (
+            <li
+              key={result.cardId}
+              className="flex items-start justify-between gap-2 border-b border-[var(--color-line)] py-1.5 text-[11px]"
+            >
+              <span className="min-w-0 truncate text-[var(--color-mute)]">
+                {card ? principalLabel(card) : `${result.cardId.slice(0, 10)}…`}
+              </span>
+              <span
+                className={
+                  result.status === "failed"
+                    ? "shrink-0 text-[var(--color-irrev)]"
+                    : "shrink-0 text-[var(--color-ok)]"
+                }
+              >
+                {result.status}
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+function Ledger({
+  records,
+  verification,
+  cards,
+  results,
+}: {
+  records: AuditRecord[];
+  verification: AuditVerification | null;
+  cards: ApiCard[];
+  results: ExecuteResult[];
+}) {
+  const passing = verification?.ok === true;
+  return (
+    <div className="mt-3">
+      <div
+        className={`border px-3 py-2 ${
+          passing
+            ? "border-[var(--color-ok)] bg-[#f2fbf4] text-[var(--color-ok)]"
+            : "border-[var(--color-irrev)] bg-[var(--color-irrev-soft)] text-[var(--color-irrev)]"
+        }`}
+      >
+        <div className="text-[12px] font-semibold">
+          {passing ? "Hash verification passing" : "Hash verification failed"}
+        </div>
+        <div className="mt-0.5 font-mono text-[10px]">
+          {verification?.count ?? records.length} ledger record
+          {(verification?.count ?? records.length) === 1 ? "" : "s"}
+        </div>
+      </div>
+      <ResultList results={results} cards={cards} />
+      <ol className="mt-3 space-y-1 border-t border-[var(--color-line)] pt-2">
+        {records.slice(-8).map((record) => (
+          <li
+            key={record.id}
+            className="flex items-center justify-between gap-2 font-mono text-[10px]"
+          >
+            <span className="truncate text-[var(--color-mute)]">
+              {record.action} · {record.cardId.slice(0, 10)}…
+            </span>
+            <span
+              className={
+                record.result === "failed" ? "text-[var(--color-irrev)]" : "text-[var(--color-ok)]"
+              }
+            >
+              {record.result}
+            </span>
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}
diff --git a/apps/web/src/hooks/useGuidedDemo.ts b/apps/web/src/hooks/useGuidedDemo.ts
new file mode 100644
index 0000000..5929253
--- /dev/null
+++ b/apps/web/src/hooks/useGuidedDemo.ts
@@ -0,0 +1,349 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { executeScanStream, fetchAudit, postDecision } from "../api/client.js";
+import type { ApiCard, AuditRecord, AuditVerification, ExecuteResult } from "../api/types.js";
+import type { AgentActivityState } from "../api/types.js";
+import { sortCards } from "../lib/format.js";
+
+export type GuidedDemoPhase =
+  | "idle"
+  | "scanning"
+  | "headline"
+  | "approving"
+  | "waiting"
+  | "holding"
+  | "executing"
+  | "verifying"
+  | "ledger"
+  | "stopped"
+  | "error";
+
+export interface GuidedDemoState {
+  phase: GuidedDemoPhase;
+  scanId: string | null;
+  targetCardId: string | null;
+  message: string | null;
+  error: string | null;
+  results: ExecuteResult[];
+  auditRecords: AuditRecord[];
+  verification: AuditVerification | null;
+}
+
+const DEFAULT_MIN_RUNTIME_MS = 90_000;
+const HEADLINE_HOLD_MS = 3_000;
+const DECISION_GAP_MS = 1_500;
+const HOLD_CONFIRMATION_MS = 1_000;
+const EXECUTION_RESULT_HOLD_MS = 15_000;
+const POLL_MS = 100;
+
+function configuredMinRuntime(): number {
+  const value = Number(import.meta.env.VITE_GUIDED_DEMO_MIN_RUNTIME_MS);
+  return Number.isFinite(value) && value >= 0 ? value : DEFAULT_MIN_RUNTIME_MS;
+}
+
+function wait(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason ?? new Error("Guided demo stopped"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new Error("Guided demo stopped"));
+      },
+      { once: true },
+    );
+  });
+}
+
+function waitFor(predicate: () => boolean, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (signal.aborted) {
+        reject(signal.reason ?? new Error("Guided demo stopped"));
+        return;
+      }
+      if (predicate()) {
+        resolve();
+        return;
+      }
+      setTimeout(check, POLL_MS);
+    };
+    check();
+  });
+}
+
+function isCiProtectedCard(card: ApiCard): boolean {
+  return (
+    card.protected === true &&
+    (card.proposedAction.kind === "flag_only" ||
+      card.grant.evidence.some((e) => /CI|do.not.revoke/i.test(e.claim)))
+  );
+}
+
+function initialState(): GuidedDemoState {
+  return {
+    phase: "idle",
+    scanId: null,
+    targetCardId: null,
+    message: null,
+    error: null,
+    results: [],
+    auditRecords: [],
+    verification: null,
+  };
+}
+
+export function useGuidedDemo({
+  activity,
+  cards,
+  beginScan,
+  updateCard,
+  cancelScan,
+}: {
+  activity: AgentActivityState;
+  cards: ApiCard[];
+  beginScan: (person: string) => Promise<string | null>;
+  updateCard: (card: ApiCard) => void;
+  cancelScan: () => void;
+}) {
+  const [state, setState] = useState<GuidedDemoState>(initialState);
+  const activityRef = useRef(activity);
+  const cardsRef = useRef(cards);
+  const runIdRef = useRef(0);
+  const controllerRef = useRef<AbortController | null>(null);
+  const gateResolverRef = useRef<(() => void) | null>(null);
+
+  activityRef.current = activity;
+  cardsRef.current = cards;
+
+  const stop = useCallback(() => {
+    runIdRef.current += 1;
+    controllerRef.current?.abort();
+    controllerRef.current = null;
+    gateResolverRef.current?.();
+    gateResolverRef.current = null;
+    cancelScan();
+    setState((previous) => ({
+      ...previous,
+      phase: "stopped",
+      message: "Guided demo stopped. Start it again for another take.",
+    }));
+  }, [cancelScan]);
+
+  useEffect(() => {
+    return () => {
+      runIdRef.current += 1;
+      controllerRef.current?.abort();
+      gateResolverRef.current?.();
+    };
+  }, []);
+
+  const continueGate = useCallback(() => {
+    if (state.phase !== "waiting") return;
+    gateResolverRef.current?.();
+    gateResolverRef.current = null;
+  }, [state.phase]);
+
+  const run = useCallback(async () => {
+    if (
+      state.phase !== "idle" &&
+      state.phase !== "stopped" &&
+      state.phase !== "error" &&
+      state.phase !== "ledger"
+    ) {
+      return;
+    }
+
+    const runId = runIdRef.current + 1;
+    runIdRef.current = runId;
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    const startedAt = Date.now();
+    let pausedAt: number | null = null;
+    let pausedMs = 0;
+
+    const current = () => runIdRef.current === runId && !controller.signal.aborted;
+    const update = (patch: Partial<GuidedDemoState>) => {
+      if (current()) setState((previous) => ({ ...previous, ...patch }));
+    };
+
+    setState({
+      ...initialState(),
+      phase: "scanning",
+      message: "Starting the five-system scan…",
+    });
+
+    try {
+      const scanId = await beginScan("Ada Lovelace");
+      if (!current()) return;
+      if (!scanId) {
+        throw new Error(activityRef.current.error ?? "The guided scan could not start.");
+      }
+      update({ scanId, message: "Subagents are scanning across five systems…" });
+
+      await waitFor(
+        () =>
+          activityRef.current.scanId === scanId &&
+          (activityRef.current.status === "completed" ||
+            activityRef.current.status === "partial" ||
+            activityRef.current.status === "failed"),
+        controller.signal,
+      );
+      if (activityRef.current.status !== "completed") {
+        throw new Error(activityRef.current.error ?? "The guided scan did not complete.");
+      }
+      await waitFor(() => cardsRef.current.length > 0, controller.signal);
+
+      update({
+        phase: "headline",
+        message: "Scan complete. Hold on the summary so it can be read.",
+      });
+      await wait(HEADLINE_HOLD_MS, controller.signal);
+
+      const ordered = sortCards(cardsRef.current);
+      const safeCards = ordered.filter(
+        (card) =>
+          card.status === "pending" &&
+          card.protected !== true &&
+          card.proposedAction.kind !== "flag_only",
+      );
+      const ciCard =
+        ordered.find(isCiProtectedCard) ?? ordered.find((card) => card.protected === true);
+      if (!ciCard) {
+        throw new Error("The guided demo requires a protected CI card.");
+      }
+
+      for (let index = 0; index < safeCards.length; index += 1) {
+        const card = safeCards[index]!;
+        update({
+          phase: "approving",
+          targetCardId: card.id,
+          message: `Approving safe card ${index + 1} of ${safeCards.length}…`,
+        });
+        const result = await postDecision(card.id, {
+          decision: "approve",
+          by: "guided-demo",
+        });
+        updateCard(result.card);
+        if (index < safeCards.length - 1) {
+          await wait(DECISION_GAP_MS, controller.signal);
+        }
+      }
+
+      update({
+        phase: "waiting",
+        targetCardId: ciCard.id,
+        message: "Human approval gate — the protected CI card is waiting.",
+      });
+      pausedAt = Date.now();
+      await new Promise<void>((resolve, reject) => {
+        if (controller.signal.aborted) {
+          reject(controller.signal.reason ?? new Error("Guided demo stopped"));
+          return;
+        }
+        gateResolverRef.current = resolve;
+        controller.signal.addEventListener(
+          "abort",
+          () => reject(controller.signal.reason ?? new Error("Guided demo stopped")),
+          { once: true },
+        );
+      });
+      if (pausedAt !== null) {
+        pausedMs += Date.now() - pausedAt;
+        pausedAt = null;
+      }
+
+      update({
+        phase: "holding",
+        message: "Recording the human decision: belongs to CI, flag the owner.",
+      });
+      const held = await postDecision(ciCard.id, {
+        decision: "hold",
+        note: "belongs to CI, flag the owner",
+        by: "guided-demo",
+      });
+      updateCard(held.card);
+      await wait(HOLD_CONFIRMATION_MS, controller.signal);
+
+      update({
+        phase: "executing",
+        targetCardId: null,
+        message: "Executing approved cards and recording each result…",
+      });
+      const streamResults: ExecuteResult[] = [];
+      const execution = await executeScanStream(
+        scanId,
+        "guided-demo",
+        true,
+        controller.signal,
+        async (event) => {
+          if (event.type !== "execute.card" || event.phase !== "after") return;
+          const status =
+            event.result === "success"
+              ? "success"
+              : event.result === "failed"
+                ? "failed"
+                : "dry_run";
+          const result: ExecuteResult = {
+            cardId: String(event.cardId),
+            status,
+            ...(event.error ? { error: String(event.error) } : {}),
+            ...(event.detail ? { detail: String(event.detail) } : {}),
+          };
+          streamResults.push(result);
+          update({
+            results: [...streamResults],
+          });
+          await wait(EXECUTION_RESULT_HOLD_MS, controller.signal);
+        },
+      );
+      update({ results: execution.results });
+
+      const remaining = Math.max(0, configuredMinRuntime() - (Date.now() - startedAt - pausedMs));
+      if (remaining > 0) {
+        update({
+          phase: "verifying",
+          message: "Holding the verification view for the recording…",
+        });
+        await wait(remaining, controller.signal);
+      }
+
+      update({ phase: "verifying", message: "Verifying the append-only audit chain…" });
+      const audit = await fetchAudit();
+      update({
+        phase: "ledger",
+        message: "Audit ledger · hash verification complete",
+        auditRecords: audit.records,
+        verification: audit.verification,
+      });
+    } catch (err) {
+      if (controller.signal.aborted || runIdRef.current !== runId) return;
+      setState((previous) => ({
+        ...previous,
+        phase: "error",
+        error: err instanceof Error ? err.message : String(err),
+        message: "Guided demo stopped with an error.",
+      }));
+    } finally {
+      if (controllerRef.current === controller) controllerRef.current = null;
+    }
+  }, [beginScan, state.phase, updateCard]);
+
+  const active =
+    state.phase !== "idle" &&
+    state.phase !== "stopped" &&
+    state.phase !== "error" &&
+    state.phase !== "ledger";
+
+  return {
+    state,
+    active,
+    run,
+    stop,
+    continueGate,
+  };
+}
diff --git a/apps/web/src/hooks/useScanSession.ts b/apps/web/src/hooks/useScanSession.ts
index 94154d6..894f0c0 100644
--- a/apps/web/src/hooks/useScanSession.ts
+++ b/apps/web/src/hooks/useScanSession.ts
@@ -554,14 +554,14 @@ export function useScanSession() {
     }
   }
 
-  async function beginScan(person: string) {
+  async function beginScan(person: string): Promise<string | null> {
     const startToken = scanStartCoordinator.begin();
     refreshAbortRef.current?.abort();
     refreshAbortRef.current = null;
     dispatch({ type: "scan_starting", person });
     try {
       const started = await startScan({ person });
-      if (!scanStartCoordinator.canCommit(startToken)) return;
+      if (!scanStartCoordinator.canCommit(startToken)) return null;
       dispatch({
         type: "scan_started",
         scanId: started.scanId,
@@ -585,16 +585,18 @@ export function useScanSession() {
         },
       });
       if (!scanStartCoordinator.commit(startToken, started.scanId, unsubscribe)) {
-        return;
+        return null;
       }
       // Initial poll in case events already finished
       void refreshCards(started.scanId);
+      return started.scanId;
     } catch (err) {
-      if (!scanStartCoordinator.canCommit(startToken)) return;
+      if (!scanStartCoordinator.canCommit(startToken)) return null;
       dispatch({
         type: "scan_error",
         error: err instanceof Error ? err.message : String(err),
       });
+      return null;
     }
   }
 
@@ -606,11 +608,19 @@ export function useScanSession() {
     dispatch({ type: "dismiss_error" });
   }
 
+  function cancelScan() {
+    scanStartCoordinator.cancel();
+    refreshAbortRef.current?.abort();
+    refreshAbortRef.current = null;
+    dispatch({ type: "reset" });
+  }
+
   return {
     ...state,
     beginScan,
     refreshCards,
     updateCard,
     dismissError,
+    cancelScan,
   };
 }
diff --git a/docs/CONNECTORS.md b/docs/CONNECTORS.md
index 254e2ec..8e4605f 100644
--- a/docs/CONNECTORS.md
+++ b/docs/CONNECTORS.md
@@ -4,10 +4,10 @@ Keyring inventories **through TrueForge-configured MCP servers**, not through Oc
 
 ## Servers
 
-| TrueForge name | Catalog / setup | Purpose |
-| --- | --- | --- |
-| `github` | Shipped catalog → [https://api.githubcopilot.com/mcp/](https://api.githubcopilot.com/mcp/) (header auth PAT) | Org repos, collaborators, teams, commits (emails), optional deploy keys / PAT insights |
-| `google_workspace` | **Custom** remote MCP URL in Settings → Connectors | Directory users/groups + Drive shares outside the org |
+| TrueForge name     | Catalog / setup                                                                                              | Purpose                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `github`           | Shipped catalog → [https://api.githubcopilot.com/mcp/](https://api.githubcopilot.com/mcp/) (header auth PAT) | Org repos, collaborators, teams, commits (emails), optional deploy keys / PAT insights |
+| `google_workspace` | **Custom** remote MCP URL in Settings → Connectors                                                           | Directory users/groups + Drive shares outside the org                                  |
 
 Register both under **TrueForge → Settings → Connectors** before live inventory. See [MCP servers](https://trueforge.dev/mcp-servers).
 
@@ -27,13 +27,14 @@ Your Google MCP must expose (names matter):
 
 From the official GitHub MCP: `search_repositories`, `list_repository_collaborators`, `get_teams`, `get_team_members`, `list_commits`.
 
-Mutating (execute path): `remove_repository_collaborator`, `remove_team_member`, optional `delete_deploy_key` (permanent).
+Mutating (execute path): `remove_repository_collaborator`, `delete_repository_invitation`, `remove_team_member`, optional `delete_deploy_key` (permanent). Pending invitations use `delete_repository_invitation`, not collaborator removal.
 
-Optional inventory (fixture MCP implements; live skips if missing): `list_deploy_keys`, `list_org_pat_insights`.
+Optional inventory (fixture MCP implements; live skips if missing): `list_repository_invitations`, `list_deploy_keys`, `list_org_pat_insights`. A live MCP that does not expose invitations can still inventory active collaborators, but cannot discover pending invitations.
 
 ## Revoke + dry-run
 
 See [EXECUTE.md](./EXECUTE.md). Product execute and MCP `revoke_grant` route through the same connectors. `KEYRING_REVOKE_BACKEND=live` + MCP URLs required for real GitHub/Google mutations. Dry-run default prevents accidental revoke.
+
 ## Local / CI (fixtures)
 
 ```bash
diff --git a/docs/EXECUTE.md b/docs/EXECUTE.md
index 4771ec2..2959492 100644
--- a/docs/EXECUTE.md
+++ b/docs/EXECUTE.md
@@ -4,14 +4,60 @@ Real revocation for GitHub and Google Workspace, gated behind harness / product
 
 ## Safety defaults
 
-| Knob | Default | Meaning |
-| --- | --- | --- |
-| `KEYRING_EXECUTE_DRY_RUN` | `1` (ON) | Walk the full execute path; write before/after AuditRecords; **no mutating APIs** |
-| `KEYRING_REVOKE_BACKEND` | `fixture` | Use FixtureConnector + fixture MCP. Set `live` for GitHub/Google MCP |
-| Body `dryRun` | follows env | `POST /scans/:id/execute` `{ dryRun: false }` required for live mutation |
+| Knob                      | Default     | Meaning                                                                           |
+| ------------------------- | ----------- | --------------------------------------------------------------------------------- |
+| `KEYRING_EXECUTE_DRY_RUN` | `1` (ON)    | Walk the full execute path; write before/after AuditRecords; **no mutating APIs** |
+| `KEYRING_REVOKE_BACKEND`  | `fixture`   | Use FixtureConnector + fixture MCP. Set `live` for GitHub/Google MCP              |
+| Body `dryRun`             | follows env | `POST /scans/:id/execute` `{ dryRun: false }` required for live mutation          |
 
 A judge cloning the repo cannot revoke their own access without deliberately disabling dry-run.
 
+## Start the live path from a clean machine
+
+Install dependencies and start the database before starting Keyring:
+
+```bash
+pnpm install
+cp .env.example .env
+cd infra && docker compose up keyring-db -d
+cd ..
+export DATABASE_URL=postgresql://keyring:keyring@localhost:5432/keyring
+pnpm db:migrate
+```
+
+If no paid model provider is configured, start the zero-cost local model in a
+separate terminal and keep the stub flag set for registration:
+
+```bash
+KEYRING_ALLOW_STUB=1 pnpm stub:model
+```
+
+In another terminal, start the API:
+
+```bash
+export TRUEFORGE_BASE_URL=http://localhost:8791
+export KEYRING_ALLOW_STUB=1
+pnpm --filter @keyring/server dev
+```
+
+In a third terminal, start the UI:
+
+```bash
+pnpm --filter @keyring/web dev
+```
+
+After the API and TrueForge are reachable, register the agent:
+
+```bash
+pnpm register:agent
+```
+
+`pnpm register:agent` verifies that `keyring` appears in
+`GET /api/v1/agents`; a non-2xx response or a missing agent is a failed setup,
+not a successful registration. With `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`,
+use that provider instead and omit the stub command and
+`KEYRING_ALLOW_STUB=1`.
+
 ## Flow
 
 1. Human **approves** cards (intent only — no revoke).
@@ -27,10 +73,10 @@ A judge cloning the repo cannot revoke their own access without deliberately dis
 
 When a system supports restore, the connector returns an `undoHint` (exact permission removed + restore method + params). It is written into the after-audit `evidenceSnapshot`.
 
-| Badge | Meaning |
-| --- | --- |
+| Badge          | Meaning                                                    |
+| -------------- | ---------------------------------------------------------- |
 | **Restorable** | `revocable.reversible` — undo hint captured when available |
-| **Permanent** | irreversible (PAT, deploy key, …) |
+| **Permanent**  | irreversible (PAT, deploy key, …)                          |
 
 ## Live offboard (test org)
 
diff --git a/docs/UI.md b/docs/UI.md
index 5c12d56..6bf7637 100644
--- a/docs/UI.md
+++ b/docs/UI.md
@@ -20,6 +20,17 @@ Approve / Hold (note required) / Reject. Bulk select + bulk approve/reject — *
 ## Execute
 
 Separate step: summary of approved actions, Restorable vs Permanent callouts, **dry-run on by default**, explicit confirm, then per-card results (including undo hints when restorable). Approving never executes.
+
+## Guided demo
+
+The replay demo exposes **Run guided demo**. It starts a real replay scan, waits on
+the five-system SSE activity, approves safe cards individually, then pauses on the
+protected CI card. **Continue** records the human hold with the note
+`belongs to CI, flag the owner`, executes approved cards through the API, and ends
+on the verified audit ledger. **Stop** aborts the guided controller and resets the
+take; running it again creates a fresh scan. The controls are not rendered outside
+demo/replay mode.
+
 ## Run
 
 ```bash
diff --git a/fixtures/test-org/manifest.json b/fixtures/test-org/manifest.json
index b26dcfb..4d36fc1 100644
--- a/fixtures/test-org/manifest.json
+++ b/fixtures/test-org/manifest.json
@@ -1,6 +1,6 @@
 {
   "org": "keyring-test",
-  "generatedAt": "2026-08-24T23:32:20.871Z",
+  "generatedAt": "2026-08-30T05:06:37.999Z",
   "grantCount": 15,
   "peopleCount": 3,
   "surviveDemo": {
diff --git a/packages/connectors/src/github.contract.test.ts b/packages/connectors/src/github.contract.test.ts
index 8bdcd01..c06dc60 100644
--- a/packages/connectors/src/github.contract.test.ts
+++ b/packages/connectors/src/github.contract.test.ts
@@ -34,11 +34,9 @@ describe("GitHubConnector contract (MCP fixtures)", () => {
     }
 
     expect(grants.length).toBeGreaterThanOrEqual(4);
-    expect(
-      grants.every((g) =>
-        g.evidence.every((e) => e.source.startsWith("mcp:github/")),
-      ),
-    ).toBe(true);
+    expect(grants.every((g) => g.evidence.every((e) => e.source.startsWith("mcp:github/")))).toBe(
+      true,
+    );
 
     const byRepo = grants.filter((g) => g.resource.kind === "repo");
     const logins = byRepo.flatMap((g) =>
@@ -103,4 +101,53 @@ describe("GitHubConnector contract (MCP fixtures)", () => {
       expect(match, `missing fixture grant ${resourceId} / ${key}`).toBeDefined();
     }
   });
+
+  it("represents pending invitations separately from active collaborators", async () => {
+    const fixture = createFixtureMcpToolCaller();
+    const connector = createGitHubConnector({
+      org: "keyring-test",
+      discoveredAt: DISCOVERED_AT,
+    });
+    const grants = [];
+    const invitationCalls: string[] = [];
+    for await (const grant of connector.inventory({
+      credentials: { kind: "read", token: "t" },
+      mcp: {
+        async callTool(request) {
+          if (request.tool === "list_repository_invitations") {
+            invitationCalls.push(String(request.arguments?.repo));
+            return {
+              server: request.server,
+              tool: request.tool,
+              data:
+                request.arguments?.repo === "payments"
+                  ? [
+                      {
+                        id: 42,
+                        invitee: { login: "pending-user" },
+                        permissions: { push: true },
+                      },
+                    ]
+                  : [],
+            };
+          }
+          return fixture.callTool(request);
+        },
+      },
+    })) {
+      grants.push(grant);
+    }
+
+    expect(invitationCalls).toContain("payments");
+    const invitation = grants.find((grant) => grant.accessState === "pending_invitation");
+    expect(invitation).toMatchObject({
+      accessState: "pending_invitation",
+      resource: {
+        id: "keyring-test/payments/invitation:42",
+      },
+      revocable: {
+        method: "delete_repository_invitation",
+      },
+    });
+  });
 });
diff --git a/packages/connectors/src/github/connector.ts b/packages/connectors/src/github/connector.ts
index 93a8777..a96e67b 100644
--- a/packages/connectors/src/github/connector.ts
+++ b/packages/connectors/src/github/connector.ts
@@ -1,8 +1,4 @@
-import {
-  createGrant,
-  type Grant,
-  type Identifier,
-} from "@keyring/core";
+import { createGrant, type Grant, type Identifier } from "@keyring/core";
 
 import { asArray, asObject, callJson, paginatePages } from "../mcp/paginate.js";
 import { McpToolError, type McpToolCaller } from "../mcp/types.js";
@@ -13,11 +9,7 @@ import type {
   RevokeContext,
   RevokeResult,
 } from "../types.js";
-import {
-  GITHUB_MCP_SERVER,
-  GitHubMcpTools,
-  githubPermissionToCapability,
-} from "./tools.js";
+import { GITHUB_MCP_SERVER, GitHubMcpTools, githubPermissionToCapability } from "./tools.js";
 import {
   buildUndoHint,
   githubCapabilityToPermission,
@@ -79,8 +71,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
           );
           const body = asObject(result.data);
           const items = asArray(body, "items").map((r) => asObject(r));
-          const nextPage =
-            items.length === 100 ? page + 1 : undefined;
+          const nextPage = items.length === 100 ? page + 1 : undefined;
           return {
             items: items.map((r) => ({
               name: String(r.name ?? ""),
@@ -143,9 +134,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
             system: "github",
             principal: {
               kind: "human",
-              identifiers: [
-                { kind: "username", value: login, source: "github" },
-              ],
+              identifiers: [{ kind: "username", value: login, source: "github" }],
             },
             resource: {
               id: `${org}/team:${slug}`,
@@ -198,14 +187,10 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
             { signal: ctx.signal, maxPages: 5 },
           )) {
             const authorLogin = String(
-              asObject(commit.author).login ??
-                asObject(asObject(commit.commit).author).login ??
-                "",
+              asObject(commit.author).login ?? asObject(asObject(commit.commit).author).login ?? "",
             );
             const email = String(
-              asObject(asObject(commit.commit).author).email ??
-                asObject(commit.commit).email ??
-                "",
+              asObject(asObject(commit.commit).author).email ?? asObject(commit.commit).email ?? "",
             );
             if (authorLogin && email && !email.includes("noreply.github.com")) {
               const set = commitEmails.get(authorLogin) ?? new Set<string>();
@@ -288,10 +273,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
               evidence: [
                 {
                   claim: `GitHub collaborator ${login} has ${permission} on ${org}/${repoName} (affiliation=${affiliation})`,
-                  source: evidenceSource(
-                    server,
-                    GitHubMcpTools.listRepositoryCollaborators,
-                  ),
+                  source: evidenceSource(server, GitHubMcpTools.listRepositoryCollaborators),
                   confidence: "certain",
                   raw: collab,
                 },
@@ -300,6 +282,92 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
           }
         }
 
+        // --- Pending repository invitations ---
+        // GitHub returns 201 when PUT /collaborators creates an invitation.
+        // Invitations are not collaborators until accepted, so inventory them
+        // separately and retain the invitation id for the correct revoke API.
+        try {
+          for await (const invitation of paginatePages(
+            async (page) => {
+              const result = await callJson(
+                mcp,
+                server,
+                GitHubMcpTools.listRepositoryInvitations,
+                { owner, repo: repoName, page, perPage: 100 },
+                ctx.signal,
+              );
+              const body = asObject(result.data);
+              const invitations = (
+                asArray(body, "invitations").length
+                  ? asArray(body, "invitations")
+                  : asArray(body, "items").length
+                    ? asArray(body, "items")
+                    : asArray(result.data)
+              ).map(asObject);
+              return {
+                items: invitations,
+                nextPage:
+                  typeof body.nextPage === "number"
+                    ? body.nextPage
+                    : invitations.length === 100
+                      ? page + 1
+                      : undefined,
+              };
+            },
+            { signal: ctx.signal },
+          )) {
+            const invitationId = String(invitation.id ?? invitation.invitation_id ?? "");
+            if (!invitationId) continue;
+            const invitee = asObject(invitation.invitee);
+            const login = String(invitation.login ?? invitee.login ?? "");
+            const email = String(invitation.email ?? invitee.email ?? "");
+            const identifiers: Identifier[] = login
+              ? [{ kind: "username", value: login, source: "github" }]
+              : email
+                ? [{ kind: "personal_email", value: email, source: "github" }]
+                : [];
+            if (identifiers.length === 0) continue;
+            const permission = String(
+              invitation.role_name ??
+                invitation.permission ??
+                (asObject(invitation.permissions).admin ? "admin" : "pull"),
+            );
+            yield createGrant({
+              system: "github",
+              principal: { kind: "human", identifiers },
+              resource: {
+                id: `${org}/${repoName}/invitation:${invitationId}`,
+                displayName: repoName,
+                kind: "repo",
+              },
+              capability: githubPermissionToCapability(permission),
+              accessState: "pending_invitation",
+              discoveredAt,
+              createdAt: invitation.created_at
+                ? new Date(String(invitation.created_at))
+                : undefined,
+              revocable: {
+                possible: true,
+                reversible: true,
+                method: "delete_repository_invitation",
+              },
+              evidence: [
+                {
+                  claim: `GitHub pending invitation for ${login || email} on ${org}/${repoName} (permission=${permission})`,
+                  source: evidenceSource(server, GitHubMcpTools.listRepositoryInvitations),
+                  confidence: "certain",
+                  raw: invitation,
+                },
+              ],
+            });
+          }
+        } catch (error) {
+          // The shipped GitHub MCP may not expose invitations yet. Keep the
+          // existing collaborator inventory usable when this optional tool is
+          // unavailable.
+          if (!(error instanceof McpToolError)) throw error;
+        }
+
         // --- Deploy keys (optional tool) ---
         try {
           const result = await callJson(
@@ -401,9 +469,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
             },
             capability: "admin",
             discoveredAt,
-            lastUsedAt: pat.last_used_at
-              ? new Date(String(pat.last_used_at))
-              : undefined,
+            lastUsedAt: pat.last_used_at ? new Date(String(pat.last_used_at)) : undefined,
             revocable: {
               possible: true,
               reversible: false,
@@ -448,9 +514,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
         if (!login || !teamOrg || !teamSlug) {
           return { ok: false, error: "team revoke requires username + org/team slug" };
         }
-        const permission = String(
-          grant.capability === "admin" ? "maintainer" : "member",
-        );
+        const permission = String(grant.capability === "admin" ? "maintainer" : "member");
         const undoHint = buildUndoHint({
           system: "github",
           permission,
@@ -508,6 +572,73 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
         };
       }
 
+      // --- Pending repository invitation ---
+      const invitationMatch = resourceId.match(/^([^/]+)\/([^/]+)\/invitation:(.+)$/);
+      if (
+        invitationMatch ||
+        grant.accessState === "pending_invitation" ||
+        grant.revocable.method === "delete_repository_invitation"
+      ) {
+        const [, invitationOwner, invitationRepo, invitationId] = invitationMatch ?? [];
+        if (!invitationOwner || !invitationRepo || !invitationId) {
+          return {
+            ok: false,
+            error: "invitation revoke requires owner/repo/invitation resource id",
+          };
+        }
+        const permission = githubCapabilityToPermission(grant.capability);
+        const undoHint = buildUndoHint({
+          system: "github",
+          permission,
+          restoreMethod: "add_repository_collaborator",
+          params: {
+            owner: invitationOwner,
+            repo: invitationRepo,
+            username: login,
+            permission,
+          },
+        });
+        if (ctx.dryRun) {
+          return {
+            ok: true,
+            detail: `dry_run: would delete pending invitation ${invitationId} from ${invitationOwner}/${invitationRepo}`,
+            undoHint,
+          };
+        }
+        const mcp = requireMcp(ctx);
+        try {
+          await callJson(
+            mcp,
+            server,
+            GitHubMcpTools.deleteRepositoryInvitation,
+            {
+              owner: invitationOwner,
+              repo: invitationRepo,
+              invitation_id: invitationId,
+            },
+            ctx.signal,
+          );
+          return {
+            ok: true,
+            detail: `deleted pending invitation ${invitationId} from ${invitationOwner}/${invitationRepo} (approval ${ctx.approvalCardId})`,
+            undoHint,
+          };
+        } catch (error) {
+          if (isAlreadyAbsentError(error)) {
+            return {
+              ok: true,
+              alreadyAbsent: true,
+              detail: `already absent: invitation ${invitationId} on ${invitationOwner}/${invitationRepo}`,
+              undoHint,
+            };
+          }
+          return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      }
+
       // --- Deploy key (permanent) ---
       if (deployKeyId || grant.revocable.method === "repos.delete_deploy_key") {
         const [owner, repo] = resourceId.split("/");
diff --git a/packages/connectors/src/github/tools.ts b/packages/connectors/src/github/tools.ts
index d6e0772..730799b 100644
--- a/packages/connectors/src/github/tools.ts
+++ b/packages/connectors/src/github/tools.ts
@@ -5,6 +5,7 @@ export const GITHUB_MCP_SERVER = "github";
 export const GitHubMcpTools = {
   searchRepositories: "search_repositories",
   listRepositoryCollaborators: "list_repository_collaborators",
+  listRepositoryInvitations: "list_repository_invitations",
   getTeams: "get_teams",
   getTeamMembers: "get_team_members",
   listCommits: "list_commits",
@@ -14,6 +15,8 @@ export const GitHubMcpTools = {
   listOrgPatInsights: "list_org_pat_insights",
   /** Mutating — remove a repo collaborator (idempotent on already-absent). */
   removeRepositoryCollaborator: "remove_repository_collaborator",
+  /** Mutating — delete a pending repository invitation. */
+  deleteRepositoryInvitation: "delete_repository_invitation",
   /** Mutating — remove a team membership. */
   removeTeamMember: "remove_team_member",
   /** Mutating — delete a deploy key (permanent / no undo). */
diff --git a/packages/connectors/src/revoke.contract.test.ts b/packages/connectors/src/revoke.contract.test.ts
index 0751563..7ed14b0 100644
--- a/packages/connectors/src/revoke.contract.test.ts
+++ b/packages/connectors/src/revoke.contract.test.ts
@@ -117,6 +117,61 @@ describe("GitHub revoke", () => {
     if (absent.ok) expect(absent.alreadyAbsent).toBe(true);
   });
 
+  it("deletes pending invitations through the invitation endpoint", async () => {
+    const calls: Array<{ tool: string; arguments?: Record<string, unknown> }> = [];
+    const mcp: McpToolCaller = {
+      async callTool(request) {
+        calls.push({ tool: request.tool, arguments: request.arguments });
+        return {
+          server: request.server,
+          tool: request.tool,
+          data: {},
+        };
+      },
+    };
+    const grant = createGrant({
+      system: "github",
+      principal: {
+        kind: "human",
+        identifiers: [{ kind: "username", value: "pending-user", source: "github" }],
+      },
+      resource: {
+        id: "keyring-test/payments/invitation:42",
+        displayName: "payments",
+        kind: "repo",
+      },
+      capability: "write",
+      accessState: "pending_invitation",
+      discoveredAt: DISCOVERED,
+      revocable: {
+        possible: true,
+        reversible: true,
+        method: "delete_repository_invitation",
+      },
+      evidence: [
+        {
+          claim: "pending invitation",
+          source: "mcp:github/list_repository_invitations",
+          confidence: "certain",
+        },
+      ],
+    });
+
+    const result = await connector.revoke(grant, writeCtx({ mcp }));
+
+    expect(result.ok).toBe(true);
+    expect(calls).toEqual([
+      {
+        tool: "delete_repository_invitation",
+        arguments: {
+          owner: "keyring-test",
+          repo: "payments",
+          invitation_id: "42",
+        },
+      },
+    ]);
+  });
+
   it("revokes team membership with undo hint", async () => {
     const grant = createGrant({
       system: "github",
diff --git a/packages/core/src/grant.ts b/packages/core/src/grant.ts
index 3604e70..6bbea0f 100644
--- a/packages/core/src/grant.ts
+++ b/packages/core/src/grant.ts
@@ -8,25 +8,11 @@ import {
   type ResourceId,
   type SystemId,
 } from "./brand.js";
-import {
-  requireNonEmptyEvidence,
-  type Evidence,
-  type NonEmptyEvidence,
-} from "./evidence.js";
+import { requireNonEmptyEvidence, type Evidence, type NonEmptyEvidence } from "./evidence.js";
 import { sha256Hex } from "./hash.js";
-import {
-  identifierSortKey,
-  normalizeIdentifier,
-  type Identifier,
-} from "./identifier.js";
+import { identifierSortKey, normalizeIdentifier, type Identifier } from "./identifier.js";
 
-export type System =
-  | "google_workspace"
-  | "github"
-  | "slack"
-  | "aws"
-  | "notion"
-  | "custom";
+export type System = "google_workspace" | "github" | "slack" | "aws" | "notion" | "custom";
 
 export type PrincipalKind = "human" | "service_account" | "unknown";
 
@@ -36,14 +22,7 @@ export type Principal =
   | { kind: "unknown"; identifiers: Identifier[] };
 
 export type ResourceKind =
-  | "repo"
-  | "drive_folder"
-  | "iam_role"
-  | "channel"
-  | "database"
-  | "bucket"
-  | "page"
-  | "other";
+  "repo" | "drive_folder" | "iam_role" | "channel" | "database" | "bucket" | "page" | "other";
 
 export interface Resource {
   id: ResourceId;
@@ -53,6 +32,8 @@ export interface Resource {
 
 export type Capability = "read" | "write" | "admin" | "owner";
 
+export type GrantAccessState = "active" | "pending_invitation";
+
 export interface Revocable {
   possible: boolean;
   reversible: boolean;
@@ -69,6 +50,8 @@ export interface Grant {
   principal: Principal;
   resource: Resource;
   capability: Capability;
+  /** Whether access is active or awaiting acceptance of an invitation. */
+  accessState?: GrantAccessState;
   createdAt?: Date;
   lastUsedAt?: Date;
   discoveredAt: Date;
@@ -127,6 +110,7 @@ export interface CreateGrantInput {
   principal: Principal;
   resource: Omit<Resource, "id"> & { id: string };
   capability: Capability;
+  accessState?: GrantAccessState;
   createdAt?: Date;
   lastUsedAt?: Date;
   discoveredAt: Date;
@@ -154,6 +138,7 @@ export function createGrant(input: CreateGrantInput): Grant {
     principal,
     resource,
     capability: input.capability,
+    ...(input.accessState !== undefined ? { accessState: input.accessState } : {}),
     ...(input.createdAt !== undefined ? { createdAt: input.createdAt } : {}),
     ...(input.lastUsedAt !== undefined ? { lastUsedAt: input.lastUsedAt } : {}),
     discoveredAt: input.discoveredAt,
diff --git a/packages/core/src/identity/run.ts b/packages/core/src/identity/run.ts
index 7f590e6..8c9b24d 100644
--- a/packages/core/src/identity/run.ts
+++ b/packages/core/src/identity/run.ts
@@ -1,8 +1,4 @@
-import {
-  createGrant,
-  type CreateGrantInput,
-  type Grant,
-} from "../grant.js";
+import { createGrant, type CreateGrantInput, type Grant } from "../grant.js";
 import { requireNonEmptyEvidence, type Evidence } from "../evidence.js";
 import { reconcileIdentities } from "./reconcile.js";
 import type {
@@ -25,9 +21,7 @@ export interface ReconciliationJsonInput {
  * Parse a JSON document (sandbox stdin / file) into grants and run reconciliation.
  * Accepts either CreateGrantInput shapes or materialized grants with ISO dates.
  */
-export function runReconciliationFromJson(
-  doc: ReconciliationJsonInput,
-): ReconciliationResult {
+export function runReconciliationFromJson(doc: ReconciliationJsonInput): ReconciliationResult {
   const grants = doc.grants.map((raw, index) => reviveGrant(raw, index));
   const input: ReconciliationInput = {
     grants,
@@ -46,15 +40,14 @@ function reviveGrant(raw: unknown, index: number): Grant {
   const g = raw as Record<string, unknown>;
 
   if (typeof g.id === "string" && g.principal && g.resource && g.evidence) {
-    const evidence = requireNonEmptyEvidence(
-      g.evidence as Evidence[],
-    );
+    const evidence = requireNonEmptyEvidence(g.evidence as Evidence[]);
     return {
       id: g.id as Grant["id"],
       system: g.system as Grant["system"],
       principal: g.principal as Grant["principal"],
       resource: g.resource as Grant["resource"],
       capability: g.capability as Grant["capability"],
+      ...(g.accessState ? { accessState: g.accessState as Grant["accessState"] } : {}),
       discoveredAt: new Date(String(g.discoveredAt)),
       revocable: g.revocable as Grant["revocable"],
       evidence,
diff --git a/scripts/demo.ts b/scripts/demo.ts
index 5df17e4..166defa 100644
--- a/scripts/demo.ts
+++ b/scripts/demo.ts
@@ -153,6 +153,7 @@ async function main(): Promise<void> {
       cwd: root,
       env: {
         ...process.env,
+        VITE_DEMO_MODE: "1",
         VITE_SCAN_DRIVER: "replay",
         VITE_API_BASE_URL: "",
         VITE_API_PORT: String(apiPort),
diff --git a/scripts/test-org/live.ts b/scripts/test-org/live.ts
index 5744e1b..f850971 100644
--- a/scripts/test-org/live.ts
+++ b/scripts/test-org/live.ts
@@ -19,8 +19,7 @@ function requiredLiveEnv(): {
     githubToken: process.env.GITHUB_TOKEN || process.env.KEYRING_GITHUB_TOKEN,
     githubOrg: process.env.GITHUB_ORG || process.env.KEYRING_GITHUB_ORG,
     slackToken: process.env.SLACK_BOT_TOKEN || process.env.KEYRING_SLACK_BOT_TOKEN,
-    googleAccessToken:
-      process.env.GOOGLE_ACCESS_TOKEN || process.env.KEYRING_GOOGLE_ACCESS_TOKEN,
+    googleAccessToken: process.env.GOOGLE_ACCESS_TOKEN || process.env.KEYRING_GOOGLE_ACCESS_TOKEN,
   };
 }
 
@@ -41,6 +40,36 @@ async function githubFetch(
   });
 }
 
+async function githubPendingInvitationIds(
+  token: string,
+  org: string,
+  repo: string,
+  user: string,
+): Promise<{ ids: string[]; error?: string }> {
+  const res = await githubFetch(token, `/repos/${org}/${repo}/invitations`);
+  if (!res.ok) {
+    return { ids: [], error: `${res.status} ${await res.text()}` };
+  }
+  const body = (await res.json()) as unknown;
+  if (!Array.isArray(body)) return { ids: [] };
+  const ids = body
+    .filter(
+      (entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null,
+    )
+    .filter((entry) => {
+      const invitee = entry.invitee;
+      return (
+        typeof invitee === "object" &&
+        invitee !== null &&
+        (invitee as { login?: unknown }).login === user
+      );
+    })
+    .map((entry) => entry.id)
+    .filter((id): id is string | number => typeof id === "string" || typeof id === "number")
+    .map(String);
+  return { ids };
+}
+
 /**
  * Idempotent GitHub ensure: org repos exist (create if missing) and outside
  * collaborators are invited with the intended permission.
@@ -90,16 +119,16 @@ async function seedGitHub(
   ];
 
   for (const c of collabs) {
-    const res = await githubFetch(
-      token,
-      `/repos/${org}/${c.repo}/collaborators/${c.user}`,
-      {
-        method: "PUT",
-        body: JSON.stringify({ permission: c.permission }),
-      },
-    );
-    // 201 invited, 204 already collaborator, 404 user missing
-    if (res.status === 201 || res.status === 204) {
+    const res = await githubFetch(token, `/repos/${org}/${c.repo}/collaborators/${c.user}`, {
+      method: "PUT",
+      body: JSON.stringify({ permission: c.permission }),
+    });
+    // 201 creates an invitation; it does not grant access until accepted.
+    if (res.status === 201) {
+      lines.push(
+        `github: pending invitation for ${c.user} on ${org}/${c.repo} (${c.permission}) [201; not a collaborator]`,
+      );
+    } else if (res.status === 204) {
       lines.push(
         `github: ensured collaborator ${c.user} on ${org}/${c.repo} (${c.permission}) [${res.status}]`,
       );
@@ -115,7 +144,11 @@ async function seedGitHub(
   );
 }
 
-async function seedSlack(token: string, people: readonly TestPerson[], lines: string[]): Promise<void> {
+async function seedSlack(
+  token: string,
+  people: readonly TestPerson[],
+  lines: string[],
+): Promise<void> {
   // Slack Web API: auth.test proves the token; channel invites need real channel IDs.
   const auth = await fetch("https://slack.com/api/auth.test", {
     headers: { Authorization: `Bearer ${token}` },
@@ -131,7 +164,11 @@ async function seedSlack(token: string, people: readonly TestPerson[], lines: st
   );
 }
 
-async function seedGoogle(accessToken: string, people: readonly TestPerson[], lines: string[]): Promise<void> {
+async function seedGoogle(
+  accessToken: string,
+  people: readonly TestPerson[],
+  lines: string[],
+): Promise<void> {
   const about = await fetch("https://www.googleapis.com/drive/v3/about?fields=user", {
     headers: { Authorization: `Bearer ${accessToken}` },
   });
@@ -184,13 +221,35 @@ export async function teardownLiveSystems(people: readonly TestPerson[]): Promis
       { user: people[2]!.githubUsername, repo: "crypto-notes" },
     ];
     for (const r of removals) {
-      const res = await githubFetch(
-        token,
-        `/repos/${org}/${r.repo}/collaborators/${r.user}`,
-        { method: "DELETE" },
-      );
+      const pending = await githubPendingInvitationIds(token, org, r.repo, r.user);
+      if (pending.error) {
+        lines.push(
+          `github: invitation lookup ${r.user} on ${org}/${r.repo} failed: ${pending.error}`,
+        );
+      }
+      for (const invitationId of pending.ids) {
+        const invitation = await githubFetch(
+          token,
+          `/repos/${org}/${r.repo}/invitations/${invitationId}`,
+          { method: "DELETE" },
+        );
+        if (invitation.status === 204 || invitation.status === 404) {
+          lines.push(
+            `github: removed/absent pending invitation ${invitationId} for ${r.user} on ${org}/${r.repo} [${invitation.status}]`,
+          );
+        } else {
+          lines.push(
+            `github: remove invitation ${invitationId} for ${r.user}: ${invitation.status} ${await invitation.text()}`,
+          );
+        }
+      }
+      const res = await githubFetch(token, `/repos/${org}/${r.repo}/collaborators/${r.user}`, {
+        method: "DELETE",
+      });
       if (res.status === 204 || res.status === 404) {
-        lines.push(`github: removed/absent collaborator ${r.user} on ${org}/${r.repo} [${res.status}]`);
+        lines.push(
+          `github: removed/absent collaborator ${r.user} on ${org}/${r.repo} [${res.status}]`,
+        );
       } else {
         lines.push(`github: remove ${r.user}: ${res.status} ${await res.text()}`);
       }
@@ -212,6 +271,8 @@ export async function teardownLiveSystems(people: readonly TestPerson[]): Promis
     lines.push("google: remove Drive shares to personal Gmail addresses manually / via Drive API");
   }
 
-  lines.push("fixtures/: left intact (dev dataset). Delete fixtures/test-org only if you intend to.");
+  lines.push(
+    "fixtures/: left intact (dev dataset). Delete fixtures/test-org only if you intend to.",
+  );
   return { lines };
 }

From 9185725274365d981e8493dc72c593911190f037 Mon Sep 17 00:00:00 2001
From: GautamTalksDev <developwith.gt@gmail.com>
Date: Sun, 30 Aug 2026 02:09:46 -0400
Subject: [PATCH 2/3] fix: close scan streams after terminal events

Prevent replay-mode EventSource reconnects from duplicating the scan history after a run has completed.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/web/src/api/client.ts | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/api/client.ts b/apps/web/src/api/client.ts
index 8cdf2a7..940dfcf 100644
--- a/apps/web/src/api/client.ts
+++ b/apps/web/src/api/client.ts
@@ -207,8 +207,17 @@ export function subscribeScanStream(
     "execute.done",
     "subagent.failed",
   ];
+  const terminalTypes = new Set([
+    "scan.completed",
+    "scan.failed",
+    "scan.cost_capped",
+    "scan.partial",
+  ]);
   for (const t of types) {
-    es.addEventListener(t, (e) => forward(t, (e as MessageEvent).data));
+    es.addEventListener(t, (e) => {
+      forward(t, (e as MessageEvent).data);
+      if (terminalTypes.has(t)) es.close();
+    });
   }
   es.onmessage = (e) => forward("message", e.data);
   es.onerror = () => {

From 8c5bfac407a9823d55b30d2d1f402a31b5af587a Mon Sep 17 00:00:00 2001
From: GautamTalksDev <developwith.gt@gmail.com>
Date: Sun, 30 Aug 2026 02:25:32 -0400
Subject: [PATCH 3/3] fix: make guided demo resets and GitHub inventory
 truthful

Discard superseded demo decisions, reset disposable demo audit state, handle every terminal scan status, preserve invitation capabilities, and surface real MCP inventory failures.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/web/src/App.tsx                          |  1 +
 apps/web/src/api/client.ts                    | 12 ++++
 apps/web/src/hooks/useGuidedDemo.test.ts      | 20 ++++++
 apps/web/src/hooks/useGuidedDemo.ts           | 71 +++++++++++++++---
 apps/web/src/hooks/useScanSession.ts          |  3 +-
 .../github/list_repository_invitations.json   | 32 +++++++++
 .../connectors/src/github.contract.test.ts    | 71 ++++++++++++++++++
 packages/connectors/src/github/connector.ts   | 37 ++++++++--
 .../server/src/api/api.integration.test.ts    | 32 +++++++--
 packages/server/src/api/routes.ts             | 57 ++++++++-------
 packages/server/src/db/store.ts               | 72 ++++++++++---------
 11 files changed, 324 insertions(+), 84 deletions(-)
 create mode 100644 apps/web/src/hooks/useGuidedDemo.test.ts
 create mode 100644 packages/connectors/fixtures/mcp/github/list_repository_invitations.json

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 7a2ce6c..b28bb3a 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -18,6 +18,7 @@ export function App() {
     beginScan: session.beginScan,
     updateCard: session.updateCard,
     cancelScan: session.cancelScan,
+    resetDemoScan: session.resetDemoScan,
   });
   const costs = session.activity.costs;
   const capped = session.activity.status === "cost_capped";
diff --git a/apps/web/src/api/client.ts b/apps/web/src/api/client.ts
index 940dfcf..04bf822 100644
--- a/apps/web/src/api/client.ts
+++ b/apps/web/src/api/client.ts
@@ -80,10 +80,22 @@ export async function postDecision(
     by?: string;
     bulk?: boolean;
   },
+  signal?: AbortSignal,
 ): Promise<{ card: ApiCard; message: string }> {
   return request(`/cards/${cardId}/decision`, {
     method: "POST",
     body: JSON.stringify({ by: "operator", ...body }),
+    signal,
+  });
+}
+
+export async function resetDemoScan(
+  scanId: string,
+  signal?: AbortSignal,
+): Promise<{ scanId: string; reset: number }> {
+  return request(`/scans/${scanId}/demo-reset`, {
+    method: "POST",
+    signal,
   });
 }
 
diff --git a/apps/web/src/hooks/useGuidedDemo.test.ts b/apps/web/src/hooks/useGuidedDemo.test.ts
new file mode 100644
index 0000000..0e36fd8
--- /dev/null
+++ b/apps/web/src/hooks/useGuidedDemo.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { isCurrentGuidedRun, isTerminalScanStatus } from "./useGuidedDemo.js";
+
+describe("guided demo run guards", () => {
+  it("does not apply a decision result from a superseded run", () => {
+    expect(isCurrentGuidedRun(4, 5, false)).toBe(false);
+    expect(isCurrentGuidedRun(5, 5, true)).toBe(false);
+    expect(isCurrentGuidedRun(5, 5, false)).toBe(true);
+  });
+
+  it("treats every non-active scan status as terminal", () => {
+    expect(isTerminalScanStatus("idle")).toBe(false);
+    expect(isTerminalScanStatus("running")).toBe(false);
+    expect(isTerminalScanStatus("completed")).toBe(true);
+    expect(isTerminalScanStatus("partial")).toBe(true);
+    expect(isTerminalScanStatus("failed")).toBe(true);
+    expect(isTerminalScanStatus("cost_capped")).toBe(true);
+  });
+});
diff --git a/apps/web/src/hooks/useGuidedDemo.ts b/apps/web/src/hooks/useGuidedDemo.ts
index 5929253..01b83ad 100644
--- a/apps/web/src/hooks/useGuidedDemo.ts
+++ b/apps/web/src/hooks/useGuidedDemo.ts
@@ -41,6 +41,14 @@ function configuredMinRuntime(): number {
   return Number.isFinite(value) && value >= 0 ? value : DEFAULT_MIN_RUNTIME_MS;
 }
 
+export function isTerminalScanStatus(status: AgentActivityState["status"]): boolean {
+  return status !== "idle" && status !== "running";
+}
+
+export function isCurrentGuidedRun(runId: number, currentRunId: number, aborted: boolean): boolean {
+  return runId === currentRunId && !aborted;
+}
+
 function wait(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
@@ -103,12 +111,14 @@ export function useGuidedDemo({
   beginScan,
   updateCard,
   cancelScan,
+  resetDemoScan,
 }: {
   activity: AgentActivityState;
   cards: ApiCard[];
   beginScan: (person: string) => Promise<string | null>;
   updateCard: (card: ApiCard) => void;
   cancelScan: () => void;
+  resetDemoScan: (scanId: string) => Promise<unknown>;
 }) {
   const [state, setState] = useState<GuidedDemoState>(initialState);
   const activityRef = useRef(activity);
@@ -116,23 +126,44 @@ export function useGuidedDemo({
   const runIdRef = useRef(0);
   const controllerRef = useRef<AbortController | null>(null);
   const gateResolverRef = useRef<(() => void) | null>(null);
+  const pendingDecisionsRef = useRef(new Set<Promise<unknown>>());
+  const committedDecisionIdsRef = useRef(new Set<string>());
+  const resetPromiseRef = useRef<Promise<void> | null>(null);
 
   activityRef.current = activity;
   cardsRef.current = cards;
 
   const stop = useCallback(() => {
+    const scanId = activityRef.current.scanId;
     runIdRef.current += 1;
     controllerRef.current?.abort();
     controllerRef.current = null;
     gateResolverRef.current?.();
     gateResolverRef.current = null;
     cancelScan();
+    if (
+      scanId &&
+      (pendingDecisionsRef.current.size > 0 || committedDecisionIdsRef.current.size > 0)
+    ) {
+      const resetPromise = Promise.allSettled([...pendingDecisionsRef.current])
+        .then(() => resetDemoScan(scanId))
+        .then(() => undefined);
+      resetPromiseRef.current = resetPromise;
+      void resetPromise
+        .catch(() => undefined)
+        .finally(() => {
+          if (resetPromiseRef.current === resetPromise) {
+            resetPromiseRef.current = null;
+          }
+        });
+      committedDecisionIdsRef.current.clear();
+    }
     setState((previous) => ({
       ...previous,
       phase: "stopped",
       message: "Guided demo stopped. Start it again for another take.",
     }));
-  }, [cancelScan]);
+  }, [cancelScan, resetDemoScan]);
 
   useEffect(() => {
     return () => {
@@ -158,6 +189,8 @@ export function useGuidedDemo({
       return;
     }
 
+    await resetPromiseRef.current?.catch(() => undefined);
+    committedDecisionIdsRef.current.clear();
     const runId = runIdRef.current + 1;
     runIdRef.current = runId;
     const controller = new AbortController();
@@ -166,7 +199,7 @@ export function useGuidedDemo({
     let pausedAt: number | null = null;
     let pausedMs = 0;
 
-    const current = () => runIdRef.current === runId && !controller.signal.aborted;
+    const current = () => isCurrentGuidedRun(runId, runIdRef.current, controller.signal.aborted);
     const update = (patch: Partial<GuidedDemoState>) => {
       if (current()) setState((previous) => ({ ...previous, ...patch }));
     };
@@ -187,10 +220,7 @@ export function useGuidedDemo({
 
       await waitFor(
         () =>
-          activityRef.current.scanId === scanId &&
-          (activityRef.current.status === "completed" ||
-            activityRef.current.status === "partial" ||
-            activityRef.current.status === "failed"),
+          activityRef.current.scanId === scanId && isTerminalScanStatus(activityRef.current.status),
         controller.signal,
       );
       if (activityRef.current.status !== "completed") {
@@ -217,6 +247,27 @@ export function useGuidedDemo({
         throw new Error("The guided demo requires a protected CI card.");
       }
 
+      const decide = async (
+        cardId: string,
+        body: {
+          decision: "approve" | "hold" | "reject";
+          note?: string;
+          by?: string;
+        },
+      ) => {
+        const request = postDecision(cardId, body, controller.signal);
+        pendingDecisionsRef.current.add(request);
+        try {
+          const result = await request;
+          if (!current()) return null;
+          committedDecisionIdsRef.current.add(cardId);
+          updateCard(result.card);
+          return result;
+        } finally {
+          pendingDecisionsRef.current.delete(request);
+        }
+      };
+
       for (let index = 0; index < safeCards.length; index += 1) {
         const card = safeCards[index]!;
         update({
@@ -224,11 +275,11 @@ export function useGuidedDemo({
           targetCardId: card.id,
           message: `Approving safe card ${index + 1} of ${safeCards.length}…`,
         });
-        const result = await postDecision(card.id, {
+        const result = await decide(card.id, {
           decision: "approve",
           by: "guided-demo",
         });
-        updateCard(result.card);
+        if (!result) return;
         if (index < safeCards.length - 1) {
           await wait(DECISION_GAP_MS, controller.signal);
         }
@@ -261,12 +312,12 @@ export function useGuidedDemo({
         phase: "holding",
         message: "Recording the human decision: belongs to CI, flag the owner.",
       });
-      const held = await postDecision(ciCard.id, {
+      const held = await decide(ciCard.id, {
         decision: "hold",
         note: "belongs to CI, flag the owner",
         by: "guided-demo",
       });
-      updateCard(held.card);
+      if (!held) return;
       await wait(HOLD_CONFIRMATION_MS, controller.signal);
 
       update({
diff --git a/apps/web/src/hooks/useScanSession.ts b/apps/web/src/hooks/useScanSession.ts
index 894f0c0..c740b2c 100644
--- a/apps/web/src/hooks/useScanSession.ts
+++ b/apps/web/src/hooks/useScanSession.ts
@@ -1,6 +1,6 @@
 import { useEffect, useReducer, useRef } from "react";
 
-import { fetchCards, startScan, subscribeScanStream } from "../api/client.js";
+import { fetchCards, resetDemoScan, startScan, subscribeScanStream } from "../api/client.js";
 import type {
   AgentActivityState,
   ApiCard,
@@ -622,5 +622,6 @@ export function useScanSession() {
     updateCard,
     dismissError,
     cancelScan,
+    resetDemoScan,
   };
 }
diff --git a/packages/connectors/fixtures/mcp/github/list_repository_invitations.json b/packages/connectors/fixtures/mcp/github/list_repository_invitations.json
new file mode 100644
index 0000000..0013111
--- /dev/null
+++ b/packages/connectors/fixtures/mcp/github/list_repository_invitations.json
@@ -0,0 +1,32 @@
+[
+  {
+    "when": { "owner": "keyring-test", "repo": "payments" },
+    "response": [
+      {
+        "id": 101,
+        "login": "pull-invite",
+        "permissions": { "pull": true }
+      }
+    ]
+  },
+  {
+    "when": { "owner": "keyring-test", "repo": "infra" },
+    "response": [
+      {
+        "id": 102,
+        "login": "push-invite",
+        "permissions": { "pull": true, "push": true }
+      }
+    ]
+  },
+  {
+    "when": { "owner": "keyring-test", "repo": "crypto-notes" },
+    "response": [
+      {
+        "id": 103,
+        "login": "admin-invite",
+        "permissions": { "pull": true, "push": true, "admin": true }
+      }
+    ]
+  }
+]
diff --git a/packages/connectors/src/github.contract.test.ts b/packages/connectors/src/github.contract.test.ts
index c06dc60..b6cc21e 100644
--- a/packages/connectors/src/github.contract.test.ts
+++ b/packages/connectors/src/github.contract.test.ts
@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 
 import { createGitHubConnector } from "./github/connector.js";
 import { createFixtureMcpToolCaller } from "./mcp/fixture-caller.js";
+import { McpToolError, type McpToolCaller } from "./mcp/types.js";
 import type { InventoryContext } from "./types.js";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
@@ -18,6 +19,21 @@ async function loadFixtureGithubGrants() {
 }
 
 describe("GitHubConnector contract (MCP fixtures)", () => {
+  async function inventory(mcp: McpToolCaller = createFixtureMcpToolCaller()) {
+    const connector = createGitHubConnector({
+      org: "keyring-test",
+      discoveredAt: DISCOVERED_AT,
+    });
+    const grants = [];
+    for await (const grant of connector.inventory({
+      credentials: { kind: "read", token: "t" },
+      mcp,
+    })) {
+      grants.push(grant);
+    }
+    return grants;
+  }
+
   it("inventories repos, collaborators, commit emails, and deploy keys via MCP", async () => {
     const connector = createGitHubConnector({
       org: "keyring-test",
@@ -67,6 +83,61 @@ describe("GitHubConnector contract (MCP fixtures)", () => {
     expect(trap!.capability).toBe("admin");
   });
 
+  it("maps pending invitation pull, push, and admin permissions correctly", async () => {
+    const invitations = (await inventory()).filter(
+      (grant) => grant.accessState === "pending_invitation",
+    );
+
+    expect(
+      invitations.map((grant) => [grant.principal.identifiers[0]?.value, grant.capability]),
+    ).toEqual(
+      expect.arrayContaining([
+        ["pull-invite", "read"],
+        ["push-invite", "write"],
+        ["admin-invite", "admin"],
+      ]),
+    );
+  });
+
+  it("swallows only an unavailable invitation tool", async () => {
+    const delegate = createFixtureMcpToolCaller();
+    const mcp: McpToolCaller = {
+      async callTool(request) {
+        if (request.tool === "list_repository_invitations") {
+          throw new McpToolError("tool list_repository_invitations not found", {
+            server: request.server,
+            tool: request.tool,
+            status: 404,
+          });
+        }
+        return delegate.callTool(request);
+      },
+    };
+
+    await expect(inventory(mcp)).resolves.toEqual(expect.any(Array));
+  });
+
+  it("surfaces invitation authentication failures for a partial scan", async () => {
+    const delegate = createFixtureMcpToolCaller();
+    const mcp: McpToolCaller = {
+      async callTool(request) {
+        if (request.tool === "list_repository_invitations") {
+          throw new McpToolError("GitHub token is not authorized", {
+            server: request.server,
+            tool: request.tool,
+            status: 401,
+          });
+        }
+        return delegate.callTool(request);
+      },
+    };
+
+    await expect(inventory(mcp)).rejects.toMatchObject({
+      name: "McpToolError",
+      status: 401,
+    });
+  });
+
   it("covers every GitHub grant resource from the test-org fixtures", async () => {
     const fixtureGrants = await loadFixtureGithubGrants();
     const connector = createGitHubConnector({
diff --git a/packages/connectors/src/github/connector.ts b/packages/connectors/src/github/connector.ts
index a96e67b..64a016c 100644
--- a/packages/connectors/src/github/connector.ts
+++ b/packages/connectors/src/github/connector.ts
@@ -37,6 +37,35 @@ function evidenceSource(server: string, tool: string): string {
   return `mcp:${server}/${tool}`;
 }
 
+function isTrue(value: unknown): boolean {
+  return value === true || value === "true";
+}
+
+function invitationPermission(invitation: Record<string, unknown>): string {
+  const explicit = invitation.role_name ?? invitation.permission;
+  if (explicit !== undefined && explicit !== null && String(explicit)) {
+    return String(explicit);
+  }
+
+  const permissions = asObject(invitation.permissions);
+  for (const permission of ["admin", "maintain", "push", "triage", "pull"]) {
+    if (isTrue(permissions[permission])) return permission;
+  }
+  return "pull";
+}
+
+function isUnavailableInvitationTool(error: unknown): boolean {
+  if (!(error instanceof McpToolError)) return false;
+  if (error.tool !== GitHubMcpTools.listRepositoryInvitations) return false;
+  if (error.status !== 404) return false;
+  const message = error.message.toLowerCase();
+  return (
+    message.includes("no mcp fixture") ||
+    /(?:tool|method|operation|endpoint).*(?:not found|not available|unsupported)/.test(message) ||
+    message.includes("tool is not configured")
+  );
+}
+
 /**
  * GitHub inventory via TrueForge-configured GitHub MCP tools — never Octokit.
  */
@@ -327,11 +356,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
                 ? [{ kind: "personal_email", value: email, source: "github" }]
                 : [];
             if (identifiers.length === 0) continue;
-            const permission = String(
-              invitation.role_name ??
-                invitation.permission ??
-                (asObject(invitation.permissions).admin ? "admin" : "pull"),
-            );
+            const permission = invitationPermission(invitation);
             yield createGrant({
               system: "github",
               principal: { kind: "human", identifiers },
@@ -365,7 +390,7 @@ export function createGitHubConnector(options: GitHubConnectorOptions): Connecto
           // The shipped GitHub MCP may not expose invitations yet. Keep the
           // existing collaborator inventory usable when this optional tool is
           // unavailable.
-          if (!(error instanceof McpToolError)) throw error;
+          if (!isUnavailableInvitationTool(error)) throw error;
         }
 
         // --- Deploy keys (optional tool) ---
diff --git a/packages/server/src/api/api.integration.test.ts b/packages/server/src/api/api.integration.test.ts
index 6581020..223ad09 100644
--- a/packages/server/src/api/api.integration.test.ts
+++ b/packages/server/src/api/api.integration.test.ts
@@ -13,21 +13,19 @@ import { verifyStoredAuditChain } from "../db/store.js";
 
 /** Reset append-only ledger for a clean chain (test-only). */
 async function resetAuditLedger(db: AppDb): Promise<void> {
-  await db.execute(
-    sql`ALTER TABLE audit_records DISABLE TRIGGER audit_records_append_only`,
-  );
+  await db.execute(sql`ALTER TABLE audit_records DISABLE TRIGGER audit_records_append_only`);
   await db.execute(sql`TRUNCATE TABLE audit_records`);
-  await db.execute(
-    sql`ALTER TABLE audit_records ENABLE TRIGGER audit_records_append_only`,
-  );
+  await db.execute(sql`ALTER TABLE audit_records ENABLE TRIGGER audit_records_append_only`);
 }
 
 describe("API scan → approve → execute → audit (fixture)", () => {
   let db: AppDb;
   let close: () => Promise<void>;
   let app: ReturnType<typeof createApp>;
+  const previousDemo = process.env.KEYRING_DEMO;
 
   beforeAll(async () => {
+    process.env.KEYRING_DEMO = "1";
     const handle = await openTestDatabase("api");
     db = handle.db;
     close = handle.close;
@@ -38,6 +36,8 @@ describe("API scan → approve → execute → audit (fixture)", () => {
   afterAll(async () => {
     await app.close();
     await close();
+    if (previousDemo === undefined) delete process.env.KEYRING_DEMO;
+    else process.env.KEYRING_DEMO = previousDemo;
   });
 
   it("runs the full path and verifies the hash chain", async () => {
@@ -109,5 +109,25 @@ describe("API scan → approve → execute → audit (fixture)", () => {
 
     const chain = await verifyStoredAuditChain(db);
     expect(chain.ok).toBe(true);
+
+    const reset = await app.inject({
+      method: "POST",
+      url: `/scans/${scanId}/demo-reset`,
+    });
+    expect(reset.statusCode).toBe(200);
+    expect((reset.json() as { reset: number }).reset).toBeGreaterThan(0);
+
+    const resetCards = await app.inject({
+      method: "GET",
+      url: `/scans/${scanId}/cards`,
+    });
+    const resetCardData = resetCards.json() as {
+      cards: Array<{ status: string; decision: unknown }>;
+    };
+    expect(resetCardData.cards.every((card) => card.status === "pending")).toBe(true);
+    expect(resetCardData.cards.every((card) => card.decision === null)).toBe(true);
+
+    const audit = await app.inject({ method: "GET", url: "/audit" });
+    expect((audit.json() as { records: unknown[] }).records).toHaveLength(0);
   }, 60_000);
 });
diff --git a/packages/server/src/api/routes.ts b/packages/server/src/api/routes.ts
index b42b4b7..d6cd23e 100644
--- a/packages/server/src/api/routes.ts
+++ b/packages/server/src/api/routes.ts
@@ -9,6 +9,7 @@ import {
   listAuditChain,
   listAuditRecords,
   listCardsForScan,
+  resetDemoScan,
   setCardDecision,
   verifyStoredAuditChain,
 } from "../db/store.js";
@@ -48,10 +49,7 @@ function writeSse(reply: FastifyReply, event: string, data: unknown): void {
   reply.raw.write(`data: ${JSON.stringify(data)}\n\n`);
 }
 
-export function registerApiRoutes(
-  app: FastifyInstance,
-  opts: { db: Database["db"] },
-): void {
+export function registerApiRoutes(app: FastifyInstance, opts: { db: Database["db"] }): void {
   const { db } = opts;
 
   app.post("/scans", async (req, reply) => {
@@ -212,25 +210,16 @@ export function registerApiRoutes(
       return reply.code(404).send({ error: "card_not_found" });
     }
 
-    if (
-      body.bulk === true &&
-      body.decision === "approve" &&
-      card.protected === true
-    ) {
+    if (body.bulk === true && body.decision === "approve" && card.protected === true) {
       return reply.code(403).send({
         error: "protected_no_bulk",
         message:
-          card.protectedReason ??
-          "Protected by keyring.yml — approve individually, never in bulk.",
+          card.protectedReason ?? "Protected by keyring.yml — approve individually, never in bulk.",
       });
     }
 
     const status: ApprovalStatus =
-      body.decision === "approve"
-        ? "approved"
-        : body.decision === "hold"
-          ? "held"
-          : "rejected";
+      body.decision === "approve" ? "approved" : body.decision === "hold" ? "held" : "rejected";
 
     const decision: Decision = {
       by: body.by,
@@ -257,11 +246,32 @@ export function registerApiRoutes(
 
     return {
       card: updated ? serializeCard(updated) : null,
-      message:
-        "Decision recorded. Call POST /scans/:id/execute to apply approved actions.",
+      message: "Decision recorded. Call POST /scans/:id/execute to apply approved actions.",
     };
   });
 
+  app.post("/scans/:id/demo-reset", async (req, reply) => {
+    if (process.env.KEYRING_DEMO !== "1") {
+      return reply.code(404).send({ error: "not_found" });
+    }
+
+    let params;
+    try {
+      params = scanIdParamSchema.parse(req.params);
+    } catch (err) {
+      if (err instanceof ZodError) return zodError(reply, err);
+      throw err;
+    }
+
+    const scan = await getScanRun(db, params.id);
+    if (!scan) {
+      return reply.code(404).send({ error: "scan_not_found" });
+    }
+
+    const reset = await resetDemoScan(db, params.id);
+    return { scanId: params.id, reset };
+  });
+
   app.post("/scans/:id/execute", async (req, reply) => {
     let params;
     let body;
@@ -343,12 +353,10 @@ export function registerApiRoutes(
 
     const chain = await listAuditChain(db, { cardId: query.cardId });
     const verification = await verifyStoredAuditChain(db);
-    const secret =
-      process.env.KEYRING_EXPORT_SECRET ?? "keyring-dev-export-secret";
+    const secret = process.env.KEYRING_EXPORT_SECRET ?? "keyring-dev-export-secret";
 
     if (query.format === "csv") {
-      const header =
-        "id,cardId,action,approvedBy,approvedAt,executedAt,result,error,prevHash,hash";
+      const header = "id,cardId,action,approvedBy,approvedAt,executedAt,result,error,prevHash,hash";
       const lines = chain.map((r) =>
         [
           r.id,
@@ -371,10 +379,7 @@ export function registerApiRoutes(
       reply.header("x-keyring-signature", signature);
       reply.header("x-keyring-signature-alg", algorithm);
       reply.header("x-keyring-content-sha256", contentHash(body));
-      reply.header(
-        "x-keyring-chain-ok",
-        verification.ok ? "true" : "false",
-      );
+      reply.header("x-keyring-chain-ok", verification.ok ? "true" : "false");
       return reply.send(body);
     }
 
diff --git a/packages/server/src/db/store.ts b/packages/server/src/db/store.ts
index 2ce699b..02bdb4f 100644
--- a/packages/server/src/db/store.ts
+++ b/packages/server/src/db/store.ts
@@ -18,10 +18,7 @@ import { approvalCards, auditRecords, grants, scanRuns } from "./schema.js";
 /** Serialize hash-chain appends so two writers cannot share a prevHash. */
 const AUDIT_CHAIN_LOCK = sql`SELECT pg_advisory_xact_lock(hashtext('keyring.audit_records.chain'))`;
 
-export async function upsertGrant(
-  db: Database["db"],
-  grant: Grant,
-): Promise<void> {
+export async function upsertGrant(db: Database["db"], grant: Grant): Promise<void> {
   await db
     .insert(grants)
     .values({
@@ -84,9 +81,7 @@ export async function upsertApprovalCard(
           protectedReason: card.protectedReason,
         }
       : {}),
-    ...(card.autoApprovedBy
-      ? { autoApprovedBy: card.autoApprovedBy }
-      : {}),
+    ...(card.autoApprovedBy ? { autoApprovedBy: card.autoApprovedBy } : {}),
   };
   await db
     .insert(approvalCards)
@@ -118,10 +113,7 @@ export async function upsertApprovalCard(
     });
 }
 
-export async function appendAuditRecordRow(
-  db: Database["db"],
-  record: AuditRecord,
-): Promise<void> {
+export async function appendAuditRecordRow(db: Database["db"], record: AuditRecord): Promise<void> {
   await db.insert(auditRecords).values({
     id: record.id,
     cardId: record.cardId,
@@ -205,11 +197,7 @@ export async function getApprovalCard(
   db: Database["db"],
   cardId: string,
 ): Promise<ApprovalCard | null> {
-  const rows = await db
-    .select()
-    .from(approvalCards)
-    .where(eq(approvalCards.id, cardId))
-    .limit(1);
+  const rows = await db.select().from(approvalCards).where(eq(approvalCards.id, cardId)).limit(1);
   const row = rows[0];
   return row ? rowToCard(row) : null;
 }
@@ -231,6 +219,34 @@ export async function setCardDecision(
   return getApprovalCard(db, cardId);
 }
 
+/**
+ * Reset a demo take after an aborted run. This is deliberately separate from
+ * the production decision path: the demo database is disposable, so its
+ * abandoned audit records may be cleared before the next recording take.
+ */
+export async function resetDemoScan(db: Database["db"], scanId: string): Promise<number> {
+  return db.transaction(async (tx) => {
+    const cards = await tx
+      .select({ id: approvalCards.id })
+      .from(approvalCards)
+      .where(eq(approvalCards.scanId, scanId));
+
+    await tx
+      .update(approvalCards)
+      .set({
+        status: "pending",
+        decision: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(approvalCards.scanId, scanId));
+
+    await tx.execute(sql`ALTER TABLE audit_records DISABLE TRIGGER audit_records_append_only`);
+    await tx.delete(auditRecords);
+    await tx.execute(sql`ALTER TABLE audit_records ENABLE TRIGGER audit_records_append_only`);
+    return cards.length;
+  });
+}
+
 export async function listApprovedCardsForScan(
   db: Database["db"],
   scanId: string,
@@ -238,9 +254,7 @@ export async function listApprovedCardsForScan(
   const rows = await db
     .select()
     .from(approvalCards)
-    .where(
-      and(eq(approvalCards.scanId, scanId), eq(approvalCards.status, "approved")),
-    );
+    .where(and(eq(approvalCards.scanId, scanId), eq(approvalCards.status, "approved")));
   return rows.map(rowToCard);
 }
 
@@ -266,10 +280,7 @@ export async function getPreviousCompletedScan(
  * True when this card already has a real successful execute_* outcome
  * (excludes dry_run and attempt_started partials). Enables independent retries.
  */
-export async function hasSuccessfulExecute(
-  db: Database["db"],
-  cardId: string,
-): Promise<boolean> {
+export async function hasSuccessfulExecute(db: Database["db"], cardId: string): Promise<boolean> {
   const rows = await db
     .select({
       action: auditRecords.action,
@@ -289,9 +300,7 @@ export async function hasSuccessfulExecute(
   );
 }
 
-export async function getLatestAuditHash(
-  db: AppDb,
-): Promise<typeof GENESIS_HASH> {
+export async function getLatestAuditHash(db: AppDb): Promise<typeof GENESIS_HASH> {
   const rows = await db
     .select({ hash: auditRecords.hash })
     .from(auditRecords)
@@ -369,12 +378,7 @@ function rowToCard(row: typeof approvalCards.$inferSelect): ApprovalCard {
     protectedReason?: string;
     autoApprovedBy?: string;
   };
-  const {
-    protected: isProtected,
-    protectedReason,
-    autoApprovedBy,
-    ...attribution
-  } = attrRaw;
+  const { protected: isProtected, protectedReason, autoApprovedBy, ...attribution } = attrRaw;
   return {
     id: asApprovalCardId(row.id),
     grant,
@@ -391,9 +395,7 @@ function rowToCard(row: typeof approvalCards.$inferSelect): ApprovalCard {
           },
         }
       : {}),
-    ...(isProtected
-      ? { protected: true, protectedReason }
-      : {}),
+    ...(isProtected ? { protected: true, protectedReason } : {}),
     ...(autoApprovedBy ? { autoApprovedBy } : {}),
   };
 }