fix(approvals): admin override to recover an approval routed to an unstaffed position (#3424)

An `approval` node routed to a position/team with no holders resolved to only
the unresolvable `position:<name>` literal in `pending_approvers`, so no
concrete user was in the slate. Every normal `decide` / `reassign` / `recall`
then returned FORBIDDEN and, with `lockRecord`, the target record stayed
RECORD_LOCKED forever — a data-availability dead-end with no in-product recovery.
Trivial to hit in fresh/demo orgs (positions seeded, holders not) and whenever a
role is vacated.

Let a platform or tenant admin act on any pending request to release it: approve,
reject, reassign it to a real approver, or recall it. The override finalizes the
request (which releases the record lock, keyed on a pending request); a tenant
admin's authority is org-scoped, a platform admin's is not, and the action is
audited under the admin's own id. An admin approval is authoritative — it
finalizes the node even under unanimous/quorum/per_group rather than counting as
one vote among the (empty) slate.

- Add server-computed `sys_approval_request.viewer.can_override`; the
  approve/reject/reassign declared actions OR it into their `visible` gate so the
  console surfaces the recovery path with no hand-wired button.
- Warn loudly when a node resolves to no concrete approver, so the
  misconfiguration is visible instead of silently locking the record. The
  literal-fallback behavior (15.x slot back-compat) is otherwise unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VmQPXXbgomoqrXtoxr3CS2

Author: claude

.changeset/approval-empty-position-admin-override.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/plugin-approvals": patch
+"@objectstack/spec": patch
+---
+
+fix(approvals): admin override for a request routed to an unstaffed approver (#3424)
+
+An `approval` node routed to a `position` (or `team`/`department`) with **no
+holders** resolved to only the unresolvable `position:<name>` literal in
+`pending_approvers` — no concrete user was in the slate. Every normal
+`decide` / `reassign` / `recall` then returned `FORBIDDEN` (not a pending
+approver) and, with `lockRecord`, the target record stayed `RECORD_LOCKED`
+forever: a data-availability dead-end with no in-product recovery (the only exit
+was editing the DB by hand). Very easy to hit in fresh/demo orgs (positions
+seeded, holders not) and whenever a role is vacated in production.
+
+A **platform or tenant admin** — the same posture the engine's superuser bypass
+already trusts — may now act on any *pending* request to release it: **approve,
+reject, reassign** it to a real approver, or **recall** it. The override finalizes
+the request (which releases the record lock, keyed on a pending request); a
+tenant admin's authority is org-scoped, a platform admin's is not, and the
+decision is audited under the admin's own id. An admin approval is authoritative,
+finalizing the node even under `unanimous` / `quorum` / `per_group` rather than
+counting as one vote among the (empty) slate.
+
+- `sys_approval_request.viewer` gains `can_override` (server-computed): true for a
+  privileged admin on a pending request. The `approve` / `reject` / `reassign`
+  declared actions OR it into their `visible` gate, so the console surfaces the
+  recovery path without a hand-wired button. Existing approver/submitter gating is
+  unchanged.
+- `openNodeRequest` now logs a loud warning when a node resolves to **no concrete
+  approver**, so the misconfiguration is visible instead of silently locking the
+  record. The literal-fallback behavior (kept for 15.x slot back-compat) is
+  otherwise unchanged.

packages/plugins/plugin-approvals/src/approval-service.test.ts

@@ -418,11 +418,11 @@ describe('ApprovalService (node era)', () => {
   it('getRequest: viewer.can_act is true for a pending approver, false for the submitter', async () => {
     const req = await svc.openNodeRequest(openInput(['u9']), CTX); // submitter u1, approver u9
     const asApprover = await svc.getRequest(req.id, { userId: 'u9', tenantId: 't1' } as any);
-    expect(asApprover!.viewer).toEqual({ can_act: true, is_submitter: false });
+    expect(asApprover!.viewer).toEqual({ can_act: true, is_submitter: false, can_override: false });
     const asSubmitter = await svc.getRequest(req.id, { userId: 'u1', tenantId: 't1' } as any);
-    expect(asSubmitter!.viewer).toEqual({ can_act: false, is_submitter: true });
+    expect(asSubmitter!.viewer).toEqual({ can_act: false, is_submitter: true, can_override: false });
     const asOther = await svc.getRequest(req.id, { userId: 'u_stranger', tenantId: 't1' } as any);
-    expect(asOther!.viewer).toEqual({ can_act: false, is_submitter: false });
+    expect(asOther!.viewer).toEqual({ can_act: false, is_submitter: false, can_override: false });
   });
 
   it('getRequest: viewer.can_act drops to false once the request is finalized', async () => {
@@ -1034,6 +1034,117 @@ describe('ApprovalService (node era)', () => {
   });
 });
 
+// ── Admin / privileged override (#3424) ──────────────────────────────
+//
+// An approval routed to a position/team with NO holders resolves to only the
+// unresolvable `position:<name>` literal — no concrete user is in the slate, so
+// every normal decision is FORBIDDEN and (with lockRecord) the record stays
+// locked forever with no in-product recovery. A platform or tenant admin may
+// act on the pending request to release it: approve, reject, reassign it to a
+// real approver, or recall it. Privilege is org-scoped for tenant admins.
+describe('ApprovalService — admin override (#3424)', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: ApprovalService;
+  let n = 0;
+  const baseTime = new Date('2026-01-15T10:00:00Z').getTime();
+
+  // Admin exec contexts, shaped like the resolved authz envelope (permissions
+  // carry the permission-set names the shared resolver aggregates).
+  const PLATFORM_ADMIN = { userId: 'root', tenantId: 't1', positions: [], permissions: ['admin_full_access'] } as any;
+  const TENANT_ADMIN = { userId: 'owner', tenantId: 't1', positions: [], permissions: ['organization_admin'] } as any;
+  const OTHER_TENANT_ADMIN = { userId: 'owner2', tenantId: 't2', positions: [], permissions: ['organization_admin'] } as any;
+  const MEMBER = { userId: 'nobody', tenantId: 't1', positions: [], permissions: [] } as any;
+
+  // A request routed to an UNSTAFFED position → `pending_approvers` falls back to
+  // the `position:sales_manager` literal, undecidable by any normal user.
+  const stuckInput = (extra: Record<string, any> = {}) => ({
+    object: 'opportunity', recordId: 'opp1', runId: 'run_1', nodeId: 'approve_step',
+    flowName: 'deal_approval',
+    config: { approvers: [{ type: 'position' as const, value: 'sales_manager' }], behavior: 'first_response' as const, lockRecord: true },
+    record: { id: 'opp1', amount: 100 },
+    ...extra,
+  });
+
+  beforeEach(() => {
+    engine = makeFakeEngine();
+    n = 0;
+    svc = new ApprovalService({ engine: engine as any, clock: { now: () => new Date(baseTime + (n++) * 1000) } });
+  });
+
+  it('the stuck request is undecidable by any normal user (repro)', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    expect(req.pending_approvers).toEqual(['position:sales_manager']);
+    // Even the org owner-by-id is not in the resolved (empty) slate.
+    await expect(svc.decideNode(req.id, { decision: 'approve', actorId: 'nobody' }, MEMBER))
+      .rejects.toThrow(/FORBIDDEN/);
+  });
+
+  it('a tenant admin can approve a stuck request, finalizing it (which releases the lock)', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    const out = await svc.decide(req.id, { decision: 'approve', actorId: 'owner' }, TENANT_ADMIN);
+    expect(out.finalized).toBe(true);
+    expect(out.request.status).toBe('approved');
+    // No pending request remains → the record-lock hook no longer blocks edits.
+    const fresh = await svc.getRequest(req.id, SYS);
+    expect(fresh?.status).toBe('approved');
+    expect(fresh?.pending_approvers).toEqual([]);
+    // Audited under the admin's own id — never spoofed as an approver.
+    const acts = await svc.listActions(req.id, SYS);
+    expect(acts.at(-1)).toMatchObject({ action: 'approve', actor_id: 'owner' });
+  });
+
+  it('a platform admin can reject a stuck request', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    const out = await svc.decide(req.id, { decision: 'reject', actorId: 'root' }, PLATFORM_ADMIN);
+    expect(out.finalized).toBe(true);
+    expect(out.request.status).toBe('rejected');
+  });
+
+  it('an admin override finalizes even a unanimous request immediately (not one vote among the slate)', async () => {
+    const req = await svc.openNodeRequest(stuckInput({
+      config: { approvers: [{ type: 'position' as const, value: 'sales_manager' }], behavior: 'unanimous' as const, lockRecord: true },
+    }), CTX);
+    const out = await svc.decide(req.id, { decision: 'approve', actorId: 'owner' }, TENANT_ADMIN);
+    expect(out.finalized).toBe(true);
+    expect(out.request.status).toBe('approved');
+  });
+
+  it('an admin can reassign a stuck request to a real approver, who then decides normally', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    const out = await svc.reassign(req.id, { actorId: 'owner', to: 'u7' }, TENANT_ADMIN);
+    expect(out.request.pending_approvers).toEqual(['u7']);
+    const decided = await svc.decideNode(
+      req.id, { decision: 'approve', actorId: 'u7' },
+      { userId: 'u7', tenantId: 't1', positions: [], permissions: [] } as any,
+    );
+    expect(decided.finalized).toBe(true);
+  });
+
+  it('an admin can recall (withdraw) a stuck request', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    const out = await svc.recall(req.id, { actorId: 'owner', comment: 'unstaffed role' }, TENANT_ADMIN);
+    expect(out.request.status).toBe('recalled');
+    expect(out.request.pending_approvers).toEqual([]);
+  });
+
+  it('a tenant admin of a DIFFERENT org cannot override (privilege is org-scoped)', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX); // organization_id = t1
+    await expect(svc.decideNode(req.id, { decision: 'approve', actorId: 'owner2' }, OTHER_TENANT_ADMIN))
+      .rejects.toThrow(/FORBIDDEN/);
+  });
+
+  it('viewer.can_override reflects the privilege, and drops once finalized', async () => {
+    const req = await svc.openNodeRequest(stuckInput(), CTX);
+    const asAdmin = await svc.getRequest(req.id, TENANT_ADMIN);
+    expect(asAdmin!.viewer).toMatchObject({ can_act: false, can_override: true });
+    const asMember = await svc.getRequest(req.id, MEMBER);
+    expect(asMember!.viewer!.can_override).toBe(false);
+    await svc.decide(req.id, { decision: 'approve', actorId: 'owner' }, TENANT_ADMIN);
+    const after = await svc.getRequest(req.id, TENANT_ADMIN);
+    expect(after!.viewer!.can_override).toBe(false);
+  });
+});
+
 describe('record-lock hook (node era)', () => {
   let engine: ReturnType<typeof makeFakeEngine>;
   let svc: ApprovalService;