@company-semantics/contracts 90.0.0 → 91.0.0

package/src/affordances/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Affordance vocabulary barrel (control ADR affordance-system).
+ * Import from '@company-semantics/contracts' (root).
+ */
+export { AFFORDANCE_IDS, AffordanceIdSchema } from "./ids";
+export type { AffordanceId } from "./ids";
+export {
+  AFFORDANCE_ARGS,
+  NO_ARG_AFFORDANCE_IDS,
+  ReviewOpenArgsSchema,
+} from "./args";
+export type { AffordanceArgs } from "./args";
+export {
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_BINDING_KINDS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  AffordanceAvailabilityIdSchema,
+  AffordanceAvailabilitySchema,
+} from "./availability";
+export type {
+  AffordanceAvailability,
+  AffordanceAvailabilityId,
+  AffordanceBindingKind,
+  AffordanceUnavailableReason,
+} from "./availability";
+export {
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_BINDING_KIND_OF,
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  sameAffordances,
+} from "./affordance";
+export type {
+  Affordance,
+  OfferedAffordance,
+  ProjectedAffordanceId,
+} from "./affordance";

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'ba43b4881a93' as const;
-export const SPEC_HASH_FULL = 'ba43b4881a9318819726dfe0c0465ecae3802951f7f558fec6786a7171195a91' as const;
+export const SPEC_HASH = 'b2a6eec5dea4' as const;
+export const SPEC_HASH_FULL = 'b2a6eec5dea4f72290740a1cf16608a826ece2e3654ba64d2bc5e3794d571809' as const;

package/src/api/generated.ts

