ai-install-guard 0.1.0 → 0.3.0

package/hooks/guard/pane.tsx

@@ -1,15 +1,19 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, RenderElement, RenderInput } from 'claude-code'
 
-import type { GuardRow, GuardStatus, GuardView } from '../../types'
+import type { GuardRequest, GuardRow, GuardStatus, GuardView } from '../../types'
 import { GROUPS } from '../scan/checks/types'
+import { safeLine } from '../scan/safe-text'
 import { locate } from '../scan/verdict'
-import { recordDecision, saveLastView } from './decisions'
+import { badgeFor } from './badge'
+import { changedSinceScan } from '../gate/recheck'
+import { modHost } from '../mod-host'
+import { loadReport, recordDecision, saveLastView } from './decisions'
+import { grantPass, takePass } from './passes'
 import { needsConfirmation, PANE_ID, primaryLabel } from './view'
 
 const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
 
-export const REPORT_TEXT = 'last-report-text'
 
 const ICON: Record<GuardStatus, string> = { fail: '✖', warn: '⚠', pass: '✔', info: '·' }
 const COLOR: Record<GuardStatus, string> = { fail: 'error', warn: 'warning', pass: 'success', info: 'subtle' }
@@ -31,7 +35,11 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     )
   }
 
-  const header = [view.kind === undefined ? undefined : `A ${view.kind}`, view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`]
+  const header = [
+    view.kind === undefined ? undefined : `A ${view.kind}`,
+    view.sha === undefined ? undefined : `commit ${view.sha.slice(0, 12)}`,
+    view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`,
+  ]
     .filter(part => part !== undefined)
     .join(' · ')
 
@@ -41,15 +49,71 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     update($, viewAtom, current =>
       current === null ? current : { ...current, expanded: current.expanded.includes(id) ? current.expanded.filter(item => item !== id) : [...current.expanded, id] },
     )
