@cat-factory/app 0.239.0 → 0.241.1

package/app/components/layout/AccountAuditLog.vue

@@ -0,0 +1,148 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
+import type { AuditEventWire } from '@cat-factory/contracts'
+import { actorLabel, describeEvent } from './AccountAuditLog.logic'
+
+// The account audit log: who did what, when, for the privileged actions an account admin is
+// answerable for. Read-only by construction — the store exposes no mutation and the backend has
+// no update or delete surface besides the retention sweep.
+//
+// The whole design rests on one rule: the backend records machine-readable FIELDS and never
+// prose, because a row is persisted and English written today could never be re-rendered for a
+// reader in another locale years later. So every sentence here is composed from a translated key
+// plus the row's `details`. The composition itself lives in `AccountAuditLog.logic.ts`, where
+// the two cases a happy-path render never reaches (a retired action, an unreadable `details`
+// blob) can be asserted without mounting anything.
+const props = defineProps<{ accountId: string }>()
+
+const accounts = useAccountsStore()
+const toast = useToast()
+const { t } = useI18n()
+
+const events = computed(() => accounts.auditEvents)
+const hasMore = computed(() => accounts.auditCursor !== null)
+const loading = computed(() => accounts.auditLoading)
+/**
+ * The load FAILED, as distinct from an empty log. An audit viewer that renders a store outage as
+ * "nothing has happened" tells an admin the exact opposite of the truth, so the two states have
+ * separate renderings and this one never silently resolves to an empty list.
+ */
+const loadError = ref<string | null>(null)
+
+async function load() {
+  loadError.value = null
+  try {
+    await accounts.loadAuditEvents(props.accountId)
+  } catch (e) {
+    loadError.value = apiErrorEnvelope(e)?.message ?? (e instanceof Error ? e.message : String(e))
+  }
+}
+
+async function loadMore() {
+  try {
+    await accounts.loadMoreAuditEvents(props.accountId)
+  } catch (e) {
+    toast.add({
+      title: t('layout.auditLog.errors.loadMore'),
+      description: apiErrorEnvelope(e)?.message ?? (e instanceof Error ? e.message : String(e)),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  }
+}
+
+onMounted(() => void load())
+watch(
+  () => props.accountId,
+  (id) => {
+    if (id) void load()
+  },
+)
+/**
+ * Something elsewhere in the app wrote a row this feed does not have yet (today: an admin forcing
+ * a member's sessions to end, whose only lasting trace IS that row).
+ *
+ * The reload lands here rather than in the writer for two reasons that are one reason: this
+ * component is the only place that knows the feed is being shown, and it is the only place that
+ * renders a failed read as a failed read. A writer that awaited the refresh itself would report
+ * its own success or failure by whether an unrelated GET succeeded.
+ */
+watch(
+  () => accounts.auditStale,
+  (stale) => {
+    if (stale) void load()
+  },
+)
+
+/**
+ * The composition helpers, bound to this component's i18n instance. They take `t` as a parameter
+ * so the logic module stays pure and testable without an i18n runtime; binding here keeps the
+ * template free of the plumbing.
+ */
+const describe = (event: AuditEventWire) => describeEvent(event, t)
+const actor = (event: AuditEventWire) => actorLabel(event, t)
+
+/** Absolute local time: an audit reader is answering "when exactly", never "how long ago". */
+function timestamp(at: number): string {
+  return new Date(at).toLocaleString()
+}
+</script>
+
+<template>
+  <section class="rounded-md border border-slate-800 bg-slate-800/40 p-4">
+    <div class="mb-3 flex items-start justify-between gap-3">
+      <div>
+        <h3 class="font-semibold text-white">{{ t('layout.auditLog.title') }}</h3>
+        <p class="mt-1 text-slate-400">{{ t('layout.auditLog.description') }}</p>
+      </div>
+      <UButton
+        size="xs"
+        color="neutral"
+        variant="ghost"
+        icon="i-lucide-refresh-cw"
+        :loading="loading"
+        :aria-label="t('layout.auditLog.refresh')"
+        data-testid="audit-log-refresh"
+        @click="load()"
+      />
+    </div>
+
+    <!-- A failed load is NOT an empty log; it says so and offers the retry. -->
+    <p v-if="loadError" class="text-red-400" data-testid="audit-log-error">
+      {{ t('layout.auditLog.errors.load') }}
+      <span class="text-slate-400">{{ loadError }}</span>
+    </p>
+
+    <p v-else-if="events.length === 0 && !loading" class="text-slate-400">
+      {{ t('layout.auditLog.empty') }}
+    </p>
+
+    <ol v-else class="space-y-2" data-testid="audit-log-list">
+      <li
+        v-for="event in events"
+        :key="event.id"
+        class="rounded border border-slate-800 bg-slate-900/40 px-3 py-2"
+      >
+        <div class="flex flex-wrap items-baseline gap-x-2">
+          <span class="font-medium text-white">{{ actor(event) }}</span>
+          <span class="text-slate-300">{{ describe(event) }}</span>
+        </div>
+        <div class="mt-1 text-xs text-slate-500">{{ timestamp(event.at) }}</div>
+      </li>
+    </ol>
+
+    <UButton
+      v-if="hasMore && !loadError"
+      class="mt-3"
+      size="xs"
+      color="neutral"
+      variant="soft"
+      :loading="loading"
+      data-testid="audit-log-load-more"
+      @click="loadMore()"
+    >
+      {{ t('layout.auditLog.loadMore') }}
+    </UButton>
+  </section>
+</template>

package/app/components/layout/AccountTeamSettings.vue

@@ -3,6 +3,7 @@ import { computed, onMounted, ref, watch } from 'vue'
 import { apiErrorEnvelope } from '~/composables/api/errors'
 import type { AccountRole } from '~/types/domain'
 import type { InvitationStatus } from '@cat-factory/contracts'
+import AccountAuditLog from '~/components/layout/AccountAuditLog.vue'
 import AccountDeploymentSettings from '~/components/layout/AccountDeploymentSettings.vue'
 import AccountModelPolicySettings from '~/components/layout/AccountModelPolicySettings.vue'
 import AccountPlatformAlertSettings from '~/components/layout/AccountPlatformAlertSettings.vue'
@@ -16,6 +17,7 @@ import SecretInput from '~/components/common/SecretInput.vue'
 const props = defineProps<{ accountId: string }>()
 
 const accounts = useAccountsStore()
+const uiMode = useUiModeStore()
 const auth = useAuthStore()
 const toast = useToast()
 const { t, te } = useI18n()
@@ -66,6 +68,20 @@ async function updateMemberRoles(userId: string, roles: AccountRole[]) {
   }
 }
 
+/**
+ * End every session a member holds. Their roles are untouched, so nothing in the roster changes —
+ * which is why the confirmation names the person: there is no visible after-state to check.
+ */
+async function revokeSessions(userId: string, label: string) {
+  if (!(await confirmAction('revoke', label))) return
+  try {
+    await accounts.revokeMemberSessions(props.accountId, userId)
+    toast.add({ title: t('layout.accountTeam.members.sessionsRevoked'), icon: 'i-lucide-check' })
+  } catch (e) {
+    notifyError(t('layout.accountTeam.errors.revokeSessions'), e)
+  }
+}
+
 function notifyError(title: string, e: unknown) {
   toast.add({
     title,
@@ -232,6 +248,20 @@ async function disconnectEmail() {
           <span v-else class="text-xs uppercase tracking-wide text-slate-400">
             {{ m.roles.join(', ') }}
           </span>
+          <!-- Offboarding: end every session this member holds, leaving their membership and
+               roles alone. Confirmed, because it is not undoable from here (the person simply
+               signs in again) and because it is the sort of thing a mis-click should not do. -->
+          <UButton
+            v-if="isAdmin"
+            size="xs"
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-log-out"
+            :title="t('layout.accountTeam.members.revokeSessions')"
+            :aria-label="t('layout.accountTeam.members.revokeSessions')"
+            data-testid="revoke-member-sessions"
+            @click="revokeSessions(m.userId, m.name || m.email || m.userId)"
+          />
         </li>
         <li v-if="accounts.members.length === 0" class="text-slate-500">
           {{ t('layout.accountTeam.members.empty') }}
@@ -355,5 +385,14 @@ async function disconnectEmail() {
     <section v-if="isAdmin">
       <AccountRunCredentialSettings :account-id="accountId" />
     </section>
+
+    <!-- The account audit log (admin-only, ADVANCED tier). Advanced rather than basic because
+         reading who changed what is a governance task, not part of the everyday delivery loop —
+         and unlike an override field there is no default it hides, so hiding it withholds nothing
+         a basic-tier user would otherwise be acting on. The backend gates it too; this only
+         decides whether the surface exists. -->
+    <section v-if="isAdmin && uiMode.isAdvanced">
+      <AccountAuditLog :account-id="accountId" />
+    </section>
   </div>
 </template>

package/app/components/panels/MergerResultView.vue

@@ -64,6 +64,7 @@ const REASON_KEYS: Record<MergeDecision['reason'], string> = {
   within_thresholds: 'panels.mergerResult.reason.within_thresholds',
   exceeded_thresholds: 'panels.mergerResult.reason.exceeded_thresholds',
   auto_merge_disabled: 'panels.mergerResult.reason.auto_merge_disabled',
+  no_policy_configured: 'panels.mergerResult.reason.no_policy_configured',
   no_rationale: 'panels.mergerResult.reason.no_rationale',
   no_assessment: 'panels.mergerResult.reason.no_assessment',
   merge_failed: 'panels.mergerResult.reason.merge_failed',

package/app/components/panels/StepToolServers.logic.spec.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { KNOWN_REASONS, REASON_KEY, reasonText } from './StepToolServers.logic'
+import {
+  KNOWN_REASONS,
+  REASON_KEY,
+  REMEDY_KEY,
+  reasonText,
+  remedyText,
+} from './StepToolServers.logic'
 import type { ToolServerUnavailableReason } from '~/types/toolServers'
 
 /**
@@ -49,6 +55,40 @@ describe('tool-server unavailability reasons', () => {
   })
 })
 
+/**
+ * The remedy is the half an operator acts on. A diagnosis with no next step is where this surface
+ * started: the reason was already stated to the AGENT in its prompt, and stating it to a person
+ * changes nothing unless it also names what to change.
+ */
+describe('tool-server unavailability remedies', () => {
+  it('gives every reason in the wire vocabulary a remedy of its own', () => {
+    expect(Object.keys(REMEDY_KEY).sort()).toEqual([...KNOWN_REASONS].sort())
+  })
+
+  it('never points two reasons at one remedy', () => {
+    // The vocabulary exists BECAUSE each member needs a different fix, so two members sharing a
+    // remedy line means either the copy is wrong or the split was.
+    const keys = Object.values(REMEDY_KEY)
+    expect(new Set(keys).size).toBe(keys.length)
+  })
+
+  it('never reuses a reason line as a remedy', () => {
+    // The two are rendered together. A remedy pointing at the reason's own key would render the
+    // diagnosis twice and read as advice.
+    const reasons = new Set(Object.values(REASON_KEY))
+    for (const key of Object.values(REMEDY_KEY)) expect(reasons.has(key)).toBe(false)
+  })
+
+  it('offers no remedy for a retired reason, rather than guessing one', () => {
+    // The build knows the code was recorded and not what it meant. Any remedy here would name a
+    // surface picked from a member the operator may never have hit, and the reason line already
+    // states the raw code, which is the whole of what is known.
+    for (const reason of ['legacy_reason', 'constructor', '__proto__']) {
+      expect(remedyText(reason as ToolServerUnavailableReason, (key) => key)).toBeNull()
+    }
+  })
+})
+
 /** Every `t` call `reasonText` made, so the assertion is about the key it CHOSE, not the copy. */
 function render(reason: string): { key: string; params?: Record<string, unknown> }[] {
   const seen: { key: string; params?: Record<string, unknown> }[] = []

package/app/components/panels/StepToolServers.logic.ts

@@ -25,6 +25,29 @@ export const REASON_KEY: Record<ToolServerUnavailableReason, string> = {
   over_budget: 'panels.stepDetail.toolServers.reason.overBudget',
 }
 
+/**
+ * The i18n key per reason for the REMEDY line: what an operator has to change to get the server
+ * wired next run. Exhaustive on the same vocabulary and for the same reason as {@link REASON_KEY}.
+ *
+ * Split from the reason rather than folded into one sentence because the two answer different
+ * questions and only one of them is stable: the reason states what the dispatch decided and is a
+ * fact about that run forever, while the remedy names a surface this deployment happens to offer
+ * (the Infrastructure window, a declaration in deployment code). The split is also the vocabulary's
+ * own justification, since every member exists precisely because it needs a DIFFERENT fix
+ * (`docs`' table in `backend/docs/mcp-tool-servers.md` is the same mapping for a reader who never
+ * opens the SPA); a reason with no remedy leaves the operator holding an accurate diagnosis and no
+ * next step, which is the state this surface was built to end.
+ */
+export const REMEDY_KEY: Record<ToolServerUnavailableReason, string> = {
+  harness_unsupported: 'panels.stepDetail.toolServers.remedy.harnessUnsupported',
+  transport_unsupported: 'panels.stepDetail.toolServers.remedy.transportUnsupported',
+  missing_secret: 'panels.stepDetail.toolServers.remedy.missingSecret',
+  reserved_secret: 'panels.stepDetail.toolServers.remedy.reservedSecret',
+  oauth_not_connected: 'panels.stepDetail.toolServers.remedy.oauthNotConnected',
+  oauth_token_failed: 'panels.stepDetail.toolServers.remedy.oauthTokenFailed',
+  over_budget: 'panels.stepDetail.toolServers.remedy.overBudget',
+}
+
 /** The reason vocabulary as the SCHEMA states it: what a parity assertion grades {@link REASON_KEY} against. */
 export const KNOWN_REASONS = toolServerUnavailableReasonSchema.options
 
@@ -56,3 +79,18 @@ export function reasonText(
     ? t(REASON_KEY[reason])
     : t('panels.stepDetail.toolServers.reason.unknown', { reason })
 }
+
+/**
+ * Render the remedy for one reason, or `null` when there is none to give.
+ *
+ * `null` is the honest answer for a RETIRED member and the reason it is not folded into
+ * {@link reasonText}: this build knows the code was recorded and does not know what it meant, so it
+ * cannot name a surface to change without guessing which current member the operator should act
+ * on. The reason line already names the raw code, which is the whole of what is known.
+ */
+export function remedyText(
+  reason: ToolServerUnavailableReason,
+  t: (key: string, params?: Record<string, unknown>) => string,
+): string | null {
+  return isKnownReason(reason) ? t(REMEDY_KEY[reason]) : null
+}

package/app/components/panels/StepToolServers.vue

@@ -15,8 +15,8 @@
 // the Infrastructure window is where declarations are read; rendering it here would put an empty
 // section on every step of every run to say nothing happened. The distinction absent-vs-empty is
 // still carried on the wire and answered by the debug API, which is where a reader asking it looks.
-import type { StepToolServers, ToolServerUnavailableReason } from '~/types/toolServers'
-import { reasonText } from '~/components/panels/StepToolServers.logic'
+import type { StepToolServers } from '~/types/toolServers'
+import { reasonText, remedyText } from '~/components/panels/StepToolServers.logic'
 import { agentKindMeta } from '~/utils/catalog'
 
 const props = defineProps<{
@@ -44,9 +44,19 @@ const dispatchedAs = computed(() =>
     : null,
 )
 
-/** Bind this component's i18n instance onto the pure mapping (see `StepToolServers.logic.ts`). */
-const describeReason = (reason: ToolServerUnavailableReason) =>
-  reasonText(reason, (key, params) => t(key, params ?? {}))
+/**
+ * Each dropped server with both halves of its answer resolved: WHY it was dropped, and what to
+ * change so the next run gets it. Bound here rather than called from the template so the pure
+ * mappings (`StepToolServers.logic.ts`) stay assertable without mounting a component, and so a
+ * retired member's absent remedy is decided once instead of on every re-render.
+ */
+const drops = computed(() =>
+  props.toolServers.unavailable.map((server) => ({
+    ...server,
+    reasonText: reasonText(server.reason, (key, params) => t(key, params ?? {})),
+    remedy: remedyText(server.reason, (key, params) => t(key, params ?? {})),
+  })),
+)
 </script>
 
 <template>
@@ -87,9 +97,9 @@ const describeReason = (reason: ToolServerUnavailableReason) =>
       </li>
     </ul>
 
-    <ul v-if="toolServers.unavailable.length" class="mt-2 space-y-1">
+    <ul v-if="drops.length" class="mt-2 space-y-1.5">
       <li
-        v-for="server in toolServers.unavailable"
+        v-for="server in drops"
         :key="server.id"
         data-testid="step-tool-server-unavailable"
         class="flex items-start gap-1.5 text-[12px] text-slate-300"
@@ -97,7 +107,17 @@ const describeReason = (reason: ToolServerUnavailableReason) =>
         <UIcon name="i-lucide-plug-zap" class="mt-0.5 h-3.5 w-3.5 shrink-0 text-amber-400/80" />
         <span>
           <span class="font-medium text-slate-200">{{ server.label || server.id }}</span>
-          <span class="text-slate-400"> {{ describeReason(server.reason) }}</span>
+          <span class="text-slate-400"> {{ server.reasonText }}</span>
+          <!--
+            Absent for a reason this build no longer recognises: it knows the code was recorded and
+            not what it meant, so there is no surface it can honestly send an operator to.
+          -->
+          <span
+            v-if="server.remedy"
+            data-testid="step-tool-server-remedy"
+            class="mt-0.5 block text-slate-500"
+            >{{ server.remedy }}</span
+          >
         </span>
       </li>
     </ul>

package/app/components/riskPolicy/RiskPolicyPicker.logic.ts

@@ -78,7 +78,13 @@ export function refusedRiskPolicySelections(input: {
   if (!from) return refusals
   const judge = (id: string, to: RiskPolicy | null) => {
     if (!to) return
-    const refusal = refuseRiskPolicySelection({ from, to, actor: input.actor })
+    // The same actor on both sides: a picker only ever offers the library of the ONE workspace the
+    // task is homed in, so both policies are in force there and the editor is the same person to
+    // each. The two-sided shape exists for the cross-home move, which the picker cannot express.
+    const refusal = refuseRiskPolicySelection({
+      from: { policy: from, actor: input.actor },
+      to: { policy: to, actor: input.actor },
+    })
     if (refusal) refusals.set(id, refusal)
   }
   judge('', input.defaultPolicy)

package/app/composables/api/accounts.ts

@@ -7,9 +7,11 @@ import {
   getAccountSettingsContract,
   getEmailConnectionContract,
   listAccountMembersContract,
+  listAuditEventsContract,
   listAccountsContract,
   listInvitationsContract,
   revokeInvitationContract,
+  revokeMemberSessionsContract,
   setMemberRolesContract,
   testEmailContract,
   updateAccountContract,
@@ -42,6 +44,16 @@ export function accountsApi({ send }: ApiContext) {
     setMemberRoles: (accountId: string, userId: string, roles: AccountRole[]) =>
       send(setMemberRolesContract, { pathParams: { accountId, userId }, body: { roles } }),
 
+    // End every session a member holds, without touching their membership or roles: the
+    // offboarding lever for a departure or a lost device. Admin-only (enforced server-side).
+    revokeMemberSessions: (accountId: string, userId: string) =>
+      send(revokeMemberSessionsContract, { pathParams: { accountId, userId } }),
+
+    // One page of the account's audit log, newest first. `cursor` is opaque and comes straight
+    // back from a previous page; the server clamps `limit`.
+    listAuditEvents: (accountId: string, query: { cursor?: string; limit?: number } = {}) =>
+      send(listAuditEventsContract, { pathParams: { accountId }, queryParams: query }),
+
     // Invitations: invite teammates by email into an org account.
     listInvitations: (accountId: string) =>
       send(listInvitationsContract, { pathParams: { accountId } }),

package/app/composables/api/documents.ts

@@ -9,6 +9,7 @@ import {
   listDocumentsContract,
   listDocumentSourcesContract,
   planDocumentContract,
+  refreshDocumentContract,
   resolveDocumentRefContract,
   searchDocumentsContract,
   spawnDocumentContract,
@@ -61,6 +62,14 @@ export function documentsApi({ send, ws }: ApiContext) {
     importDocument: (workspaceId: string, source: DocumentSourceKind, body: { ref: string }) =>
       send(importDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
+    // Re-confirm one stored document against its source now, pulling the new body if the page
+    // moved. Keyed by `(source, externalId)` in the BODY, because the target is a stored row
+    // rather than a provider surface, and an `externalId` carries slashes.
+    refreshDocument: (
+      workspaceId: string,
+      body: { source: DocumentSourceKind; externalId: string },
+    ) => send(refreshDocumentContract, { pathPrefix: ws(workspaceId), body }),
+
     searchDocumentSource: (workspaceId: string, source: DocumentSourceKind, query: string) =>
       send(searchDocumentsContract, {
         pathPrefix: ws(workspaceId),

package/app/composables/useDocumentFreshness.ts

@@ -0,0 +1,111 @@
+import { ref } from 'vue'
+import type {
+  DocumentFreshness,
+  DocumentOrigin,
+  DocumentSourceKind,
+  RefreshedDocumentView,
+  SourceDocument,
+} from '~/types/domain'
+
+/**
+ * A verdict plus WHEN it was reached. The two are one value because either alone is a half-truth:
+ * the verdict says the copy matched the source, and only the stamp says how long ago that was true
+ * of a page someone else is still editing. A surface handed the verdict without the stamp can only
+ * render it as "just now", which is exactly the false confidence this feature exists to remove: an
+ * hour-old confirmation would keep showing a green check.
+ *
+ * `checkedAt` is stamped where the answer LANDS rather than on the server, so it is on the clock the
+ * person reading it is looking at. A skewed browser clock renders its own time consistently; a
+ * server stamp would render "checked at 14:32" to someone whose clock says 14:29.
+ */
+export interface DatedFreshness {
+  readonly verdict: DocumentFreshness
+  /** Epoch ms, on the reader's own clock. */
+  readonly checkedAt: number
+}
+
+/**
+ * The "is the copy on the board still the current one" half of the documents store: the per-document
+ * verdict a manual check produced, the in-flight flags, and the call that produces both.
+ *
+ * Its own collaborator rather than more lines in the store because it holds a DIFFERENT KIND of
+ * state from everything around it. The store's other state is the projection itself (sources,
+ * connections, imported rows), which the backend owns and the SPA mirrors; a freshness verdict is a
+ * statement about one MOMENT ("as of the click, this was the live revision"), owned by nothing and
+ * true of no row. Keeping it separate is what makes the three rules below expressible at all instead
+ * of folding into the document list and quietly becoming a claim about it.
+ *
+ * The rules, in one place so no surface can get half of them right:
+ *
+ *   - **An absent verdict means "nobody has asked", never "unknown".** Listing documents
+ *     deliberately probes nothing (confirming costs a round trip to the source per page), so a
+ *     freshly imported document has no verdict and is perfectly fine, which is not the same fact as
+ *     a check that ran and could not conclude.
+ *   - **The verdict never merges into the row.** A refresh that finds nothing changed writes
+ *     nothing, so `syncedAt` legitimately stays where it was; folding a confirmation into the row
+ *     would either claim a write that never happened or leave the confirmation sitting on a body
+ *     the source has moved past since.
+ *   - **A verdict belongs to the BOARD it was asked on.** The same Figma file can be imported into
+ *     two boards, and the pair `(source, externalId)` is identical in both, so a map keyed by that
+ *     alone would render board A's "confirmed, revision v3" against board B's row, which nobody
+ *     checked, breaking the first rule in the one direction that cannot be noticed. Hence
+ *     {@link keyOf}, and hence the read below asking for the ACTIVE board each time rather than
+ *     capturing it once.
+ */
+export function useDocumentFreshness(deps: {
+  /**
+   * The board these maps are ABOUT. A getter rather than a value because it changes under a
+   * long-lived store, and every read has to see the change.
+   */
+  workspaceId: () => string | null
+  /** Ask the backend to re-confirm one document. Only a CONNECTABLE source can be asked. */
+  refresh: (source: DocumentSourceKind, externalId: string) => Promise<RefreshedDocumentView>
+  /** Reconcile the (possibly rewritten) row back into the list every surface reads. */
+  onRefreshed: (document: SourceDocument) => void
+}): {
+  refresh: (source: DocumentSourceKind, externalId: string) => Promise<RefreshedDocumentView>
+  freshnessFor: (source: DocumentOrigin, externalId: string) => DatedFreshness | undefined
+  isRefreshing: (source: DocumentOrigin, externalId: string) => boolean
+} {
+  const freshness = ref<Record<string, DatedFreshness>>({})
+  const refreshing = ref<Record<string, boolean>>({})
+  const keyOf = (workspaceId: string | null, source: DocumentOrigin, externalId: string) =>
+    `${workspaceId ?? ''}:${source}:${externalId}`
+
+  async function refresh(source: DocumentSourceKind, externalId: string) {
+    // Captured ONCE, at the start, and used for every write below: a check that outlives a board
+    // switch must land under the board it was asked on, not whichever one is showing when it
+    // returns. Re-reading the getter at the end would file the answer under a board that never
+    // asked, which is the same wrong render the key exists to prevent, just harder to reproduce.
+    const board = deps.workspaceId()
+    const key = keyOf(board, source, externalId)
+    refreshing.value = { ...refreshing.value, [key]: true }
+    try {
+      const result = await deps.refresh(source, externalId)
+      // The document LIST is the active board's, and it is not keyed by board, so a row can only be
+      // merged into it while that board is still the one showing. The verdict is filed either way:
+      // it stays true of the board it was asked on, and switching back should not have to re-ask.
+      if (deps.workspaceId() === board) deps.onRefreshed(result.document)
+      freshness.value = {
+        ...freshness.value,
+        [key]: { verdict: result.freshness, checkedAt: Date.now() },
+      }
+      return result
+    } finally {
+      // Cleared however the call ended. A failure that left the flag set would disable the button
+      // that is the whole remedy, so the person could not try again.
+      const { [key]: _settled, ...rest } = refreshing.value
+      refreshing.value = rest
+    }
+  }
+
+  // The verdict map itself stays INSIDE: a caller that could write it could record a conclusion
+  // nobody reached, which is the one thing this vocabulary exists to make impossible.
+  return {
+    refresh,
+    freshnessFor: (source, externalId) =>
+      freshness.value[keyOf(deps.workspaceId(), source, externalId)],
+    isRefreshing: (source, externalId) =>
+      !!refreshing.value[keyOf(deps.workspaceId(), source, externalId)],
+  }
+}

package/app/stores/accounts.audit.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest'
+import { useAccountsStore } from '~/stores/accounts'
+
+/**
+ * The audit feed and the one write that produces a row in it.
+ *
+ * What these guard is the seam between them. Forcing a member's sessions to end leaves nothing
+ * visible in the roster — the row IS the trace — so the feed has to be brought back into step.
+ * Doing that by awaiting the read inside the write is what conflated the two: a revocation that
+ * had already succeeded was reported to the admin as "could not sign the member out" whenever the
+ * follow-up read failed, which on a deployment with no audit store wired is every time.
+ */
+describe('accounts store — audit feed and forced revocation', () => {
+  it('reports a successful revocation as successful even when the audit read is broken', async () => {
+    // The 204 landed. Nothing about a failing GET afterwards changes that, and telling an admin
+    // otherwise invites them to do it again or to escalate a problem they do not have.
+    const listAuditEvents = vi.fn(() => Promise.reject(new Error('audit store down')))
+    const revokeMemberSessions = vi.fn(() => Promise.resolve())
+    vi.stubGlobal('useApi', () => ({ listAuditEvents, revokeMemberSessions }))
+
+    const store = useAccountsStore()
+    await expect(store.revokeMemberSessions('acc_1', 'usr_2')).resolves.toBeUndefined()
+    expect(revokeMemberSessions).toHaveBeenCalledWith('acc_1', 'usr_2')
+  })
+
+  it('does not read the audit log from the write path at all', async () => {
+    // The write must not pay for a read nothing may be showing: the panel is absent in basic mode
+    // and on any deployment that wires no audit store. Marking the feed stale leaves the reload to
+    // the viewer, which is the only place that knows it is on screen and the only place that
+    // renders a failed read AS a failed read.
+    const listAuditEvents = vi.fn(() => Promise.resolve({ events: [], nextCursor: null }))
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents,
+      revokeMemberSessions: () => Promise.resolve(),
+    }))
+
+    const store = useAccountsStore()
+    await store.revokeMemberSessions('acc_1', 'usr_2')
+
+    expect(listAuditEvents).not.toHaveBeenCalled()
+    expect(store.auditStale).toBe(true)
+  })
+
+  it('propagates a failed revocation, which IS the caller’s business', async () => {
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents: () => Promise.resolve({ events: [], nextCursor: null }),
+      revokeMemberSessions: () => Promise.reject(new Error('nope')),
+    }))
+
+    const store = useAccountsStore()
+    store.auditStale = false
+
+    await expect(store.revokeMemberSessions('acc_1', 'usr_2')).rejects.toThrow('nope')
+    // Nothing was written, so the feed is not behind.
+    expect(store.auditStale).toBe(false)
+  })
+
+  it('clears the stale flag on the reload ATTEMPT, not on its success', async () => {
+    // Clearing on success would re-trigger the watch that just failed, on every failure, forever.
+    // The failure is reported by the viewer's own error slot instead.
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents: () => Promise.reject(new Error('still down')),
+      revokeMemberSessions: () => Promise.resolve(),
+    }))
+
+    const store = useAccountsStore()
+    await store.revokeMemberSessions('acc_1', 'usr_2')
+    expect(store.auditStale).toBe(true)
+
+    await expect(store.loadAuditEvents('acc_1')).rejects.toThrow('still down')
+    expect(store.auditStale).toBe(false)
+    expect(store.auditLoading).toBe(false)
+  })
+})