@@ -4271,6 +4271,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/internal-admin/quality/decisions/{id}/diagnosis": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** A decision's diagnosis: stable vs flaky failures, failure kinds by bucket, suspected component and findings */
+        get: operations["getQualityDecisionDiagnosis"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments": {
         parameters: {
             query?: never;
@@ -8122,7 +8139,7 @@ export interface components {
                 notification: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready" | "proactive.org_structure_review_ready";
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready" | "proactive.org_structure_review_ready" | "proactive.workflow_needs_attention" | "proactive.workflow_finished";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";
@@ -18064,6 +18081,47 @@ export interface operations {
             };
         };
     };
+    getQualityDecisionDiagnosis: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The decision, whether its diagnosis is stored, pending or not applicable, and the report once stored */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin, or missing internal.manage_quality */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such decision */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listCommentThreads: {
         parameters: {
             query: {

package/src/generated/openapi-routes.ts

@@ -110,6 +110,7 @@ export const openApiRoutes = {
   '/api/internal-admin/quality/candidates/{id}/accept': ['POST'],
   '/api/internal-admin/quality/candidates/{id}/reject': ['POST'],
   '/api/internal-admin/quality/changes/manual': ['POST'],
+  '/api/internal-admin/quality/decisions/{id}/diagnosis': ['GET'],
   '/api/internal-admin/quality/escalations': ['GET'],
   '/api/internal-admin/quality/escalations/{id}/resolve': ['POST'],
   '/api/internal-admin/quality/graders': ['GET'],

package/src/proactive/README.md

@@ -134,6 +134,23 @@ the three from another.
   broken, so it gets an unread inbox row (`proactive.org_structure_review_ready`)
   and no chat or banner. It is triggered by the committed insert of a
   `validated` proposal, and its occurrence key is the proposal id.
+- **The two workflow settlement kinds are one `explained` and one `notice`**
+  (control ADR-CTRL-540 phase 2; control ADR `affordance-system`). Both are
+  triggered by a ROUTED workflow settlement — the committed `deferred → routed`
+  transition of a settlement nobody was watching, routed per reason through
+  `../workflows/deferred-route` — and both key on
+  `workflow-settled:{workflowId}:{executionEpoch}`. `workflow.needs_attention`
+  is `explained`: the `workflowNeedsAttention` chat is FACT-FREE (no counts —
+  the outcome's facts are stripped), carries the settled outcome as
+  `ProactiveChatMessage.outcome` so its grounded affordances render as real
+  controls, and has NO chips (a chip only sends a chat prompt, which is not
+  grounded). Its composer frames and never narrates: `text` is the backend's
+  settlement narration verbatim, and its per-type title states no digit and
+  no next step. The inbox row is born read. `workflow.finished` is a `notice`:
+  an unread inbox row and nothing else, because telling it needs counts that
+  must re-render under the reader's authority. Their rows are
+  `proactive.workflow_needs_attention` and `proactive.workflow_finished`.
+  Neither sets `emailKind` or `actionItemKind`.
 - **The occurrence vocabulary is closed.** `ProactiveEventId` is branded so a
   raw string cannot stand in for an occurrence; `ProactiveRecipientReason` is a
   closed enum because the recipients table is the frozen audit record of who
@@ -172,9 +189,9 @@ the three from another.
 | `bornRead`                         | Whether a class's `chat` or `inbox` row is born read                          |
 | `ORG_SYSTEM_EVENT_TYPES`           | Mirror of the backend `org_system_event_type` pgEnum — the banner ids         |
 | `OrgSystemEventType`               | Union derived from the array                                                  |
-| `PROACTIVE_CHAT_TEMPLATES`         | Which prose composes a kind's pushed chat (8: 2 + 5 `billing*` + 1 `source*`) |
+| `PROACTIVE_CHAT_TEMPLATES`         | Which prose composes a kind's pushed chat (9, incl. `workflowNeedsAttention`) |
 | `ProactiveChatTemplate`            | Union derived from the array                                                  |
-| `PROACTIVE_EVENT_KIND_IDS`         | Closed kinds (3 org/brief/chat + 15 `billing.*` + 2 `sourceSync.*`)           |
+| `PROACTIVE_EVENT_KIND_IDS`         | Closed kinds (org/brief/chat, `billing.*`, `sourceSync.*`, `workflow.*` …)    |
 | `ProactiveEventKind`               | Union derived from the array                                                  |
 | `ProactiveEventId`                 | Branded id of ONE occurrence — a raw string cannot be passed as one           |
 | `PROACTIVE_RECIPIENT_REASONS`      | Closed enum of WHY a recipient was addressed (the frozen audit record)        |
@@ -192,7 +209,9 @@ the three from another.
 | `BillingSuspendedFacts`            | `orgName` — the prose needs nothing else, and may state nothing else          |
 | `BillingSubscriptionCanceledFacts` | `orgName`                                                                     |
 | `SourceSyncReviewReadyFacts`       | `orgName` + `checkpoint`; no count, no document name, no source name          |
-| `ProactiveChatMessage`             | What a composer returns: `title`, `text`, and 0..4 `replies` chips            |
+| `ExplainedWorkflowOutcomeData`     | The settlement data part with an explained, fact-free outcome                 |
+| `WorkflowNeedsAttentionFacts`      | `narration` (backend settlement copy) + the fact-free `outcome` data part     |
+| `ProactiveChatMessage`             | `title`, `text`, 0..4 `replies` chips, and an optional settled `outcome`      |
 | `ProactiveChatComposer`            | The composer port — `template` plus an arrow-property `compose(facts)`        |
 | `PROACTIVE_CHAT_MAX_REPLIES`       | At most this many chips (4); more is a menu, not a chip row                   |
 | `PROACTIVE_CHAT_COMPOSERS`         | The total template → composer registry (see `templates/README.md`)            |
@@ -203,5 +222,8 @@ Type-only imports of `UserNotificationKind` (`../user-notifications`),
 `NotificationKind` (`../notifications`) and `ActionItemKind`
 (`../action-items`) — the three vocabularies this one composes — and of
 `SuggestedReply` (`../message-parts`), the chip shape a composer's `replies`
-reuse rather than redeclare. No `zod`, no runtime imports; pure vocabulary
+reuse rather than redeclare. Type-only imports of `WorkflowOutcomeData`
+(`../message-parts`), `ExplainedWorkflowOutcome` (`../workflows`) and
+`WorkflowType` for the workflow settlement chat; the dependency runs
+proactive → workflows, never the reverse. No `zod`, no runtime imports; pure vocabulary
 data and pure helpers.

package/src/proactive/__tests__/README.md

@@ -51,6 +51,16 @@ cannot.
   must not be told to update one), past-due separates the seat subscription from
   the AI balance, and suspension and cancellation each say outright that nothing
   was deleted.
+- `workflow-attention.test.ts` — the two workflow settlement kinds (control
+  ADR-CTRL-540 phase 2): `workflow.needs_attention` is explained (a chat and a
+  born-read inbox row, never a banner) and `workflow.finished` is a notice (an
+  unread inbox row only); the `workflowNeedsAttention` chat carries the
+  fact-free outcome (schema-valid, `facts: null`) and no chips, frames the
+  backend narration verbatim, has a title per workflow type with no digit and
+  no next-step wording; and both inbox rows supersede per workflow type.
+- `workflow-attention-fixtures.ts` — explained, fact-free outcomes for those
+  tests and the registry-wide fixtures. A COMPILED module, so each fixture is
+  typechecked against `ExplainedWorkflowOutcome`.
 
 ## Invariants
 

package/src/proactive/__tests__/chat-templates.test.ts

@@ -6,6 +6,10 @@ import type { OrgSharedTransitionTrigger } from "../../org/shared-transition";
 import { PROACTIVE_CHAT_TEMPLATES } from "../surfaces";
 import type { ProactiveChatTemplate } from "../surfaces";
 import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+} from "./workflow-attention-fixtures";
 
 /**
  * One representative facts fixture per template. Total over
@@ -32,6 +36,10 @@ const FACTS: { readonly [T in ProactiveChatTemplate]: ProactiveChatFacts[T] } =
     billingSuspended: { orgName: "Acme" },
     billingSubscriptionCanceled: { orgName: "Acme" },
     sourceSyncReviewReady: { orgName: "Acme", checkpoint: "candidates" },
+    workflowNeedsAttention: {
+      narration: DRIVE_AUTH_NARRATION,
+      outcome: { workflowId: "wf-1", outcome: DRIVE_AUTH_OUTCOME },
+    },
   };
 
 /**

package/src/proactive/__tests__/vocabulary.test.ts

@@ -37,6 +37,10 @@ import {
   PLAN_FIXTURES_THE_COMPILER_REJECTS,
   REGISTRY_FIXTURES_THE_COMPILER_REJECTS,
 } from "./compile-fixtures";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+} from "./workflow-attention-fixtures";
 
 /**
  * The registry, read as the union it satisfies rather than as its literal
@@ -103,6 +107,10 @@ const FRESH_FACTS: {
     orgName: "Acme",
     checkpoint: "synthesis" as const,
   }),
+  workflowNeedsAttention: () => ({
+    narration: DRIVE_AUTH_NARRATION,
+    outcome: { workflowId: "wf-1", outcome: DRIVE_AUTH_OUTCOME },
+  }),
 };
 
 /**
@@ -259,6 +267,9 @@ describe("the kind registry", () => {
       "sourceSync.review_ready": "proactive",
       // The org structure row is rendered by `src/proactive/` as well.
       "orgStructure.review_ready": "proactive",
+      // Both workflow settlement rows are rendered by `src/proactive/`.
+      "workflow.needs_attention": "proactive",
+      "workflow.finished": "proactive",
     };
 
     expect(Object.keys(EXPECTED_INBOX_DOMAIN).sort()).toEqual(

package/src/proactive/__tests__/workflow-attention-fixtures.ts

@@ -0,0 +1,49 @@
+/**
+ * Explained, fact-free workflow outcomes for the `workflowNeedsAttention`
+ * template's tests. A COMPILED module (not `*.test.ts`), so every fixture is
+ * checked against `ExplainedWorkflowOutcome` — a reason that is not explained,
+ * or facts left in, fails the typecheck rather than passing silently.
+ *
+ * The narrations are fixture strings standing in for the backend's settlement
+ * copy; contracts never owns that wording.
+ */
+import type { ExplainedWorkflowOutcomeData } from "../facts";
+import type { ExplainedWorkflowOutcome } from "../../workflows/deferred-route";
+
+export const DRIVE_AUTH_NARRATION =
+  "The search of the connected drive stopped because Google Drive no longer accepts the connection's sign-in.";
+
+export const DRIVE_AUTH_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 0,
+  kind: "failed",
+  reason: "drive_auth",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "integrations.connectGoogleDrive" }],
+};
+
+export const PAUSED_BILLING_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "source-sync/synthesize",
+  executionEpoch: 1,
+  kind: "failed",
+  reason: "paused_billing",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "billing.open" }],
+};
+
+export const MODEL_FAILED_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "org-structure/reanalyze",
+  executionEpoch: 2,
+  kind: "failed",
+  reason: "model_failed",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "orgStructure.reanalyze" }],
+};
+
+/** The settlement data part for an outcome, as the backend would hand it over. */
+export const outcomeDataOf = (
+  outcome: ExplainedWorkflowOutcome,
+): ExplainedWorkflowOutcomeData => ({ workflowId: "wf-1", outcome });