+  const codeOpen = (row: GuardRow): boolean => (view.codeOpen ?? []).includes(row.id)
+  const toggleCode = (id: string) => () =>
+    update($, viewAtom, current => {
+      if (current === null) return current
+      const open = current.codeOpen ?? []
+      return { ...current, codeOpen: open.includes(id) ? open.filter(item => item !== id) : [...open, id] }
+    })
+
+  // A press counts only on the scan it was drawn from, and only once: the
+  // first press claims the decision, and a scan that took the pane since, or
+  // a second press, changes nothing.
+  const claim = async (): Promise<GuardView | undefined> => {
+    let claimed: GuardView | undefined
+    await update($, viewAtom, latest => {
+      claimed = undefined
+      if (latest === null || latest.scanId !== view.scanId || latest.verdict === undefined || latest.decision !== undefined || latest.deciding === true) return latest
+      claimed = { ...latest, deciding: true }
+      return claimed
+    })
+    return claimed
+  }
+  /** Puts `next` in the pane while it still shows this scan; false once another scan has taken it. */
+  const replaceOwn = async (next: GuardView): Promise<boolean> => {
+    let ours = false
+    await update($, viewAtom, latest => {
+      ours = latest !== null && latest.scanId === view.scanId
+      return ours ? next : latest
+    })
+    return ours
+  }
+  const release = (current: GuardView) => replaceOwn({ ...current, deciding: false })
+  /**
+   * Saves this scan's outcome for /guard report; should a newer scan take
+   * the pane meanwhile, its view is saved instead, so the reopened report is
+   * always the pane's.
+   */
+  const saveOwn = async (outcome: GuardView): Promise<void> => {
+    await saveLastView($, outcome).catch(() => undefined)
+    const now = await read($, viewAtom).catch(() => null)
+    if (now !== null && now.scanId !== outcome.scanId) await saveLastView($, now).catch(() => undefined)
+  }
+  const movedOn = 'the pane has moved on to another scan'
 
   const decide = (decision: 'approved' | 'rejected', overridden: boolean) => async () => {
-    const current = await read($, viewAtom)
-    if (current === null || current.verdict === undefined) return
+    const current = await claim()
+    if (current === undefined || current.verdict === undefined) return
+    const held = current.action === 'install' ? current.request : undefined
     // A scan that never read the files has no tree hash to pin a decision to:
-    // the pane closes, nothing is remembered, and nothing claims otherwise.
+    // nothing is remembered, and nothing claims otherwise. A held install the
+    // person allows anyway goes through once, as that exact command.
     if (current.treeHash === undefined) {
-      $.ui.toast('AI Install Guard: closed; the scan read nothing, so there is no decision to remember')
-      await $.ui.close({ id: PANE_ID })
+      if (held !== undefined && decision === 'approved') {
+        // The pass is spent on this request: the reopened report shows it allowed, not the buttons again.
+        const allowed = { ...current, decision, decidedAt: Date.now(), confirming: false, deciding: false }
+        if (!(await replaceOwn(allowed))) {
+          $.ui.toast(`AI Install Guard: nothing was allowed: ${movedOn}`)
+          return
+        }
+        await grantPass($, { origin: held.origin, args: held.args })
+        await saveOwn(allowed)
+        await carryOut($, held, allowed)
+        return
+      }
+      $.ui.toast(held !== undefined ? 'AI Install Guard: rejected; nothing was installed' : 'AI Install Guard: closed; the scan read nothing, so there is no decision to remember')
+      if (await release(current)) await closeOwn($, current)
       return
     }
     const decidedAt = Date.now()
@@ -57,6 +121,7 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
       await recordDecision($, {
         target: current.target,
         root: current.root,
+        sha: current.sha,
         treeHash: current.treeHash,
         verdict: current.verdict.recommendation,
         verdictKind: current.verdict.kind,
@@ -67,29 +132,53 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     } catch {
       // Nothing was saved: say so, and leave the pane open to try again.
       $.ui.toast('AI Install Guard: could not save the decision; nothing was recorded')
+      await release(current)
+      return
+    }
+    const decided = { ...current, decision, decidedAt, confirming: false, deciding: false }
+    // The decision is saved for its version either way; the pane, the
+    // reopened report and the install are this scan's only while it has the pane.
+    if (!(await replaceOwn(decided))) {
+      $.ui.toast(`AI Install Guard: ${decision} ${current.target}, but ${movedOn}${held !== undefined && decision === 'approved' ? '; run the install again and it goes through' : ''}`)
       return
     }
-    const decided = { ...current, decision, decidedAt, confirming: false }
-    await update($, viewAtom, () => decided)
     // The reopened report shows the outcome, not the buttons again.
-    await saveLastView($, decided).catch(() => undefined)
-    $.ui.toast(`AI Install Guard: ${decision === 'approved' ? 'approved' : 'rejected'} ${current.target}`)
-    await $.ui.close({ id: PANE_ID })
+    await saveOwn(decided)
+    // The approval is saved for this exact version, so the install, asked for
+    // again, now goes through: the gate looks the version up again first.
+    if (held !== undefined && decision === 'approved') {
+      await carryOut($, held, decided)
+      return
+    }
+    $.ui.toast(`AI Install Guard: ${decision === 'approved' ? 'approved' : 'rejected'} ${current.target}${held === undefined ? '' : '; nothing was installed'}`)
+    await closeOwn($, decided)
   }
 
   const primary = async () => {
     const current = await read($, viewAtom)
-    if (current === null) return
+    if (current === null || current.scanId !== view.scanId) return
     if (needsConfirmation(current)) {
-      await update($, viewAtom, latest => (latest === null ? latest : { ...latest, confirming: true }))
+      await update($, viewAtom, latest => (latest === null || latest.scanId !== view.scanId ? latest : { ...latest, confirming: true }))
       return
     }
     await decide('approved', false)()
   }
 
+  const copyBadge = async () => {
+    const made = badgeFor(view)
+    if ('refusal' in made) {
+      $.ui.toast(`AI Install Guard: ${made.refusal}`)
+      return
+    }
+    const result = await $.ui.copy({ text: made.markdown, surface: e.surface })
+    $.ui.toast(result.isCopied ? 'AI Install Guard: badge copied; paste it near the top of your README' : 'AI Install Guard: could not copy the badge here')
+  }
+  const offersBadge = view.treeHash !== undefined && (view.verdict?.kind === 'safe' || view.verdict?.kind === 'caution')
+
   const copy = async () => {
-    const text = await $.store.get(REPORT_TEXT)
-    const result = await $.ui.copy({ text: typeof text === 'string' ? text : 'No report yet.', surface: e.surface })
+    // Only this scan's own report: never another scan's in its place.
+    const text = await loadReport($, view.scanId)
+    const result = await $.ui.copy({ text: text ?? 'No report yet.', surface: e.surface })
     $.ui.toast(result.isCopied ? 'AI Install Guard: report copied' : 'AI Install Guard: could not copy the report here')
   }
 
@@ -105,6 +194,12 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
         </Text>
       )}
 
