# ADR-039: Custodian Reactivation Offers Limited (Settlement-Only) and Full Mode

## Status

Accepted, 2026-06-22.

## Status History

```yaml
status_history:
  - date: 2026-06-22
    status: Proposed
    changed_by: hkl
    reason: Formalising two-mode reactivation pattern in Custodian PWA
    changed_via: adr-kit (360lm)
  - date: 2026-06-22
    status: Accepted
    changed_by: hkl
    reason: limited/full reactivation live with _isLimitedMode flag and Settlement badge
    changed_via: adr-kit (360lm)
```

## Context

When a custodian (employee managing petty cash) is deactivated (resigned, suspended), they may still have outstanding pending transfers or unresolved obligations. A simple on/off reactivation would either (a) force full reactivation (giving the ex-custodian unrestricted access to initiate new transactions before clearing obligations), or (b) deny all access (leaving obligations permanently unresolvable without admin intervention for every pending item). A two-mode approach provides a safe middle path.

## Decision

When reactivating a deactivated custodian, the admin chooses:

- **`limited` mode:** custodian can only view their dashboard and resolve pending transfers (accept/reject/settle). They cannot initiate new transfers, view other custodians' data, or access admin functions. The Manage screen shows a "Settlement" badge on their entry. A `_isLimitedMode` flag in their session controls which screens/actions are accessible.

- **`full` mode:** complete access restored, identical to a never-deactivated custodian. All screens and actions available.

The `reactivation_mode` column in `custodian.profiles` stores the current mode. Admin selects mode explicitly at reactivation — there is no default.

This pattern is applicable to any PWA role that has a suspension/reinstatement lifecycle with outstanding obligations.

**Decision Maker:** hkl

## Alternatives Considered

- **Binary reactivation (full access or none).** Rejected: "full" allows new transactions before obligations cleared — creates new debt on top of unresolved old debt; "none" forces admin to manually resolve every pending item one by one as proxy for the deactivated custodian — operational burden proportional to number of open items.
- **Time-limited access window (e.g. 48h to settle, then auto-deactivate).** Rejected: obligations may take longer than any fixed window; time pressure on a custodian trying to contact payees to close transfers causes rushed/incorrect resolution; admin must manually re-extend if window expires.
- **Admin resolves all pending items on behalf of deactivated custodian.** Rejected: admin lacks the custodian's context about specific pending transfers; custodian is the right person to resolve their own obligations; this also creates audit trail confusion (admin acting as custodian).

## Consequences

**Positive:**
- Deactivated custodian can clear their own obligations without admin acting as proxy.
- No risk of new transactions during settlement phase.
- Clear visual distinction in Manage screen (Settlement badge) so admins know who is in limited mode.
- Reusable pattern: any future PWA with role suspension can implement `limited` vs `full` reactivation using the same column + flag approach.

**Negative / Trade-offs:**
- Admin must choose mode at reactivation — an extra decision step; no safe default (both defaults have risks).
- `_isLimitedMode` session flag must be checked at every restricted action — missing a check creates a bypass.
- Edge case: a custodian in `limited` mode who is also rehired as a full employee would get auto-restored via the cross-schema sync trigger (ADR-040) — admin must re-deactivate if they were only reactivated for settlement.

**Risks and mitigations:**
- Admin forgets to set mode and assigns `full` when `limited` was intended: mitigated by surfacing mode choice as a mandatory radio button with `limited` pre-selected and explanatory text.
- `_isLimitedMode` check missed in a new action: mitigated by centralising the check in a `canPerformAction(action)` helper that reads `_isLimitedMode`.

## Related Decisions

- ADR-040 (cross-schema active-state sync trigger) — trigger that auto-restores custodian active status on employee rehire interacts with this pattern.
- ADR-011 (PIN-based auth) — custodian session carries `_isLimitedMode`; PIN login must set this from DB.

## References

- `memory/dbt_custodian.md` — two-mode reactivation, _isLimitedMode, Settlement badge in Manage screen
- `finance/custodian/index.html` — reactivation_mode column, limited mode screen guards