package/src/proactive/__tests__/workflow-attention.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The two workflow settlement proactive kinds (control ADR-CTRL-540 phase 2;
+ * control ADR affordance-system): `workflow.needs_attention` is explained and
+ * its chat only FRAMES the backend's narration, `workflow.finished` is a notice.
+ */
+import { describe, it, expect } from "vitest";
+import { CLASS_SURFACES, bornRead } from "../classes";
+import type { ProactiveChatMessage } from "../composer";
+import type { WorkflowNeedsAttentionFacts } from "../facts";
+import { PROACTIVE_EVENT_KINDS } from "../registry";
+import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import { notificationKeysOf } from "../../user-notifications/condition-keys";
+import { NOTIFICATION_LIFECYCLE } from "../../user-notifications/lifecycle-registry";
+import { WorkflowOutcomeSchema } from "../../workflows/outcome";
+import { ANALYSIS_WORKFLOW_TYPES } from "../../workflows/types";
+import type { ExplainedWorkflowOutcome } from "../../workflows/deferred-route";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+  MODEL_FAILED_OUTCOME,
+  PAUSED_BILLING_OUTCOME,
+  outcomeDataOf,
+} from "./workflow-attention-fixtures";
+
+// Mirrors the backend settlement-copy ban (backend tests/chat/workflow-outcome-copy.test.ts).
+const CALL_TO_ACTION =
+  /\byou can\b|\btry\b|\bagain\b|\bsettings\b|\breconnect\b|\badd funds\b|\bclick\b|\bgo to\b|\bopen\b/i;
+
+const compose = (facts: WorkflowNeedsAttentionFacts): ProactiveChatMessage =>
+  PROACTIVE_CHAT_COMPOSERS.workflowNeedsAttention.compose(facts);
+
+const DRIVE_AUTH_FACTS: WorkflowNeedsAttentionFacts = {
+  narration: DRIVE_AUTH_NARRATION,
+  outcome: outcomeDataOf(DRIVE_AUTH_OUTCOME),
+};
+
+/** The drive-auth outcome re-typed as each workflow type, for title coverage. */
+const outcomeAs = (
+  workflowType: (typeof ANALYSIS_WORKFLOW_TYPES)[number],
+): ExplainedWorkflowOutcome =>
+  ({ ...DRIVE_AUTH_OUTCOME, workflowType }) as ExplainedWorkflowOutcome;
+
+describe("workflow settlement proactive kinds", () => {
+  it("workflow.needs_attention is explained: a chat and a born-read inbox row, never a banner", () => {
+    const plan = PROACTIVE_EVENT_KINDS["workflow.needs_attention"];
+    expect(plan).toEqual({
+      class: "explained",
+      chatTemplate: "workflowNeedsAttention",
+      inboxKind: "proactive.workflow_needs_attention",
+    });
+    const surfaces = CLASS_SURFACES[plan.class];
+    expect(surfaces.banner).toBe(false);
+    expect(surfaces.chat).toBe(true);
+    expect(bornRead(surfaces, "inbox")).toBe(true);
+  });
+
+  it("workflow.finished is a notice: an unread inbox row, no banner and no chat", () => {
+    const plan = PROACTIVE_EVENT_KINDS["workflow.finished"];
+    expect(plan).toEqual({
+      class: "notice",
+      inboxKind: "proactive.workflow_finished",
+    });
+    const surfaces = CLASS_SURFACES[plan.class];
+    expect(surfaces.banner).toBe(false);
+    expect(surfaces.chat).toBe(false);
+    expect(bornRead(surfaces, "inbox")).toBe(false);
+  });
+
+  it("the attention chat carries the fact-free outcome and no chips", () => {
+    const msg = compose(DRIVE_AUTH_FACTS);
+    expect(msg.replies).toEqual([]);
+    expect(msg.outcome).toEqual({
+      workflowId: "wf-1",
+      outcome: DRIVE_AUTH_OUTCOME,
+    });
+    expect(msg.outcome?.outcome.facts).toBeNull();
+    expect(WorkflowOutcomeSchema.safeParse(msg.outcome?.outcome).success).toBe(
+      true,
+    );
+  });
+
+  it("the attention chat frames the backend narration verbatim", () => {
+    for (const outcome of [
+      DRIVE_AUTH_OUTCOME,
+      PAUSED_BILLING_OUTCOME,
+      MODEL_FAILED_OUTCOME,
+    ]) {
+      const narration = `Narration for ${outcome.workflowType} ${outcome.reason}.`;
+      const msg = compose({ narration, outcome: outcomeDataOf(outcome) });
+      expect(msg.text, outcome.workflowType).toBe(narration);
+    }
+  });
+
+  it("the attention chat has a title for every workflow type", () => {
+    for (const workflowType of ANALYSIS_WORKFLOW_TYPES) {
+      const msg = compose({
+        narration: DRIVE_AUTH_NARRATION,
+        outcome: outcomeDataOf(outcomeAs(workflowType)),
+      });
+      expect(typeof msg.title, workflowType).toBe("string");
+      expect(msg.title.trim().length, workflowType).toBeGreaterThan(0);
+    }
+  });
+
+  it("the attention chat title states no digit and offers no next step", () => {
+    for (const workflowType of ANALYSIS_WORKFLOW_TYPES) {
+      const { title } = compose({
+        narration: DRIVE_AUTH_NARRATION,
+        outcome: outcomeDataOf(outcomeAs(workflowType)),
+      });
+      expect(title, workflowType).not.toMatch(/\d/);
+      expect(title, workflowType).not.toMatch(CALL_TO_ACTION);
+    }
+  });
+
+  it("both workflow inbox rows supersede per workflow type", () => {
+    for (const kind of [
+      "proactive.workflow_needs_attention",
+      "proactive.workflow_finished",
+    ] as const) {
+      const lifecycle = NOTIFICATION_LIFECYCLE[kind];
+      expect(lifecycle.condition, kind).toEqual({
+        scope: "fields",
+        fields: ["workflowType"],
+      });
+      expect(lifecycle.supersedes, kind).toBe(true);
+      expect(lifecycle.resolution, kind).toBe("never");
+
+      const first = notificationKeysOf(kind, {
+        workflowType: "source-sync/discover",
+        workflowId: "wf-1",
+      });
+      const second = notificationKeysOf(kind, {
+        workflowType: "source-sync/discover",
+        workflowId: "wf-2",
+      });
+      const other = notificationKeysOf(kind, {
+        workflowType: "org-structure/reanalyze",
+        workflowId: "wf-3",
+      });
+      expect(first.supersessionKey, kind).not.toBeNull();
+      expect(second.supersessionKey, kind).toBe(first.supersessionKey);
+      expect(other.supersessionKey, kind).not.toBe(first.supersessionKey);
+    }
+  });
+});