+      {view.request !== undefined && (
+        <Text dimColor wrap="truncate-end">
+          {requestLine(view.request)}
+        </Text>
+      )}
+
       {verdict === undefined ? (
         <Text color="suggestion" wrap="truncate-end">
           Scanning: {view.stage}…
@@ -138,7 +233,11 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
           <Text bold>{group.title}</Text>
           {rowsOf(group.id).map(row => {
             const first = row.evidence[0]
-            const summary = first === undefined ? '' : `: ${locate(first.file, first.line)}${first.excerpt}`
+            const headline = row.summary?.[0]
+            const summary = headline !== undefined ? `: ${headline}` : first === undefined ? '' : `: ${locate(first.file, first.line)}${first.excerpt}`
+            const places = row.evidence.length + row.more
+            // With a summary, the code lines are one step further in.
+            const showCode = row.summary === undefined || codeOpen(row)
             return (
               <Box key={`row-${row.id}`} flexDirection="column">
                 <Button key={`toggle-${row.id}`} plain onPress={toggle(row.id)}>
@@ -147,18 +246,31 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
                 </Button>
                 {isOpen(row) && (
                   <Box key={`detail-${row.id}`} flexDirection="column" paddingLeft={2}>
-                    {row.evidence.map(item => (
-                      <Text wrap="wrap" color={item.status === undefined ? undefined : COLOR[item.status]}>
-                        {locate(item.file, item.line)}
-                        {item.excerpt}
+                    {row.summary?.map((line, index) => (
+                      <Text wrap="wrap" bold={index === 0}>
+                        {line}
                       </Text>
                     ))}
-                    {row.more > 0 && <Text dimColor>… and {row.more} more in the copied report</Text>}
                     {(row.status === 'fail' || row.status === 'warn') && (
                       <Text dimColor wrap="wrap">
                         {row.advice}
                       </Text>
                     )}
+                    {row.summary !== undefined && places > 0 && (
+                      <Button key={`code-${row.id}`} plain onPress={toggleCode(row.id)}>
+                        <Text color="suggestion">
+                          {codeOpen(row) ? 'Hide the code' : `Show the code (${places} place${places === 1 ? '' : 's'})`}
+                        </Text>
+                      </Button>
+                    )}
+                    {showCode &&
+                      row.evidence.map(item => (
+                        <Text wrap="wrap" color={item.status === undefined ? undefined : COLOR[item.status]}>
+                          {locate(item.file, item.line)}
+                          {item.excerpt}
+                        </Text>
+                      ))}
+                    {showCode && row.more > 0 && <Text dimColor>… and {row.more} more in the copied report</Text>}
                   </Box>
                 )}
               </Box>
@@ -167,18 +279,19 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
         </Box>
       ))}
 
-      {verdict !== undefined && view.decision === undefined && !view.confirming && (
+      {verdict !== undefined && view.decision === undefined && !view.confirming && view.deciding !== true && (
         <Box key="actions" flexDirection="row" gap={1} marginTop={1}>
-          {view.treeHash !== undefined && (
+          {(view.treeHash !== undefined || (view.action === 'install' && view.request !== undefined)) && (
             <Button key="install" label={primaryLabel(view)} hotkey="i" variant={needsConfirmation(view) ? 'secondary' : 'primary'} onPress={primary} />
           )}
           <Button key="reject" label="Reject" hotkey="r" variant={needsConfirmation(view) ? 'primary' : 'secondary'} onPress={decide('rejected', false)} />
           <Button key="details" label={view.details ? 'Fewer details' : 'Details'} hotkey="d" onPress={() => update($, viewAtom, current => (current === null ? current : { ...current, details: !current.details }))} />
           <Button key="copy" label="Copy report" hotkey="c" onPress={copy} />
+          {offersBadge && <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />}
         </Box>
       )}
 
-      {verdict !== undefined && view.confirming && (
+      {verdict !== undefined && view.confirming && view.deciding !== true && (
         <Box key="confirm-row" flexDirection="column" marginTop={1}>
           <Text color="warning" wrap="wrap">
             The verdict is {verdict.recommendation}. {primaryLabel(view)}?
@@ -192,14 +305,72 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
 
       {view.decision !== undefined && (
         <Text color={view.decision === 'approved' ? 'success' : 'error'}>
-          {view.decision === 'approved' ? 'Approved' : 'Rejected'}
-          {view.decidedAt === undefined ? '' : ` on ${new Date(view.decidedAt).toISOString().slice(0, 10)}`}. The decision is saved for this exact version; /guard forget clears it.
+          {view.treeHash === undefined ? 'Allowed once' : view.decision === 'approved' ? 'Approved' : 'Rejected'}
+          {view.decidedAt === undefined ? '' : ` on ${new Date(view.decidedAt).toISOString().slice(0, 10)}`}
+          {view.treeHash === undefined ? '. Nothing could be pinned, so nothing is remembered; the same install is held again next time.' : '. The decision is saved for this exact version; /guard forget clears it.'}
         </Text>
       )}
+      {view.decision !== undefined && offersBadge && (
+        <Box key="after-decision" flexDirection="row" gap={1} marginTop={1}>
+          <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />
+        </Box>
+      )}
     </Box>
   )
 }
 
+/**
+ * Closes the pane while it shows this scan. Closing is a step of its own, so
+ * a newer scan may take the pane in that moment: while that scan still runs
+ * or waits for a decision it gets the pane back at once, so its verdict is
+ * never left hidden; one already decided closed the pane itself.
+ */
+async function closeOwn($: EngineInterface, view: GuardView): Promise<void> {
+  const before = await read($, viewAtom).catch(() => null)
+  if (before !== null && before.scanId !== view.scanId) return
+  await $.ui.close({ id: PANE_ID })
+  const after = await read($, viewAtom).catch(() => null)
+  const waiting = after !== null && after.scanId !== view.scanId && after.decision === undefined && after.deciding !== true
+  if (waiting) await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => undefined)
+}
+
+/** What the held install is, in the person's or Claude's own words. */
+function requestLine(request: GuardRequest): string {
+  return request.origin === 'tool' ? `Claude asked to run: ${safeLine(request.args)}` : `Held until you decide: /plugin ${safeLine(request.args)}`
+}
+
+/**
+ * Carries out a held install the person approved. Their own /plugin command
+ * runs again once the version it would install is checked to be the one
+ * scanned; a command Claude ran is Claude's to run again, once the person
+ * tells it to, and its gate checks the version then.
+ */
+async function carryOut($: EngineInterface, held: GuardRequest, view: GuardView): Promise<void> {
+  await closeOwn($, view)
+  if (held.origin === 'tool') {
+    $.ui.toast(`AI Install Guard: approved ${held.label}. Tell Claude to run the install again; it goes through now`)
+    return
+  }
+  // The plugin's own command does not pass through its own gate, so the
+  // version is looked up again here: a commit that moved since the scan is
+  // not installed on the strength of the old one's verdict.
+  const changed = await changedSinceScan(modHost($), view).catch((error: unknown) => `the guard could not look it up again (${error instanceof Error ? error.message : String(error)})`)
+  if (changed !== undefined) {
+    await takePass($, { origin: 'command', args: held.args }).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: nothing was installed: ${safeLine(changed)}. Run /plugin ${safeLine(held.args)} again to scan it`)
+    return
+  }
+  $.ui.toast(`AI Install Guard: approved; installing ${held.label}`)
+  try {
+    await $.command.run({ command: 'plugin', args: held.args })
+  } catch {
+    $.ui.toast(`AI Install Guard: approved, but the install did not start. Run /plugin ${safeLine(held.args)} again; it goes through now`)
+  } finally {
+    // A pass the gate did not use up is not left for a later command.
+    await takePass($, { origin: 'command', args: held.args }).catch(() => undefined)
+  }
+}
+
 function truncate(text: string, room: number): string {
   if (room <= 1) return ''
   return text.length <= room ? text : `${text.slice(0, Math.max(0, room - 1))}…`

package/hooks/guard/passes.ts

@@ -0,0 +1,34 @@
+// Installs the person allowed once although nothing could be pinned: Could
+// not verify, then Install anyway, confirmed. Each pass lets that exact
+// command through one time in this session and is then used up.
+
+import { atom, update } from 'claude-code'
+import type { EngineInterface } from 'claude-code'
+
+import type { GuardPass } from '../../types'
+
+const passesAtom = atom({ plugin: 'ai-install-guard', key: 'passes' } as const, [] as GuardPass[])
+
+/** Passes kept at once; an old one unused falls off. */
+const MAX_PASSES = 20
+
+function samePass(a: GuardPass, b: GuardPass): boolean {
+  return a.origin === b.origin && a.args === b.args
+}
+
+export async function grantPass($: EngineInterface, pass: GuardPass): Promise<void> {
+  await update($, passesAtom, current => [...current.filter(item => !samePass(item, pass)), pass].slice(-MAX_PASSES))
+}
+
+/**
+ * Uses up the pass for this command, if there is one. Finding and removing it
+ * is one write, so two commands at once cannot both use the same pass.
+ */
+export async function takePass($: EngineInterface, pass: GuardPass): Promise<boolean> {
+  let taken = false
+  await update($, passesAtom, latest => {
+    taken = latest.some(item => samePass(item, pass))
+    return taken ? latest.filter(item => !samePass(item, pass)) : latest
+  })
+  return taken
+}

package/hooks/guard/run.ts

@@ -0,0 +1,158 @@
+// A scan shown in the pane: progress while it runs, then the verdict, the
+// stored report Copy report copies and the view /guard report reopens.
+
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface } from 'claude-code'
+
+import type { GuardAction, GuardRequest, GuardView } from '../../types'
+import { modHost } from '../mod-host'
+import type { RemoteSpec } from '../scan/remote'
+import { formatReport } from '../scan/report'
+import { safeLine } from '../scan/safe-text'
+import { scanFolder, scanRemote, type ScanReport } from '../scan/scan'
+import { decisionFor, saveLastView, saveReport } from './decisions'
+import { PANE_ID, scanningView, viewOf } from './view'
+
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
+
+export type ScanHow = { remote: RemoteSpec } | { folder: string }
+
+export type ShowOptions = {
+  action: GuardAction
+  /** The install the pane's Install button carries out, for a held install. */
+  request?: GuardRequest
+  lookups: boolean
+}
+
+export type Shown =
+  | { kind: 'done'; report: ScanReport; view: GuardView; text: string; placed: boolean; superseded: boolean }
+  | { kind: 'failed'; reason: string; view: GuardView; placed: boolean; superseded: boolean }
+
+let scans = 0
+
+/**
+ * A name for one scan, unique in this session, that sorts after every scan
+ * started before it: the time, then a count for scans in the same moment.
+ */
+function newScanId(): string {
+  scans += 1
+  return `${Date.now().toString(36).padStart(10, '0')}-${scans.toString(36).padStart(6, '0')}`
+}
+
+/** Opens the pane on a scan of `how`, and leaves the verdict in it. */
+export async function showScan($: EngineInterface, target: string, how: ScanHow | (() => Promise<ScanHow>), options: ShowOptions): Promise<Shown> {
+  // Named before anything waits, so a scan asked for later is always the newer one.
+  const scanId = newScanId()
+  const host = modHost($)
+  const opened = await openPane($)
+  const scanning = { ...withRequest(scanningView(target, options.action), options.request), scanId }
+  if (!(await takePane($, scanning))) {
+    return { kind: 'failed', reason: `Could not verify ${safeLine(target)}: a newer scan has the pane`, view: scanning, placed: opened, superseded: true }
+  }
+  $.ui.status(`AI Install Guard: scanning ${safeLine(target)}`)
+  try {
+    const scanOptions = {
+      lookups: options.lookups,
+      // Stage names can carry a candidate's own words (a plugin's name).
+      onStage: (stage: string) => update($, viewAtom, current => (current === null || current.scanId !== scanId ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
+    }
+    const resolved = typeof how === 'function' ? await how() : how
+    const report = 'remote' in resolved ? await scanRemote(host, target, resolved.remote, scanOptions) : await scanFolder(host, target, resolved.folder, scanOptions)
+    // A tree you already decided on shows that decision, not the buttons
+    // again, unless it now judges worse than when you approved it.
+    const earlier = report.inventory === undefined ? undefined : await decisionFor($, { treeHash: report.inventory.treeHash, sha: report.source?.sha }, report.verdict.kind).catch(() => undefined)
+    const base = { ...withRequest(viewOf(report, options.action), options.request), scanId }
+    const view = earlier === undefined ? base : { ...base, decision: earlier.decision, decidedAt: earlier.decidedAt }
+    const text = formatReport(report, { details: true })
+    // A scan started since owns the pane now: this one leaves it, its report
+    // and the reopened report alone, so no press lands on the wrong scan.
+    if (!(await owns($, scanId))) return { kind: 'done', report, view, text, placed: opened, superseded: true }
+    // The report is stored under this scan's name before the pane shows the
+    // verdict, so Copy report copies it, and never another scan's.
+    await saveReport($, scanId, text)
+    if (!(await showOwn($, view))) return { kind: 'done', report, view, text, placed: opened, superseded: true }
+    $.ui.toast(`AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}`)
+    return { kind: 'done', report, view, text, placed: opened, superseded: false }
+  } catch (error) {
+    const reason = `Could not verify ${safeLine(target)}: ${safeLine(error instanceof Error ? error.message : String(error))}`
+    const failed = await showFailure($, target, reason, options, scanId)
+    return { kind: 'failed', reason, view: failed.view, placed: opened, superseded: !failed.shown }
+  } finally {
+    $.ui.status(undefined)
+  }
+}
+
+/**
+ * Opens the pane on an install the guard could not scan: Could not verify,
+ * with the reason, and Install anyway behind a second confirmation.
+ * `superseded` says a newer scan has the pane instead.
+ */
+export async function showUnverified($: EngineInterface, target: string, reason: string, options: ShowOptions): Promise<{ view: GuardView; placed: boolean; superseded: boolean }> {
+  const scanId = newScanId()
+  const placed = await openPane($)
+  const scanning = { ...withRequest(scanningView(target, options.action), options.request), scanId }
+  if (!(await takePane($, scanning))) return { view: scanning, placed, superseded: true }
+  const failed = await showFailure($, target, `Could not verify ${safeLine(target)}: ${safeLine(reason)}`, options, scanId)
+  return { view: failed.view, placed, superseded: !failed.shown }
+}
+
+/**
+ * The pane, and the report /guard report reopens, show a failure: never a
+ * scanning pane, and never an older verdict in its place. Only while this
+ * scan still owns the pane; `shown` says whether it did.
+ */
+async function showFailure($: EngineInterface, target: string, reason: string, options: ShowOptions, scanId: string): Promise<{ view: GuardView; shown: boolean }> {
+  const failed: GuardView = {
+    ...withRequest(scanningView(target, options.action), options.request),
+    scanId,
+    stage: '',
+    verdict: { kind: 'unverified', recommendation: 'Could not verify', reasons: [reason], counts: { pass: 0, warn: 0, fail: 0, info: 0 } },
+  }
+  if (!(await owns($, scanId).catch(() => false))) return { view: failed, shown: false }
+  await saveReport($, scanId, reason)
+  return { view: failed, shown: await showOwn($, failed).catch(() => false) }
+}
+
+/** Whether the pane still shows this scan. */
+async function owns($: EngineInterface, scanId: string): Promise<boolean> {
+  return (await read($, viewAtom))?.scanId === scanId
+}
+
+/** Takes the pane for a scan just started, unless a newer scan already has it. */
+async function takePane($: EngineInterface, view: GuardView): Promise<boolean> {
+  let taken = false
+  await update($, viewAtom, current => {
+    taken = current === null || current.scanId === undefined || view.scanId === undefined || current.scanId <= view.scanId
+    return taken ? view : current
+  })
+  return taken
+}
+
+/**
+ * Shows a scan's finished view while the pane still shows that scan, and
+ * saves it for /guard report. Should a newer scan take the pane while it is
+ * saved, the newer view is saved instead, so the reopened report is always
+ * the pane's.
+ */
+async function showOwn($: EngineInterface, view: GuardView): Promise<boolean> {
+  let shown = false
+  await update($, viewAtom, current => {
+    shown = current?.scanId === view.scanId
+    return shown ? view : current
+  })
+  if (!shown) return false
+  await saveLastView($, view).catch(() => undefined)
+  const now = await read($, viewAtom).catch(() => null)
+  if (now !== null && now.scanId !== view.scanId) await saveLastView($, now).catch(() => undefined)
+  return true
+}
+
+/** Opens the pane; false where no surface can show it (a headless run). */
+async function openPane($: EngineInterface): Promise<boolean> {
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  return opened.isPlaced
+}
+
+function withRequest(view: GuardView, request: GuardRequest | undefined): GuardView {
+  return request === undefined ? view : { ...view, request }
+}

package/hooks/guard/view.ts

@@ -32,7 +32,15 @@ export function viewOf(report: ScanReport, action: GuardAction): GuardView {
     },
     rows: report.results.map(rowOf),
     kind: report.kind,
-    root: report.inventory === undefined ? undefined : safeLine(report.inventory.root),
+    // A remote scan's folder is a temporary one: its source names it instead.
+    root:
+      report.source !== undefined
+        ? sourceRoot(report.source.url, report.source.subdir)
+        : report.inventory === undefined
+          ? undefined
+          : safeLine(report.inventory.root),
+    sha: report.source?.sha,
+    ...(report.source?.subdir === undefined ? {} : { subdir: encodeFolder(report.source.subdir) }),
     treeHash: report.inventory?.treeHash,
     expanded: [],
     details: false,
@@ -40,6 +48,11 @@ export function viewOf(report: ScanReport, action: GuardAction): GuardView {
   }
 }
 
+/** How a decision names a remote source: its address, and the folder in it after `#`. */
+export function sourceRoot(url: string, subdir: string | undefined): string {
+  return safeLine(`${url}${subdir === undefined ? '' : `#${subdir}`}`)
+}
+
 function rowOf(result: CheckResult): GuardRow {
   return {
     id: result.id,
@@ -54,6 +67,7 @@ function rowOf(result: CheckResult): GuardRow {
     })),
     more: Math.max(0, result.evidence.length - EVIDENCE_PER_ROW),
     advice: result.advice,
+    ...(result.summary === undefined || result.summary.length === 0 ? {} : { summary: result.summary.slice(0, 8).map(line => clip(safeLine(redactSecrets(line)))) }),
   }
 }
 
@@ -67,3 +81,12 @@ export function primaryLabel(view: GuardView): string {
   const verb = view.action === 'install' ? 'Install' : 'Approve'
   return needsConfirmation(view) ? `${verb} anyway` : verb
 }
+
+/**
+ * A folder name as the pane and a badge show it: whole characters other than
+ * letters, digits and `_ . / -` percent-encoded, so the exact folder stays
+ * named and nothing in it can be read as markup or hide itself.
+ */
+export function encodeFolder(folder: string): string {
+  return folder.replace(/[^\w./-]/gu, char => [...new TextEncoder().encode(char)].map(byte => `%${byte.toString(16).toUpperCase().padStart(2, '0')}`).join(''))
+}

package/hooks/mod-host.ts

@@ -27,5 +27,6 @@ export function modHost($: EngineInterface): Host {
       throw new Error(`could not read the link ${path}`)
     },
     run: (argv, options) => $.process.run(argv, options),
+    fetch: (url, init) => $.http.fetch(url, init),
   }
 }