@nauticana/sail 1.1.35 → 1.1.36

package/README.md

@@ -2,7 +2,7 @@
 
 A shared Angular component library for building CRUD-based admin frontends. Provides table management, form handling, navigation, authentication, two-factor authentication, and trusted device management — all driven by metadata from a [keel](https://github.com/nauticana/keel) Go backend.
 
-> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.35 adopts keel v1.2.112 (minor-unit money, the `currency` catalog, OAuth grant routes), sail v1.1.33 adopts keel v1.2.106 (`prompt` on the login page, new-device step-up, sign-in sessions), sail v1.1.32 adopts keel v1.2.101 (the OAuth connect callback ticket), sail v1.1.31 adopts keel v1.2.100 (tenant single sign-on, DNS and HTTP-file domain verification), sail v1.1.30 adopts keel v1.2.99 (password routes; a password change signs out), sail v1.1.29 adopts keel v1.2.94 (signup: confirmation signs in, partner setup, sign-in hand-off code), sail v1.1.28 adopts keel v1.2.93 (absolute `return` for the OAuth hand-off), sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.36 adopts keel v1.2.113 (API key expiry, caller-aware scope policy), sail v1.1.35 adopts keel v1.2.112 (minor-unit money, the `currency` catalog, OAuth grant routes), sail v1.1.33 adopts keel v1.2.106 (`prompt` on the login page, new-device step-up, sign-in sessions), sail v1.1.32 adopts keel v1.2.101 (the OAuth connect callback ticket), sail v1.1.31 adopts keel v1.2.100 (tenant single sign-on, DNS and HTTP-file domain verification), sail v1.1.30 adopts keel v1.2.99 (password routes; a password change signs out), sail v1.1.29 adopts keel v1.2.94 (signup: confirmation signs in, partner setup, sign-in hand-off code), sail v1.1.28 adopts keel v1.2.93 (absolute `return` for the OAuth hand-off), sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
 
 **Recent additions:** `BaseAuthService.acceptToken(jwt)` — adopt an externally-minted JWT (registration / SSO-handoff flows) and run the full post-login sequence (store under the canonical `jwt` key, load appdata, init routes); apps must use this instead of writing `localStorage` directly. `BaseRestService.analytic<T>(endpoint, params?)` — GET a keel `analytic/<endpoint>` report and return its rows. `passwordPolicyValidator` + `BaseAuthService.ensurePasswordPolicy()` — validate passwords against keel's policy (via `SailGuiConfig.passwordPolicyUrl`); see Configuration reference.
 
@@ -414,7 +414,7 @@ The login flow redirects `twoFactorRequired` responses to `/login/2fa`. With `tw
 
 `SessionsComponent` (`<sail-sessions>`) lists the sessions with their `sign_in_method` captions, marks the current one, and signs out any other.
 
-`ApiKeysComponent` (`<sail-api-keys [scopes]>`) lists the partner's keys and uses the backend-provided `generate` and `restrict` table actions; controls appear only for granted actions. Pass the scopes the app offers (`LabelOption[]`) after filtering out scopes the caller may not mint. The role also needs generic `SELECT` and `DELETE` grants to list and revoke keys. `ConnectedAppsComponent` (`<sail-connected-apps>`) lists and disconnects OAuth clients through keel's `GrantHandler` routes (v1.2.112, `RestURL.oauthGrantsURL` and `oauthGrantRevokeURL`).
+`ApiKeysComponent` (`<sail-api-keys [scopes]>`) lists the partner's keys and uses the backend-provided `generate` and `restrict` table actions; controls appear only for granted actions. Pass the scopes the app offers (`LabelOption[]`) after filtering out scopes the caller may not mint; with none, keel's `ScopePolicy` supplies them. A key may carry an expiry, shown in its own column. The role also needs generic `SELECT` and `DELETE` grants to list and revoke keys. `ConnectedAppsComponent` (`<sail-connected-apps>`) lists and disconnects OAuth clients through keel's `GrantHandler` routes (v1.2.112, `RestURL.oauthGrantsURL` and `oauthGrantRevokeURL`).
 
 ### Cross-origin cookie requirement
 
@@ -689,7 +689,7 @@ A complete screen is the pieces above assembled over `BillingService` — no met
 
 ## Agent UI (v1.1.20)
 
-Agent Studio and agent-conversation UI live in a secondary entry point, `@nauticana/sail/agent`. Nothing in it is exported from `@nauticana/sail`, so an app that never imports it bundles none of it. It needs no additional peer dependency. The wire types match Scout v1.2.13.
+Agent Studio and agent-conversation UI live in a secondary entry point, `@nauticana/sail/agent`. Nothing in it is exported from `@nauticana/sail`, so an app that never imports it bundles none of it. It needs no additional peer dependency. The wire types match Scout v1.2.14.
 
 ```ts
 import { AgentStudioService, PromptLanguageEditorComponent, TurnStream } from '@nauticana/sail/agent';
@@ -699,10 +699,10 @@ import { AgentStudioService, PromptLanguageEditorComponent, TurnStream } from '@
 |---|---|
 | `AgentStudioService` | Client for Scout's core Studio routes under `/api/agent-studio/` (fixed, unversioned paths): the `features` manifest, list, draft, settings, create, rename, archive, enable, test, publish, restore, reset, default, history, audit, release sections, models. Models mirror the backend's JSON names. |
 | `sail-studio-page` | Embeddable Studio: an agent rail grouped by `[groupBy]` (agent type by default; pass a function for workflow or position), and Overview, Prompts, Settings (scoped bindings and what they resolve to), Test, and History (diff, restore, audit) tabs. Product tabs are `<ng-template sailStudioTab="id" label="Label" let-agent>`. A control shows only when the `agents` feature lists its action and the caller holds the `AGENT_STUDIO` grant at `agent:<name>` (`agent_type:<type>` for create); hiding is never the authorization. `hasUnsavedChanges()` serves a `canDeactivate` guard. |
-| `sail-studio-page` Guardrails tab | Shown when the `features` manifest lists `guardrails`: inherited layers read-only, the agent's own rules as an editable JSON array saved against `expected_agent_revision`, and its safety events paged by `before`. Edit needs the feature's `EDIT` action. The rail captions Scout's fixed readiness values (`AGENT_READINESS_CAPTIONS`). |
-| `sail-assistant-activity` | The tenant's decision records from Scout's `decisions` feature (`GET /api/agent-studio/decisions`, `AGENT_AUDIT` `VIEW`), newest first and paged by `next_before`: when, action, resource, outcome caption, who (`[who]` names a principal), app (`client_ref`), and whom it acted for. `[category]` and `[outcome]` filter. |
-| `sail-turn-thread` | The signed-in person's turns from `GET {base}turns` (`ConversationService.turns`), newest first, paged by `next_before` and optionally narrowed to `[workRef]`: `turn_status` caption, settled cost in minor units with its exponent, agent and release version. Each `task_kind` renders its result through `<ng-template sailTurnResult="kind" let-turn>`; the first page reloads every `[pollMs]` while a turn is nonterminal. |
-| `sail-approval-inbox` / `ApprovalService` | The signed-in person's pending approvals (`GET /api/approval/pending`) and MCP confirmations (`GET /api/approval/confirmations`) in one list. Approvals are approved, rejected, or edited (`POST /api/approval/resolve`); confirmations are confirmed, declined, withdrawn, or reconciled as executed or failed through `/api/approval/confirmation/*`, each control shown only when Scout says the person may. A `409` reloads the list; `(decided)` and `(confirmationChanged)` emit the result. |
+| `sail-studio-page` Guardrails tab | Shown when the `features` manifest lists `guardrails`: inherited layers read-only, the agent's own rules as an editable JSON array saved against `expected_agent_revision`, and its safety events paged by `before`. Edit needs the feature's `EDIT` action. The rail captions Scout's fixed `AgentReadiness` values (`AGENT_READINESS_CAPTIONS`). |
+| `sail-assistant-activity` | The tenant's decision records from Scout's `decisions` feature (`GET /api/agent-studio/decisions`, `AGENT_AUDIT` `VIEW`), newest first and paged by `next_before`: when, action, resource, outcome caption, who, app, and whom it acted for, named by the product's Scout `Labeler` (kind and id, or the client ref, without one). `[category]` and `[outcome]` filter. |
+| `sail-turn-thread` | The signed-in person's turns from `GET {base}turns` (`ConversationService.turns`), newest first, paged by `next_before` and optionally narrowed to `[workRef]`: `turn_status` caption, settled cost in minor units with its exponent, agent and release version. Each `task_kind` renders its result through `<ng-template sailTurnResult="kind" let-turn>` (`"*"` for any other kind; `let-turn` is a `ConversationTurn`); a failed turn without error text shows `[failedText]`; the first page reloads every `[pollMs]` while a turn is nonterminal. |
+| `sail-approval-inbox` / `ApprovalService` | The signed-in person's pending approvals (`GET /api/approval/pending`) and MCP confirmations (`GET /api/approval/confirmations`) grouped as waiting, submitted, needing reconciliation and recent; each list loads independently and a `404` leaves it empty. Approvals are approved, rejected, or edited (`POST /api/approval/resolve`); confirmations are confirmed, declined, withdrawn, or reconciled as executed or failed through `/api/approval/confirmation/*`, each control shown only when Scout says the person may. Approving asks once more; reconciling requires a note of up to 500 characters. `[open]` selects an item by key or confirmation id (an emailed link). People, workspaces and apps show their Scout `Labeler` captions. A tool's preview renders through `<ng-template sailApprovalPreview="tool" let-c>` (`"*"` for any other tool), otherwise as JSON. A `404` or `409` reloads the list; `(decided)` and `(confirmationChanged)` emit the result. |
 | `studioErrorMessage(err)` | One message for a failed Studio call: the conflict cause, the field errors, or the detail. |
 | `studioConflictCause(err)` | `'revision'` (reload the draft), `'sealed'` (a layer sits under a sealed one) or `'other'` for a `409`. |
 | `studioFieldErrors(err)` / `retryAfterSeconds(err)` | Field errors of a `400`; `Retry-After` of a `429`/`503`. |
@@ -713,7 +713,7 @@ import { AgentStudioService, PromptLanguageEditorComponent, TurnStream } from '@
 | `TurnStream` | Per-turn stream state: `accept(frame)` accepts Scout's zero-based frames and drops frames already rendered, `cursor()` is the next sequence wanted for inclusive replay, a suspension frame (`approval_pending`, even when marked final) sets `awaiting_approval` without advancing the cursor so the resumed frame at the same sequence is accepted, `markReplayExpired()` + `acceptStoredResult(frame)` handle an expired replay window, `markCancelRequested()` holds `cancelling` until the final frame. |
 | `sail-turn-stream-view` | `TurnStream` + event list + status + cancel button (`cancelRequested`). |
 | `sail-decision-timeline` | Read-only decision chain of one request, grouped by category. |
-| `ConversationService` | Transport for Scout's conversation bridge: `submit`, `stream(requestId, turnStream)`, `cancel`. Mount point injected through `CONVERSATION_BASE_PATH`. |
+| `ConversationService` | Transport for Scout's conversation bridge: `submit`, `stream(requestId, turnStream)`, `cancel`. Mount point injected through `CONVERSATION_BASE_PATH`; the service is a root singleton, so provide the token at bootstrap, or both together on a component. |
 | `SseParser` | Incremental `text/event-stream` parser: `push(chunk)` returns whole events out of chunks that split anywhere, including between the CR and LF of a CRLF; `finish()` flushes what the closing body left pending. |
 
 `DecisionRecord` is Scout's `api.DecisionRecord` (outcome `A`, `D`, or `P`, captioned from `audit_decision_outcome`); the timeline takes the records of one request, the activity table pages the tenant's. Style the `.prompt-*`, `.release-*`, `.turn-*`, `.decision-*`, `.studio__*`, and `.approval-inbox__*` class hooks. Scout's short codes render through `sailCaption`, a pipe over the backend's constant captions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.35",
+  "version": "1.1.36",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "exports": {

package/src/agent/component/approval_inbox.html

@@ -1,38 +1,42 @@
 <div class="approval-inbox">
-  <section class="approval-inbox__list" aria-label="Pending approvals">
-    @if (requests().length === 0 && confirmations().length === 0 && !loading()) {
-      <p class="approval-inbox__empty">Nothing is waiting for your decision.</p>
+  <nav class="approval-inbox__list" aria-label="Approvals">
+    @for (section of sections(); track section.title) {
+      <section [attr.aria-label]="section.title">
+        <h3>{{ section.title }} ({{ section.requests.length + section.confirmations.length }})</h3>
+        <ul>
+          @for (request of section.requests; track key(request)) {
+            <li>
+              <button type="button" class="approval-inbox__item" [class.selected]="key(request) === selectedKey()"
+                [attr.aria-current]="key(request) === selectedKey()" (click)="select(key(request))">
+                <span class="approval-inbox__summary">{{ request.summary || request.action }}</span>
+                @if (request.deadline_at) {
+                  <span class="approval-inbox__deadline">Due {{ request.deadline_at | date: 'medium' }}</span>
+                }
+              </button>
+            </li>
+          }
+          @for (c of section.confirmations; track confirmationKey(c)) {
+            <li>
+              <button type="button" class="approval-inbox__item" [class.selected]="confirmationKey(c) === selectedKey()"
+                [attr.aria-current]="confirmationKey(c) === selectedKey()" (click)="select(confirmationKey(c))">
+                <span class="approval-inbox__summary">{{ c.tool }} · {{ c.status | sailCaption:'mcp_confirmation_status' }}</span>
+                @if (c.status === 'P') {
+                  <span class="approval-inbox__deadline">Expires {{ c.expires_at | date: 'medium' }}</span>
+                }
+              </button>
+            </li>
+          }
+        </ul>
+      </section>
+    } @empty {
+      @if (!loading()) { <p class="approval-inbox__empty">Nothing is waiting for your decision.</p> }
     }
-    <ul>
-      @for (request of requests(); track key(request)) {
-        <li>
-          <button type="button" class="approval-inbox__item" [class.selected]="key(request) === selectedKey()"
-            [attr.aria-current]="key(request) === selectedKey()" (click)="select(key(request))">
-            <span class="approval-inbox__summary">{{ request.summary || request.action }}</span>
-            @if (request.deadline_at) {
-              <span class="approval-inbox__deadline">Due {{ request.deadline_at | date: 'medium' }}</span>
-            }
-          </button>
-        </li>
-      }
-      @for (c of confirmations(); track confirmationKey(c)) {
-        <li>
-          <button type="button" class="approval-inbox__item" [class.selected]="confirmationKey(c) === selectedKey()"
-            [attr.aria-current]="confirmationKey(c) === selectedKey()" (click)="select(confirmationKey(c))">
-            <span class="approval-inbox__summary">{{ c.tool }} · {{ c.status | sailCaption:'mcp_confirmation_status' }}</span>
-            @if (c.status === 'P') {
-              <span class="approval-inbox__deadline">Expires {{ c.expires_at | date: 'medium' }}</span>
-            }
-          </button>
-        </li>
-      }
-    </ul>
     <button matButton type="button" [disabled]="loading()" (click)="load()">Refresh</button>
-  </section>
+  </nav>
 
   @if (selected(); as request) {
     <section class="approval-inbox__decision" aria-label="Decision">
-      <h3>{{ request.summary || request.action }}</h3>
+      <h3 #heading tabindex="-1">{{ request.summary || request.action }}</h3>
       <dl>
         <dt>Action</dt><dd>{{ request.action }}</dd>
         <dt>Resource</dt><dd>{{ request.resource }}</dd>
@@ -60,45 +64,64 @@
         <textarea matInput rows="4" [value]="revisedArguments()" (input)="revisedArguments.set($any($event.target).value)"></textarea>
       </mat-form-field>
 
-      <div class="approval-inbox__actions">
-        <button matButton="elevated" type="button" [disabled]="loading()" (click)="decide('A')">Approve</button>
-        <button matButton type="button" class="warn" [disabled]="loading()" (click)="decide('X')">Reject</button>
-        <button matButton type="button" [disabled]="loading() || !revisedArguments().trim()" (click)="decide('E')">Edit and run</button>
+      <div class="approval-inbox__actions" role="group" aria-label="Decide">
+        @if (confirming()) {
+          <span>Approve this action? It runs exactly as shown.</span>
+          <button #yes matButton="filled" type="button" [disabled]="loading()" (click)="decide('A')">Yes, approve</button>
+          <button matButton type="button" [disabled]="loading()" (click)="cancelApprove()">Cancel</button>
+        } @else {
+          <button matButton="filled" type="button" [disabled]="loading()" (click)="askApprove()">Approve</button>
+          <button matButton type="button" class="warn" [disabled]="loading()" (click)="decide('X')">Reject</button>
+          <button matButton type="button" [disabled]="loading() || !revisedArguments().trim()" (click)="decide('E')">Edit and run</button>
+        }
       </div>
     </section>
   }
 
   @if (selectedConfirmation(); as c) {
     <section class="approval-inbox__decision" aria-label="Confirmation">
-      <h3>{{ c.tool }}</h3>
+      <h3 #heading tabindex="-1">{{ c.tool }}</h3>
       <dl>
+        <dt>Workspace</dt><dd>{{ c.tenant_label || c.tenant_id }}</dd>
         <dt>Status</dt><dd>{{ c.status | sailCaption:'mcp_confirmation_status' }}@if (c.expired) { (expired) }</dd>
-        <dt>Requested by</dt><dd>{{ c.maker.kind }} {{ c.maker.id }}@if (c.client_ref) { through {{ c.client_ref }} }</dd>
+        <dt>Requested by</dt><dd>{{ name(c.maker) }}@if (c.client_label || c.client_ref) { through {{ c.client_label || c.client_ref }} }</dd>
         <dt>Requested</dt><dd>{{ c.created_at | date: 'medium' }} · expires {{ c.expires_at | date: 'medium' }}</dd>
         @if (c.approval_required) { <dt>Maker-checker</dt><dd>A second person must approve</dd> }
-        @if (c.decider; as d) { <dt>Decided</dt><dd>{{ d.kind }} {{ d.id }} · {{ c.decided_at | date: 'medium' }} {{ c.decision_note }}</dd> }
-        @if (c.reconciler; as r) { <dt>Reconciled</dt><dd>{{ r.kind }} {{ r.id }} {{ c.reconcile_note }}</dd> }
+        @if (c.decider; as d) { <dt>Decided</dt><dd>{{ name(d) }} · {{ c.decided_at | date: 'medium' }} {{ c.decision_note }}</dd> }
+        @if (c.completed_at) { <dt>Finished</dt><dd>{{ c.completed_at | date: 'medium' }}</dd> }
+        @if (c.reconciler; as r) { <dt>Reconciled</dt><dd>{{ name(r) }} {{ c.reconcile_note }}</dd> }
         @if (c.error) { <dt>Error</dt><dd>{{ c.error }}</dd> }
       </dl>
-      @if (c.preview !== undefined) { <pre class="approval-inbox__preview">{{ c.preview | json }}</pre> }
+      @if (previewTemplate(c.tool); as template) {
+        <ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ $implicit: c }" />
+      } @else if (c.preview !== undefined) {
+        <pre class="approval-inbox__preview">{{ c.preview | json }}</pre>
+      }
 
       @if (c.can_decide || c.can_reconcile) {
         <mat-form-field>
-          <mat-label>Note (optional)</mat-label>
-          <textarea matInput rows="2" [value]="reason()" (input)="reason.set($any($event.target).value)"></textarea>
+          <mat-label>{{ c.can_reconcile ? 'What you verified (required)' : 'Note (optional)' }}</mat-label>
+          <textarea matInput rows="2" [maxLength]="noteMax" [required]="c.can_reconcile" [value]="reason()"
+            (input)="reason.set($any($event.target).value)"></textarea>
         </mat-form-field>
       }
-      <div class="approval-inbox__actions">
+      <div class="approval-inbox__actions" role="group" aria-label="Decide">
         @if (c.can_decide) {
-          <button matButton="elevated" type="button" [disabled]="loading()" (click)="confirm(true)">Confirm</button>
-          <button matButton type="button" class="warn" [disabled]="loading()" (click)="confirm(false)">Decline</button>
+          @if (confirming()) {
+            <span>Confirm this action? It runs exactly as shown.</span>
+            <button #yes matButton="filled" type="button" [disabled]="loading()" (click)="confirm(true)">Yes, confirm</button>
+            <button matButton type="button" [disabled]="loading()" (click)="cancelApprove()">Cancel</button>
+          } @else {
+            <button matButton="filled" type="button" [disabled]="loading()" (click)="askApprove()">Confirm</button>
+            <button matButton type="button" class="warn" [disabled]="loading()" (click)="confirm(false)">Decline</button>
+          }
         }
         @if (c.can_withdraw) {
           <button matButton type="button" [disabled]="loading()" (click)="withdraw()">Withdraw</button>
         }
         @if (c.can_reconcile) {
-          <button matButton type="button" [disabled]="loading()" (click)="reconcile('D')">Mark executed</button>
-          <button matButton type="button" [disabled]="loading()" (click)="reconcile('F')">Mark failed</button>
+          <button matButton type="button" [disabled]="loading() || !reason().trim()" (click)="reconcile('D')">Mark executed</button>
+          <button matButton type="button" [disabled]="loading() || !reason().trim()" (click)="reconcile('F')">Mark failed</button>
         }
       </div>
     </section>
@@ -107,4 +130,5 @@
   @if (errorMessage()) {
     <p class="approval-inbox__error" role="alert">{{ errorMessage() }}</p>
   }
+  <p class="approval-inbox__status" role="status">{{ successMessage() }}</p>
 </div>

package/src/agent/component/approval_inbox.ts

@@ -1,37 +1,88 @@
-import { DatePipe, JsonPipe } from '@angular/common';
-import { ChangeDetectionStrategy, Component, OnInit, computed, inject, output, signal } from '@angular/core';
+import { DatePipe, JsonPipe, NgTemplateOutlet } from '@angular/common';
+import {
+  ChangeDetectionStrategy, Component, Directive, ElementRef, Injector, OnInit, Signal, TemplateRef, afterNextRender,
+  computed, contentChildren, inject, input, output, signal, viewChild,
+} from '@angular/core';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import { MatInputModule } from '@angular/material/input';
-import { Observable, forkJoin } from 'rxjs';
+import { Observable, catchError, forkJoin, of } from 'rxjs';
 import { BaseAsync } from '../../component/abstract/base_async';
 import { CaptionPipe } from '../../service/caption_pipe';
-import { ApprovalRequest, ApprovalVerdict, Confirmation } from '../model/approval';
+import { errorDetail, httpStatus } from '../../util/errors';
+import {
+  ApprovalRequest, ApprovalVerdict, CONFIRMATION_NOTE_MAX, Confirmation, ReconcileOutcome,
+} from '../model/approval';
+import { principalName } from '../model/decision';
 import { ApprovalService } from '../service/approval.service';
 
+export interface ApprovalPreviewContext {
+  $implicit: Confirmation;
+}
+
+/**
+ * How one tool's confirmation preview reads, or every other tool's with `"*"`:
+ * `<ng-template sailApprovalPreview="tool" let-c>…</ng-template>`. Without one the preview prints as JSON.
+ */
+@Directive({ selector: 'ng-template[sailApprovalPreview]' })
+export class ApprovalPreviewDirective {
+  readonly tool = input.required<string>({ alias: 'sailApprovalPreview' });
+  readonly template = inject<TemplateRef<ApprovalPreviewContext>>(TemplateRef);
+
+  static ngTemplateContextGuard(_dir: ApprovalPreviewDirective, ctx: unknown): ctx is ApprovalPreviewContext {
+    return true;
+  }
+}
+
+export interface ApprovalInboxSection {
+  title: string;
+  requests: ApprovalRequest[];
+  confirmations: Confirmation[];
+}
+
+const actionErrors: Record<number, string> = {
+  403: 'You are not allowed to do this here.',
+  404: 'This item no longer exists, or you can no longer see it; the list was refreshed.',
+  409: 'This item changed or was decided elsewhere; the list was refreshed.',
+};
+
 /**
- * The signed-in person's pending approvals and MCP confirmations with a decision view: approve,
- * reject, or edit a tool call's arguments; confirm, decline, withdraw, or reconcile a confirmation.
- * A 409 (reassigned or decided elsewhere) reloads the list.
+ * The signed-in person's pending approvals and MCP confirmations, grouped as waiting, submitted,
+ * needing reconciliation and recent, with a decision view: approve, reject, or edit a tool call's
+ * arguments; confirm, decline, withdraw, or reconcile a confirmation. Approving asks once more, and
+ * reconciling requires a note. A list the backend does not serve (404) stays empty.
  * Selector: <sail-approval-inbox>.
  */
 @Component({
   selector: 'sail-approval-inbox',
   changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [DatePipe, JsonPipe, MatButtonModule, MatFormFieldModule, MatInputModule, CaptionPipe],
+  imports: [DatePipe, JsonPipe, NgTemplateOutlet, MatButtonModule, MatFormFieldModule, MatInputModule, CaptionPipe],
   templateUrl: './approval_inbox.html',
 })
 export class ApprovalInboxComponent extends BaseAsync implements OnInit {
   private readonly approvals = inject(ApprovalService);
+  private readonly injector = inject(Injector);
+  private readonly previews = contentChildren(ApprovalPreviewDirective);
+  private readonly heading = viewChild<ElementRef<HTMLElement>>('heading');
+  private readonly yes = viewChild<ElementRef<HTMLElement>>('yes');
+  private opened = '';
+
+  /** The item to open first: an approval or confirmation key, or a confirmation id from a link. */
+  readonly open = input('');
 
   readonly decided = output<ApprovalRequest>();
   readonly confirmationChanged = output<Confirmation>();
 
+  readonly noteMax = CONFIRMATION_NOTE_MAX;
+  readonly name = principalName;
   readonly requests = signal<ApprovalRequest[]>([]);
   readonly confirmations = signal<Confirmation[]>([]);
+  readonly sections = computed(() => groupInbox(this.requests(), this.confirmations()));
   readonly selectedKey = signal('');
   readonly reason = signal('');
   readonly revisedArguments = signal('');
+  /** The approve step awaits its second click. */
+  readonly confirming = signal(false);
   readonly selected = computed(() => this.requests().find((r) => this.key(r) === this.selectedKey()));
   readonly selectedConfirmation = computed(() => this.confirmations().find((c) => this.confirmationKey(c) === this.selectedKey()));
 
@@ -40,47 +91,52 @@ export class ApprovalInboxComponent extends BaseAsync implements OnInit {
   }
 
   load(): void {
-    this.run(forkJoin([this.approvals.pending(), this.approvals.confirmations()]), ([requests, confirmations]) => {
+    this.run(forkJoin([
+      this.listed(this.approvals.pending(), this.requests(), 'Failed to load approvals.'),
+      this.listed(this.approvals.confirmations(), this.confirmations(), 'Failed to load confirmations.'),
+    ]), ([requests, confirmations]) => {
       this.requests.set(requests);
       this.confirmations.set(confirmations);
-      if (!this.selected() && !this.selectedConfirmation()) this.select(requests[0] ? this.key(requests[0]) : confirmations[0] ? this.confirmationKey(confirmations[0]) : '');
-    }, 'Failed to load approvals.');
+      const link = this.open();
+      if (link && link !== this.opened) {
+        const linked = requests.find((r) => this.key(r) === link)
+          ?? confirmations.find((c) => this.confirmationKey(c) === link || String(c.id) === link);
+        if (linked) {
+          this.opened = link;
+          this.select('request_id' in linked ? this.key(linked) : this.confirmationKey(linked));
+          this.focus(this.heading);
+          return;
+        }
+        if (!this.successMessage()) {
+          this.successMessage.set('The linked item is not listed: it may be decided, withdrawn or expired, or not yours to act on.');
+        }
+      }
+      if (!this.selected() && !this.selectedConfirmation()) {
+        this.selectFirst();
+      }
+    });
   }
 
   select(key: string): void {
     this.selectedKey.set(key);
     this.reason.set('');
     this.revisedArguments.set('');
+    this.confirming.set(false);
   }
 
-  confirm(approve: boolean): void {
-    const c = this.selectedConfirmation();
-    if (!c) return;
-    this.applyConfirmation(this.approvals.decideConfirmation(c, approve, this.reason().trim()));
+  askApprove(): void {
+    this.confirming.set(true);
+    this.focus(this.yes);
   }
 
-  withdraw(): void {
-    const c = this.selectedConfirmation();
-    if (!c || !window.confirm('Withdraw this confirmation?')) return;
-    this.run(this.approvals.withdrawConfirmation(c), () => this.load(), 'Failed to withdraw the confirmation.');
+  cancelApprove(): void {
+    this.confirming.set(false);
+    this.focus(this.heading);
   }
 
-  reconcile(outcome: 'D' | 'F'): void {
-    const c = this.selectedConfirmation();
-    if (!c) return;
-    this.applyConfirmation(this.approvals.reconcileConfirmation(c, outcome, this.reason().trim()));
-  }
-
-  private applyConfirmation(request: Observable<Confirmation>): void {
-    this.run(request, (result) => {
-      this.confirmations.update((rows) => rows.map((c) => c.id === result.id && c.tenant_id === result.tenant_id ? result : c));
-      this.reason.set('');
-      this.confirmationChanged.emit(result);
-    }, 'Failed to record the decision.', (err) => this.reloadOnConflict(err));
-  }
-
-  confirmationKey(c: Confirmation): string {
-    return `${c.tenant_id}/${c.id}`;
+  previewTemplate(tool: string): TemplateRef<ApprovalPreviewContext> | undefined {
+    const previews = this.previews();
+    return (previews.find((p) => p.tool() === tool) ?? previews.find((p) => p.tool() === '*'))?.template;
   }
 
   decide(verdict: ApprovalVerdict): void {
@@ -94,7 +150,7 @@ export class ApprovalInboxComponent extends BaseAsync implements OnInit {
         return;
       }
     }
-    this.run(this.approvals.resolve({
+    this.act(this.approvals.resolve({
       request_id: request.request_id,
       execution_step_id: request.execution_step_id,
       verdict,
@@ -103,20 +159,108 @@ export class ApprovalInboxComponent extends BaseAsync implements OnInit {
       revised_arguments: revised,
     }), (result) => {
       this.requests.update((rows) => rows.filter((r) => this.key(r) !== this.key(request)));
-      this.select(this.requests()[0] ? this.key(this.requests()[0]) : '');
+      this.selectFirst();
       this.decided.emit(result);
-    }, 'Failed to record the decision.', (err) => this.reloadOnConflict(err));
+      return verdict === 'X' ? 'Rejected.' : 'Approved.';
+    });
   }
 
-  private reloadOnConflict(err: unknown): void {
-    if ((err as { status?: number })?.status !== 409) return;
-    this.load();
-    this.errorMessage.set('This request was reassigned or decided elsewhere; the list was refreshed.');
+  confirm(approve: boolean): void {
+    const c = this.selectedConfirmation();
+    if (!c) return;
+    this.applyConfirmation(this.approvals.decideConfirmation(c, approve, this.reason().trim()),
+      approve ? 'Confirmed; the action runs shortly.' : 'Declined; nothing was done.');
+  }
+
+  withdraw(): void {
+    const c = this.selectedConfirmation();
+    if (!c || !window.confirm('Withdraw this confirmation?')) return;
+    this.act(this.approvals.withdrawConfirmation(c), () => {
+      this.load();
+      return 'Withdrawn; nothing will be done.';
+    });
+  }
+
+  reconcile(outcome: ReconcileOutcome): void {
+    const c = this.selectedConfirmation();
+    const note = this.reason().trim();
+    if (!c || !note) return;
+    this.applyConfirmation(this.approvals.reconcileConfirmation(c, outcome, note), 'Outcome recorded; the action was not run again.');
   }
 
   key(request: ApprovalRequest): string {
     return `${request.request_id}#${request.execution_step_id}`;
   }
+
+  confirmationKey(c: Confirmation): string {
+    return `${c.tenant_id}/${c.id}`;
+  }
+
+  private applyConfirmation(request: Observable<Confirmation>, done: string): void {
+    this.act(request, (result) => {
+      this.confirmations.update((rows) => rows.map((c) => c.id === result.id && c.tenant_id === result.tenant_id ? result : c));
+      this.confirmationChanged.emit(result);
+      return done;
+    });
+  }
+
+  private act<T>(request: Observable<T>, done: (result: T) => string): void {
+    this.run(request, (result) => {
+      this.reason.set('');
+      this.confirming.set(false);
+      this.successMessage.set(done(result));
+      this.focus(this.heading);
+    }, 'Failed to record the decision.', (err) => {
+      const status = httpStatus(err);
+      const message = actionErrors[status ?? 0];
+      if (!message) return;
+      if (status !== 403) this.load();
+      this.errorMessage.set(message);
+    });
+  }
+
+  private listed<T>(list: Observable<T[]>, current: T[], failed: string): Observable<T[]> {
+    return list.pipe(catchError((err) => {
+      if (httpStatus(err) === 404) return of([]);
+      this.errorMessage.set(errorDetail(err, failed));
+      return of(current);
+    }));
+  }
+
+  private focus(target: Signal<ElementRef<HTMLElement> | undefined>): void {
+    afterNextRender(() => target()?.nativeElement.focus(), { injector: this.injector });
+  }
+
+  private selectFirst(): void {
+    const first = this.sections()[0];
+    this.select(first?.requests[0] ? this.key(first.requests[0])
+      : first?.confirmations[0] ? this.confirmationKey(first.confirmations[0]) : '');
+  }
+}
+
+/** Approvals wait first; confirmations land in the first section they qualify for, open ones soonest expiry first. */
+export function groupInbox(requests: ApprovalRequest[], confirmations: Confirmation[]): ApprovalInboxSection[] {
+  const sections: ApprovalInboxSection[] = [
+    { title: 'Waiting for your decision', requests, confirmations: [] },
+    { title: 'Submitted by you', requests: [], confirmations: [] },
+    { title: 'Needs reconciliation', requests: [], confirmations: [] },
+    { title: 'Recent', requests: [], confirmations: [] },
+  ];
+  for (const c of confirmations) {
+    sections[c.can_decide ? 0 : c.can_withdraw ? 1 : c.can_reconcile ? 2 : 3].confirmations.push(c);
+  }
+  sections.forEach((s, i) => s.confirmations.sort(i < 2
+    ? (a, b) => time(a.expires_at) - time(b.expires_at)
+    : (a, b) => lastActivity(b) - lastActivity(a)));
+  return sections.filter((s) => s.requests.length || s.confirmations.length);
+}
+
+function time(value: string | undefined): number {
+  return (value && Date.parse(value)) || 0;
+}
+
+function lastActivity(c: Confirmation): number {
+  return Math.max(time(c.created_at), time(c.decided_at), time(c.completed_at));
 }
 
 function parseObject(text: string): Record<string, unknown> | undefined {

package/src/agent/component/assistant_activity.html

@@ -11,9 +11,9 @@
             <td><code>{{ record.action }}</code></td>
             <td>{{ record.resource }}</td>
             <td>{{ record.outcome | sailCaption:'audit_decision_outcome' }}@if (record.reason) { <span class="assistant-activity__reason">({{ record.reason }})</span> }</td>
-            <td>{{ who()(record) }}</td>
-            <td>{{ record.client_ref }}</td>
-            <td>@if (record.authority; as a) { {{ a.subject.kind }} {{ a.subject.id }} }</td>
+            <td>{{ name(record.principal) }}</td>
+            <td>{{ record.client_label || record.client_ref }}</td>
+            <td>@if (record.authority; as a) { {{ name(a.subject) }} }</td>
           </tr>
         }
       </tbody>

package/src/agent/component/assistant_activity.ts

@@ -3,12 +3,13 @@ import { ChangeDetectionStrategy, Component, OnInit, inject, input, signal } fro
 import { MatButtonModule } from '@angular/material/button';
 import { BaseAsync } from '../../component/abstract/base_async';
 import { CaptionPipe } from '../../service/caption_pipe';
-import { DecisionOutcome, DecisionRecord } from '../model/decision';
+import { DecisionOutcome, DecisionRecord, principalName } from '../model/decision';
 import { AgentStudioService } from '../service/agent_studio.service';
 
 /**
  * What assistants did in the tenant: Scout's decision records (`decisions` feature, `AGENT_AUDIT`
- * `VIEW`), newest first and paged by `next_before`. Selector: <sail-assistant-activity>.
+ * `VIEW`), newest first and paged by `next_before`, named by the product's labeler.
+ * Selector: <sail-assistant-activity>.
  */
 @Component({
   selector: 'sail-assistant-activity',
@@ -21,8 +22,7 @@ export class AssistantActivityComponent extends BaseAsync implements OnInit {
 
   readonly category = input('');
   readonly outcome = input<DecisionOutcome | undefined>(undefined);
-  /** Who acted, as the app names its principals; kind and id by default. */
-  readonly who = input<(record: DecisionRecord) => string>((r) => `${r.principal.kind} ${r.principal.id}`);
+  readonly name = principalName;
 
   readonly records = signal<DecisionRecord[]>([]);
   readonly nextBefore = signal(0);

package/src/agent/component/studio_page.ts

@@ -13,7 +13,7 @@ import { BaseAuthService } from '../../service/auth.service';
 import { CaptionPipe } from '../../service/caption_pipe';
 import { LabelOption, LabelService } from '../../service/label.service';
 import {
-  AGENT_READINESS_CAPTIONS, AgentAuditEvent, AgentDraft, AgentGuardrails, AgentLanguageDraft, AgentMergeMode,
+  AGENT_READINESS_CAPTIONS, AgentAuditEvent, AgentReadiness, AgentDraft, AgentGuardrails, AgentLanguageDraft, AgentMergeMode,
   AgentModelSelection, AgentRelease, AgentSetting, AgentSettings, AgentSummary, AgentTestResult, GuardrailRule,
   SafetyEvent, StudioFeature, StudioModel,
 } from '../model/agent_studio';
@@ -127,7 +127,7 @@ export class StudioPageComponent implements OnInit {
     return this.features().find((f) => f.id === id);
   }
 
-  readinessCaption(code: string): string {
+  readinessCaption(code: AgentReadiness): string {
     return AGENT_READINESS_CAPTIONS[code] ?? code;
   }
 

package/src/agent/component/turn_thread.html

@@ -10,8 +10,8 @@
         @if (turn.cost_minor !== undefined && turn.currency && turn.exponent !== undefined) { · {{ turn.cost_minor | sailMoney:turn.currency:turn.exponent }} }
         @if (turn.release_version) { · {{ turn.agent_name }} v{{ turn.release_version }} }
       </p>
-      @if (turn.status === 'F' && turn.error_text) {
-        <p class="turn-thread__error" role="alert">{{ turn.error_text }}</p>
+      @if (turn.status === 'F') {
+        <p class="turn-thread__error" role="alert">{{ turn.error_text || failedText() }}</p>
       }
       @if (resultTemplate(turn.task_kind); as template) {
         <ng-container [ngTemplateOutlet]="template" [ngTemplateOutletContext]="{ $implicit: turn }" />

package/src/agent/component/turn_thread.ts

@@ -9,14 +9,22 @@ import { MoneyPipe } from '../../service/money_pipe';
 import { ConversationTurn, TERMINAL_TURN_STATUSES } from '../model/conversation';
 import { ConversationService } from '../service/conversation.service';
 
+export interface TurnResultContext {
+  $implicit: ConversationTurn;
+}
+
 /**
- * The result card of one task kind: `<ng-template sailTurnResult="kind" let-turn>…</ng-template>`.
- * The template's context is the turn.
+ * The result card of one task kind, or of every other kind with `"*"`:
+ * `<ng-template sailTurnResult="kind" let-turn>…</ng-template>`.
  */
 @Directive({ selector: 'ng-template[sailTurnResult]' })
 export class TurnResultDirective {
   readonly kind = input.required<string>({ alias: 'sailTurnResult' });
-  readonly template = inject<TemplateRef<{ $implicit: ConversationTurn }>>(TemplateRef);
+  readonly template = inject<TemplateRef<TurnResultContext>>(TemplateRef);
+
+  static ngTemplateContextGuard(_dir: TurnResultDirective, ctx: unknown): ctx is TurnResultContext {
+    return true;
+  }
 }
 
 /**
@@ -39,6 +47,8 @@ export class TurnThreadComponent extends BaseAsync implements OnInit {
   readonly kindLabels = input<Record<string, string>>({});
   readonly pollMs = input(10000);
   readonly emptyMessage = input('Nothing yet.');
+  /** Shown for a failed turn that carries no error text. */
+  readonly failedText = input('The turn failed.');
 
   readonly turns = signal<ConversationTurn[]>([]);
   readonly nextBefore = signal('');
@@ -77,7 +87,8 @@ export class TurnThreadComponent extends BaseAsync implements OnInit {
     return this.kindLabels()[kind] ?? kind;
   }
 
-  resultTemplate(kind: string): TemplateRef<{ $implicit: ConversationTurn }> | undefined {
-    return this.results().find((r) => r.kind() === kind)?.template;
+  resultTemplate(kind: string): TemplateRef<TurnResultContext> | undefined {
+    const results = this.results();
+    return (results.find((r) => r.kind() === kind) ?? results.find((r) => r.kind() === '*'))?.template;
   }
 }

package/src/agent/model/agent_studio.ts

@@ -12,7 +12,7 @@ export interface AgentSummary {
   enabled: boolean;
   is_default: boolean;
   archived: boolean;
-  readiness: string;
+  readiness: AgentReadiness;
   readiness_reason: string;
   type_defaults_revision: number;
   agent_revision: number;
@@ -310,8 +310,11 @@ export interface AgentSettingChange {
   expected_type_defaults_revision: number;
 }
 
-/** Captions for Scout's fixed `AgentReadiness` values, which no constant domain carries. */
-export const AGENT_READINESS_CAPTIONS: Record<string, string> = {
+/** Scout's fixed `AgentReadiness` values, which no constant domain carries. */
+export type AgentReadiness =
+  'ready' | 'disabled' | 'missing_model' | 'unpublished' | 'error' | 'not_entitled' | 'needs_integration' | 'forbidden';
+
+export const AGENT_READINESS_CAPTIONS: Record<AgentReadiness, string> = {
   ready: 'Ready',
   disabled: 'Disabled',
   missing_model: 'No text model',

package/src/agent/model/approval.ts

@@ -1,6 +1,6 @@
 import { PrincipalRef } from './decision';
 
-/** Scout approval desk and MCP confirmation inbox wire types (v1.2.13). Codes render through backend captions. */
+/** Scout approval desk and MCP confirmation inbox wire types (v1.2.14). Codes render through backend captions. */
 
 /** A approved, X rejected, E edited (tool-call proposals only, with revised arguments). */
 export type ApprovalVerdict = 'A' | 'X' | 'E';
@@ -46,6 +46,12 @@ export interface ApprovalResolveRequest {
 /** `mcp_confirmation_status`: P pending, A approved, R running, D executed, F failed, U unknown, X declined, W withdrawn, T expired. */
 export type ConfirmationStatus = 'P' | 'A' | 'R' | 'D' | 'F' | 'U' | 'X' | 'W' | 'T';
 
+/** A verified reconciliation outcome. */
+export type ReconcileOutcome = Extract<ConfirmationStatus, 'D' | 'F'>;
+
+/** Scout's bound on decision and reconciliation notes, in characters. */
+export const CONFIRMATION_NOTE_MAX = 500;
+
 export interface ConfirmationKey {
   tenant_id: number;
   id: number;
@@ -53,8 +59,10 @@ export interface ConfirmationKey {
 
 /** One MCP tool call awaiting or past a person's confirmation; never its payload. */
 export interface Confirmation extends ConfirmationKey {
+  tenant_label?: string;
   maker: PrincipalRef;
   client_ref?: string;
+  client_label?: string;
   tool: string;
   payload_digest: string;
   /** The product's preview of the complete action. */

package/src/agent/model/conversation.ts

@@ -67,7 +67,10 @@ export interface ConversationTurnPage {
   next_before?: string;
 }
 
-/** Where the app mounts Scout's ConversationHandler, e.g. '/api/wingmate/'. */
+/**
+ * Where the app mounts Scout's ConversationHandler, e.g. '/api/wingmate/'. `ConversationService` is a
+ * root singleton: provide this at bootstrap, or provide both together on a component.
+ */
 export const CONVERSATION_BASE_PATH = new InjectionToken<string>('SailConversationBasePath', {
   providedIn: 'root',
   factory: () => '/api/conversation/',

package/src/agent/model/decision.ts

@@ -4,6 +4,8 @@ export type DecisionOutcome = 'A' | 'D' | 'P';
 export interface PrincipalRef {
   kind: string;
   id: string;
+  /** The product's caption for the principal (Scout `contract.Labeler`). */
+  label?: string;
 }
 
 export interface AuthorityRef {
@@ -24,6 +26,7 @@ export interface DecisionRecord {
   authority?: AuthorityRef;
   /** The client application the principal acted through. */
   client_ref?: string;
+  client_label?: string;
   work_ref?: string;
   scope_id?: string;
   release_version?: string;
@@ -46,3 +49,8 @@ export interface DecisionCategoryGroup {
   category: string;
   records: DecisionRecord[];
 }
+
+/** A principal's label, or its kind and id. */
+export function principalName(ref: PrincipalRef): string {
+  return ref.label || `${ref.kind} ${ref.id}`;
+}

package/src/agent/service/approval.service.ts

@@ -1,7 +1,7 @@
 import { Injectable } from '@angular/core';
 import { Observable } from 'rxjs';
 import { BaseRestService } from '../../service/base_rest.service';
-import { ApprovalRequest, ApprovalResolveRequest, Confirmation, ConfirmationKey } from '../model/approval';
+import { ApprovalRequest, ApprovalResolveRequest, Confirmation, ConfirmationKey, ReconcileOutcome } from '../model/approval';
 
 const base = '/api/approval/';
 
@@ -31,8 +31,8 @@ export class ApprovalService extends BaseRestService {
     return this.http.post<ConfirmationKey>(this.url(base + 'confirmation/withdraw'), key);
   }
 
-  /** Records the verified outcome of an unknown confirmation: D executed or F failed. */
-  reconcileConfirmation(key: ConfirmationKey, outcome: 'D' | 'F', note = ''): Observable<Confirmation> {
+  /** Records the verified outcome of an unknown confirmation; the note is required. */
+  reconcileConfirmation(key: ConfirmationKey, outcome: ReconcileOutcome, note: string): Observable<Confirmation> {
     return this.http.post<Confirmation>(this.url(base + 'confirmation/reconcile'), { ...key, outcome, note });
   }
 }

package/src/component/agency/agency_accept.ts

@@ -3,7 +3,7 @@ import { MatButtonModule } from '@angular/material/button';
 import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
 import { AgencyInvite } from '../../model/agency';
 import { AgencyService } from '../../service/agency.service';
-import { errorCode, errorDetail } from '../../util/errors';
+import { errorCode, errorDetail, httpStatus } from '../../util/errors';
 
 const NO_PARTNER_CODE = 'agency_no_partner';
 
@@ -71,7 +71,7 @@ export class AgencyAcceptComponent implements OnInit {
       },
       error: (error: unknown) => {
         this.accepting.set(false);
-        if (this.statusOf(error) === 409 && errorCode(error) === NO_PARTNER_CODE) {
+        if (httpStatus(error) === 409 && errorCode(error) === NO_PARTNER_CODE) {
           localStorage.setItem(this.tokenStorageKey(), this.activeToken);
           this.needsBusiness.set(true);
           return;
@@ -85,10 +85,4 @@ export class AgencyAcceptComponent implements OnInit {
     localStorage.setItem(this.tokenStorageKey(), this.activeToken);
     this.businessSetupRequested.emit(this.activeToken);
   }
-
-  private statusOf(error: unknown): number | undefined {
-    return typeof error === 'object' && error !== null && 'status' in error
-      ? Number((error as { status?: unknown }).status)
-      : undefined;
-  }
 }

package/src/component/oauth_connection/oauth_connection_panel.ts

@@ -7,6 +7,7 @@ import { MatIconModule } from '@angular/material/icon';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import { MatInputModule } from '@angular/material/input';
 import { OAuthConnectionService } from '../../service/oauth_connection.service';
+import { httpStatus } from '../../util/errors';
 import { OAuthConnectionStatus, OAuthConnectionView, PartnerCredential, OAuthProviderDescriptor, OAuthProviderFieldRole } from '../../model/oauth_connection';
 
 /**
@@ -90,7 +91,7 @@ export class OAuthConnectionPanelComponent implements OnInit {
   }
 
   private completeMsg(e: unknown): string {
-    const status = (e as { status?: number })?.status;
+    const status = httpStatus(e);
     if (status === 403) return 'This connection was started by another user — start again from this account.';
     if (status === 400) return 'The connection link expired — start again.';
     return this.msg(e, 'Could not complete the connection.');

package/src/component/security/api_keys.html

@@ -18,13 +18,19 @@
         <input matInput formControlName="allowedCidrs" maxlength="2000">
         <mat-hint>Comma-separated addresses or CIDR ranges. Empty allows any address.</mat-hint>
       </mat-form-field>
-      <fieldset class="api-keys__scopes">
-        <legend>Scopes</legend>
-        @for (scope of scopes(); track scope.code) {
-          <mat-checkbox [checked]="form.controls.scopes.value.includes(scope.code)"
-            (change)="toggleScope(scope.code, $event.checked)">{{ scope.caption }}</mat-checkbox>
-        }
-      </fieldset>
+      <mat-form-field>
+        <mat-label>Expires (optional)</mat-label>
+        <input matInput type="datetime-local" formControlName="expiresAt">
+      </mat-form-field>
+      @if (scopes().length) {
+        <fieldset class="api-keys__scopes">
+          <legend>Scopes</legend>
+          @for (scope of scopes(); track scope.code) {
+            <mat-checkbox [checked]="form.controls.scopes.value.includes(scope.code)"
+              (change)="toggleScope(scope.code, $event.checked)">{{ scope.caption }}</mat-checkbox>
+          }
+        </fieldset>
+      }
       <button matButton="filled" type="submit" [disabled]="form.invalid || loading()">Create key</button>
     </form>
   }
@@ -32,7 +38,7 @@
   @if (keys().length > 0) {
     <table class="api-keys__table">
       <thead>
-        <tr><th>Name</th><th>Prefix</th><th>Scopes</th><th>Networks</th><th>Created</th><th>Last used</th><th><span class="cdk-visually-hidden">Actions</span></th></tr>
+        <tr><th>Name</th><th>Prefix</th><th>Scopes</th><th>Networks</th><th>Created</th><th>Expires</th><th>Last used</th><th><span class="cdk-visually-hidden">Actions</span></th></tr>
       </thead>
       <tbody>
         @for (key of keys(); track key.Id) {
@@ -51,6 +57,7 @@
               }
             </td>
             <td>{{ key.CreatedAt | date: 'short' }}</td>
+            <td>{{ key.ExpiresAt ? (key.ExpiresAt | date: 'short') : 'never' }}</td>
             <td>{{ key.LastUsedAt ? (key.LastUsedAt | date: 'short') : '' }}</td>
             <td>
               @if (restricting() === key.Id) {

package/src/component/security/api_keys.ts

@@ -11,9 +11,9 @@ import { LabelOption } from '../../service/label.service';
 import { BaseAsync } from '../abstract/base_async';
 
 /**
- * The partner's API keys: mint one with scopes and allowed networks (the plaintext shows once),
- * restrict its networks later, or revoke it. The app passes the scopes it offers; keel's
- * `ScopePolicy` still decides. Selector: <sail-api-keys>.
+ * The partner's API keys: mint one with scopes, allowed networks and an optional expiry (the
+ * plaintext shows once), restrict its networks later, or revoke it. The app passes the scopes it
+ * offers; keel's `ScopePolicy` decides and may supply them. Selector: <sail-api-keys>.
  */
 @Component({
   selector: 'sail-api-keys',
@@ -27,7 +27,7 @@ export class ApiKeysComponent extends BaseAsync implements OnInit {
   private readonly fb = inject(FormBuilder).nonNullable;
 
   /** Scopes offered for a new key, as code and caption. */
-  readonly scopes = input.required<LabelOption[]>();
+  readonly scopes = input<LabelOption[]>([]);
 
   readonly canGenerate = this.access.canApiKeyAction('generate');
   readonly canRestrict = this.access.canApiKeyAction('restrict');
@@ -39,7 +39,8 @@ export class ApiKeysComponent extends BaseAsync implements OnInit {
   readonly form = this.fb.group({
     keyName:      ['', [Validators.required, Validators.maxLength(100)]],
     allowedCidrs: ['', Validators.maxLength(2000)],
-    scopes:       [[] as string[], Validators.required],
+    scopes:       [[] as string[]],
+    expiresAt:    [''],
   });
   readonly networks = this.fb.control('', Validators.maxLength(2000));
 
@@ -58,8 +59,13 @@ export class ApiKeysComponent extends BaseAsync implements OnInit {
 
   mint(): void {
     if (this.form.invalid) return;
-    const { keyName, scopes, allowedCidrs } = this.form.getRawValue();
-    this.run(this.access.mintApiKey(keyName, scopes, allowedCidrs), (key) => {
+    const { keyName, scopes, allowedCidrs, expiresAt } = this.form.getRawValue();
+    this.run(this.access.mintApiKey({
+      key_name: keyName,
+      scopes: scopes.join(','),
+      allowed_cidrs: allowedCidrs,
+      expires_at: expiresAt ? new Date(expiresAt).toISOString() : undefined,
+    }), (key) => {
       this.minted.set(key);
       this.form.reset();
       this.load();

package/src/model/access.ts

@@ -12,6 +12,15 @@ export interface ApiKey {
   AllowedCidrs?: string;   // CSV of networks; absent allows any address
 }
 
+/** keel `api_key/generate` request; blank scopes are the product `ScopePolicy`'s to supply. */
+export type NewApiKey = {
+  key_name:      string;
+  scopes:        string;   // CSV
+  allowed_cidrs: string;
+  /** RFC 3339; absent never expires. */
+  expires_at?:   string;
+};
+
 /** keel `api_key/generate` reply: the plaintext is shown once and never stored. */
 export interface MintedApiKey {
   api_key:    string;

package/src/service/access.service.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@angular/core';
 import { Observable, catchError, throwError } from 'rxjs';
-import { ApiKey, MintedApiKey, OAuthGrant } from '../model/access';
+import { ApiKey, MintedApiKey, NewApiKey, OAuthGrant } from '../model/access';
 import { TableAction } from '../model/appdata';
 import { BackendService } from './rest_service';
 import { RestURL } from './rest_url';
@@ -12,9 +12,8 @@ export class AccessService extends BackendService {
     return this.list<ApiKey>('api_key', undefined, { orderBy: 'created_at desc' });
   }
 
-  mintApiKey(keyName: string, scopes: string[], allowedCidrs: string): Observable<MintedApiKey> {
-    return this.apiKeyAction<MintedApiKey>('generate',
-      { key_name: keyName, scopes: scopes.join(','), allowed_cidrs: allowedCidrs });
+  mintApiKey(key: NewApiKey): Observable<MintedApiKey> {
+    return this.apiKeyAction<MintedApiKey>('generate', key);
   }
 
   restrictApiKey(id: number, allowedCidrs: string): Observable<void> {

package/src/service/auth.service.ts

@@ -2,6 +2,7 @@ import { Injectable, WritableSignal, inject, signal } from '@angular/core';
 import { HttpErrorResponse, HttpParams } from '@angular/common/http';
 import { filter, finalize, map, mergeMap, shareReplay, take, tap } from 'rxjs/operators';
 import { PasswordRules } from '../util/password_policy';
+import { httpStatus } from '../util/errors';
 import { ActiveSession, ApplicationData, ConfirmRegisterResponse, DictionaryPath, LoginResponse2FA, PartnerCreated, PartnerRegistration, PartnerSetup, RestReport, TableDefinition, TokenPair, TrustedDevice, TwoFactorSetupResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from '../model/appdata';
 import {
   LoginResponseSocial,
@@ -289,7 +290,7 @@ export abstract class BaseAuthService extends BaseRestService {
       },
       error: (err: unknown) => {
         console.error('Session handoff failed:', err);
-        this.sessionHandoffError.set(handoffErrorMessage((err as { status?: number } | null)?.status));
+        this.sessionHandoffError.set(handoffErrorMessage(httpStatus(err)));
       },
     });
   }

package/src/util/errors.ts

@@ -21,7 +21,8 @@ function asString(value: unknown): string | undefined {
   return typeof value === 'string' && value ? value : undefined;
 }
 
-function statusOf(err: unknown): number | undefined {
+/** The HTTP status of any sail error shape; undefined when it carries none. */
+export function httpStatus(err: unknown): number | undefined {
   if (!err || typeof err !== 'object') return undefined;
   const s = (err as { status?: unknown }).status;
   return typeof s === 'number' ? s : undefined;
@@ -34,12 +35,12 @@ function statusOf(err: unknown): number | undefined {
  * available. Use it to offer a retry rather than reporting a backend rejection.
  */
 export function isTransportFailure(err: unknown): boolean {
-  return statusOf(err) === 0;
+  return httpStatus(err) === 0;
 }
 
 /** True for keel's 403: the session is valid but lacks the grant for this action. */
 export function isPermissionDenied(err: unknown): boolean {
-  return statusOf(err) === 403;
+  return httpStatus(err) === 403;
 }
 
 /**
@@ -55,7 +56,7 @@ export function isPermissionDenied(err: unknown): boolean {
  * exposing their response text.
  */
 export function errorDetail(err: unknown, fallback: string, statuses?: readonly number[]): string {
-  const status = statusOf(err);
+  const status = httpStatus(err);
   if (statuses && status !== undefined && !statuses.includes(status)) {
     return fallback;
   }