package/src/proactive/composer.ts

@@ -35,6 +35,7 @@
  */
 
 import type { SuggestedReply } from "../message-parts/suggested-replies";
+import type { WorkflowOutcomeData } from "../message-parts/workflow-outcome";
 import type { ProactiveChatFacts } from "./facts";
 import type { ProactiveChatTemplate } from "./surfaces";
 
@@ -65,6 +66,13 @@ export interface ProactiveChatMessage {
   readonly text: string;
   /** 0..`PROACTIVE_CHAT_MAX_REPLIES` chips. */
   readonly replies: readonly SuggestedReply[];
+  /**
+   * The settled workflow a template reports, when it reports one. The chat
+   * writer persists it as a `data-workflow-outcome` part beside the prose, so
+   * the same renderer shows its affordances. Present only for a template whose
+   * facts carry an outcome; always fact-free here.
+   */
+  readonly outcome?: WorkflowOutcomeData;
 }
 
 // =============================================================================

package/src/proactive/facts.ts

@@ -23,7 +23,9 @@
  *   receive different prose because they were handed different facts.
  */
 
+import type { WorkflowOutcomeData } from "../message-parts/workflow-outcome";
 import type { OrgSharedTransitionTrigger } from "../org/shared-transition";
+import type { ExplainedWorkflowOutcome } from "../workflows/deferred-route";
 
 // =============================================================================
 // Per-template facts
