docs(auth): spec for per-Agent identity, login & user management (HT-54) - #69

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@specs/auth/agents-and-auth.md`:
- Around line 211-216: Update specs/auth/agents-and-auth.md lines 211-216 to
require an advisory transaction lock or a serializable transaction with retry
around active-admin demotion, disabling, and deletion, while retaining the count
predicate as an additional guard. Update specs/auth/agents-and-auth.md lines
230-234 to apply the same serialization to first-admin bootstrap so concurrent
requests cannot create multiple initial Agents; retain the NOT EXISTS predicate
as an additional guard.
- Around line 42-46: Update the Agent definition in the terminology section to
describe an Agent directly as a human member of the support staff who operates
the inbox, removing the “user” characterization. Preserve the distinction that
Agents are human support staff, Assistants are AI actors, and “Users” is
reserved only for explicitly referenced FreeScout terminology.
- Around line 355-363: Define temporary-password lifecycle state for the
fallback authentication path, including an expiry or forced-change indicator and
the enforcement point during authentication. Require an Agent using a temporary
password to change it before normal authenticated access, and clear the
temporary state after a successful change; update the temp-password flow and
first-login activation behavior accordingly.
- Around line 73-78: Resolve the lifecycle contradiction across the Agent status
and authentication sections: choose one model and apply it consistently. Either
create temporary-password Agents as active with an explicit
required-password-change state, or allow password-authenticated invited Agents
and atomically promote them during `/auth/verify`; update the definitions,
provisioning paths, login behavior, and first-login activation requirements to
match the chosen model.
- Around line 86-96: Enforce the one-password-identity-per-agent invariant in
the schema and core identity service. Add a partial unique index on
agent_auth_identities.agent_id for rows where provider = 'password', and update
the core identity service to reject or prevent creating a second password
identity for the same agent while preserving existing behavior for other
providers.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@specs/auth/agents-and-auth.md`:
- Around line 268-271: Update the agent lifecycle documentation covering PATCH
/agents/{id} and /password to restrict status changes to defined valid
transitions, reserve invited → active with password creation for atomic invite
acceptance, and reject password writes for invited Agents. Ensure the documented
rules prevent arbitrary statuses, disabling an invited Agent, or adding a
password while status remains invited, while preserving the existing
provisioning behavior.
- Around line 268-271: Update the POST /api/v1/agents provisioning contract and
its corresponding section around the additional referenced lines to require a
configured EmailSender before accepting sendInvite=true; reject the request
before Agent insertion when no sender exists, or require the password-based
admin fallback instead. Preserve the existing invited/no-password behavior when
an EmailSender is configured and the active/password behavior for the
alternative path.

---

Outside diff comments:
In `@specs/auth/agents-and-auth.md`:
- Around line 87-103: Add a schema CHECK constraint to agent_auth_identities
enforcing that provider='password' requires a non-NULL secret_hash, while every
non-password provider requires secret_hash to be NULL. Keep the existing
uniqueness constraints and indexes unchanged.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@specs/auth/agents-and-auth.md`:
- Around line 498-502: The draft.3 changelog entry has an incomplete causal
phrase. Update the sentence in the draft.3 bullet to state that the closed
incoherent states were permitted by an unconstrained `status` field, preserving
the existing technical details and meaning.