@@ -189,6 +191,39 @@ export interface SourceSyncReviewReadyFacts {
   readonly checkpoint: "candidates" | "synthesis";
 }
 
+// =============================================================================
+// Workflow settlement facts (control ADR-CTRL-540 phase 2)
+// =============================================================================
+
+/**
+ * The settlement data part a pushed chat may carry: an explained, fact-free
+ * outcome.
+ */
+export type ExplainedWorkflowOutcomeData = Omit<
+  WorkflowOutcomeData,
+  "outcome"
+> & {
+  readonly outcome: ExplainedWorkflowOutcome;
+};
+
+/**
+ * A workflow ended in a failure a person can act on, and nobody was watching.
+ *
+ * FACT-FREE (INV-PROACTIVE-CONTENT). `narration` is the BACKEND's deterministic
+ * settlement copy (src/chat/workflow-outcome-copy.ts), rendered from the
+ * fact-stripped outcome (`facts: null`) — the same sentence the launching chat
+ * would have received, so one module owns settlement wording and it already
+ * carries the call-to-action ban. `outcome` is the settlement data part with
+ * the frozen outcome's facts stripped: reason and affordance ids only, each
+ * affordance re-gated per viewer at render and executed by the server.
+ */
+export interface WorkflowNeedsAttentionFacts {
+  /** The backend settlement narration for this outcome, told with `facts: null`. */
+  readonly narration: string;
+  /** `{ workflowId, outcome }` — explained route only, `facts: null`. */
+  readonly outcome: ExplainedWorkflowOutcomeData;
+}
+
 // =============================================================================
 // ProactiveChatFacts
 // =============================================================================
@@ -207,4 +242,5 @@ export interface ProactiveChatFacts {
   readonly billingSuspended: BillingSuspendedFacts;
   readonly billingSubscriptionCanceled: BillingSubscriptionCanceledFacts;
   readonly sourceSyncReviewReady: SourceSyncReviewReadyFacts;
+  readonly workflowNeedsAttention: WorkflowNeedsAttentionFacts;
 }

package/src/proactive/index.ts

@@ -51,6 +51,8 @@ export type {
   BillingSuspendedFacts,
   BillingSubscriptionCanceledFacts,
   SourceSyncReviewReadyFacts,
+  ExplainedWorkflowOutcomeData,
+  WorkflowNeedsAttentionFacts,
   ProactiveChatFacts,
 } from "./facts";
 export { PROACTIVE_CHAT_MAX_REPLIES } from "./composer";

package/src/proactive/kinds.ts

@@ -302,6 +302,35 @@ export const PROACTIVE_EVENT_KIND_IDS = [
    * times its job is redelivered.
    */
   "orgStructure.review_ready",
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2; control ADR
+  // affordance-system)
+  // ===========================================================================
+  //
+  // A workflow that settles with no launching conversation (a scheduled
+  // rediscovery, an upkeep re-synthesis, a launch nobody docked into a chat)
+  // is ROUTED here by the backend, per reason, through the frozen
+  // `*_DEFERRED_ROUTE_OF_REASON` tables in ../workflows/deferred-route.
+  //
+  // TRIGGER: the committed `deferred → routed` transition of the settlement
+  // row (INV-PROACTIVE-TRIGGER). OCCURRENCE KEY:
+  // `workflow-settled:{workflowId}:{executionEpoch}` — one settlement announces
+  // once, however often the sweep runs.
+  /**
+   * A workflow ended in a failure a person can act on. `explained` — a pushed
+   * chat that says what happened, FACT-FREE (reason only), carrying the frozen
+   * outcome so its grounded affordances render as controls; plus a born-read
+   * inbox row. No banner: one background run is not the workspace broken.
+   */
+  "workflow.needs_attention",
+  /**
+   * A workflow finished (or failed with nothing to offer) while nobody was
+   * watching. A `notice` — an unread inbox row and nothing else: telling it
+   * needs counts, which are authority-sensitive and must re-render under the
+   * reader's current authority, never freeze into a chat.
+   */
+  "workflow.finished",
 ] as const;
 export type ProactiveEventKind = (typeof PROACTIVE_EVENT_KIND_IDS)[number];
 

package/src/proactive/registry.ts

@@ -262,4 +262,26 @@ export const PROACTIVE_EVENT_KINDS = {
     class: "notice",
     inboxKind: "proactive.org_structure_review_ready",
   },
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2)
+  // ===========================================================================
+  //
+  // Routed per reason by the backend through ../workflows/deferred-route. NO
+  // PLAN SETS `emailKind` or `actionItemKind`: a background run's ending is
+  // announced, not standing work.
+  /**
+   * A failure a person can act on. EXPLAINED: the fact-free chat carries the
+   * badge and the frozen outcome; the inbox row is born read.
+   */
+  "workflow.needs_attention": {
+    class: "explained",
+    chatTemplate: "workflowNeedsAttention",
+    inboxKind: "proactive.workflow_needs_attention",
+  },
+  /** A finished run nobody watched. A NOTICE: the inbox row is the attention. */
+  "workflow.finished": {
+    class: "notice",
+    inboxKind: "proactive.workflow_finished",
+  },
 } as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>;

package/src/proactive/surfaces.ts

@@ -91,5 +91,7 @@ export const PROACTIVE_CHAT_TEMPLATES = [
   "billingSubscriptionCanceled",
   /** "A source review is ready — here is what it is and what happens if you leave it." */
   "sourceSyncReviewReady",
+  /** "A background run did not finish — here is what happened." Fact-free. */
+  "workflowNeedsAttention",
 ] as const;
 export type ProactiveChatTemplate = (typeof PROACTIVE_CHAT_TEMPLATES)[number];

package/src/proactive/templates/README.md

@@ -66,6 +66,13 @@ chat. That is the precedent notify/'s README states for outbound notifications
   nothing. It names no count, no document and no source: all three are
   scope-gated, and a frozen sentence cannot be taken back.
   `../__tests__/vocabulary.test.ts` enforces "no digit" for both checkpoints.
+- **`workflow-needs-attention.ts` FRAMES; IT DOES NOT NARRATE.** Its `text` is
+  the backend's settlement narration verbatim (one owner of settlement wording),
+  its title is per workflow type with no digit and no next step, it has no
+  chips, and it carries the fact-free outcome as `outcome` so the outcome's
+  grounded affordances render as real controls (control ADR
+  `affordance-system`). `../__tests__/workflow-attention.test.ts` pins all of
+  it.
 
 ## Public API
 
@@ -80,10 +87,11 @@ chat. That is the precedent notify/'s README states for outbound notifications
 | `billingSuspendedComposer`            | The grace period elapsed; leads with "nothing was deleted"      |
 | `billingSubscriptionCanceledComposer` | Seats ended; AI funds are not forfeit                           |
 | `sourceSyncReviewReadyComposer`       | A source review waits; nothing has happened yet; no count       |
+| `workflowNeedsAttentionComposer`      | A background run failed; frames the backend narration, no chips |
 
 ## Dependencies
 
 Type-only imports of `ProactiveChatComposer` (`../composer`),
 `ProactiveChatTemplate` (`../surfaces`) and the per-template facts
-(`../facts`). No `zod`, no runtime imports beyond the sibling template
+(`../facts`), and of `WorkflowType` (`../../workflows`). No `zod`, no runtime imports beyond the sibling template
 modules.