haru-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{haru_cli-0.1.4 → haru_cli-0.1.6}/CHANGELOG.md

@@ -9,6 +9,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `haru doctor`: diagnoses configuration, SSO token, identity provenance,
+  role credentials, caller identity, region divergence, Bedrock reachability,
+  inference-profile availability, and guardrail sanity, with per-check
+  remediation and `--json` output. `--invoke` makes one real (billable)
+  Bedrock call for a definitive answer.
+- `haru doctor --all-roles`: probes every account and role you are assigned
+  and prints a matrix of which combinations can actually reach Bedrock -
+  answering "which IAM role do I need?" empirically.
+- Global `--debug` flag and real logging: `logging.yaml` (level/format/file)
+  is now honoured instead of being dead config. AWS SDK logging rises to INFO
+  under `--debug` (operations and error codes, never bodies or headers), and a
+  redaction filter masks credential-shaped values.
+- `docs/troubleshooting.md`: the IAM policy to hand an AWS administrator,
+  including the easily-missed foundation-model ARNs that cross-region
+  inference profiles require, and why a Kiro/Amazon Q role will not work.
+
+### Fixed
+
+- Bedrock failures no longer surface as raw botocore tracebacks. AccessDenied,
+  ResourceNotFound, Validation, Throttling, and expired-credential errors are
+  translated into actionable messages naming the model, region, role, and the
+  exact IAM action required. A denial mid-chat now returns to the prompt
+  instead of ending the session.
+
+### Fixed
+
+- Stale configuration pins no longer produce a broken sign-in: `haru login`
+  validates a pinned `role_name`/`account_id` against your actual Identity
+  Center assignments, warns, and falls back to the chooser when they do not
+  match (previously a leftover `role_name` from an older `config init` was
+  persisted unchecked and every later command failed).
+- Role rejections are reported honestly: `AWS rejected role 'X' in account
+  'Y' … the role may not be assigned to you` instead of the misleading
+  "SSO credentials rejected; run 'haru login'", which is now reserved for
+  genuinely invalid tokens.
+
+### Changed
+
+- CLI startup is roughly 6x faster (~0.6s to ~0.1s for `haru --version`):
+  strands, mcp, boto3, botocore, and opentelemetry are imported lazily at
+  their call sites, so `--help`, `--version`, `config`, `agents`, and
+  `session list` never load the agent/AWS stack. A guard test fails the
+  build if an eager import creeps back in.
+- `haru login` and `haru config show` report where the account and role
+  came from (login selection, pinned in config, or an environment variable).
+
+### Added
+
 - The login callback now serves a proper local result page (dark themed,
   approval/denial card): "Request approved" on success, "Request denied"
   with the reason on error, missing parameters, or a state mismatch —

{haru_cli-0.1.4 → haru_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haru-cli
-Version: 0.1.4
+Version: 0.1.6
 Summary: Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK.
 Author: haru-cli maintainers
 License-Expression: Apache-2.0
@@ -56,6 +56,8 @@ uv sync
 
 | Command                          | Purpose                                                       |
 | -------------------------------- | ------------------------------------------------------------- |
+| `haru doctor`                    | Diagnose config, sign-in, and Bedrock permissions              |
+| `haru doctor --all-roles`        | Find which account+role can actually reach Bedrock            |
 | `haru config init`               | Create a starter configuration (interactive)                  |
 | `haru config show`               | Show the resolved configuration (no secrets)                  |
 | `haru login`                     | Browser sign-in to IAM Identity Center (OAuth 2.0 + PKCE)     |
@@ -68,7 +70,9 @@ uv sync
 | `haru --version`                 | Print the installed version                                   |
 
 Configuration is resolved from `--config`, then `$HARU_CONFIG`, then
-`./config/haru.yaml`, then `~/.config/haru/haru.yaml`.
+`./config/haru.yaml`, then `~/.config/haru/haru.yaml`. `haru --debug <command>`
+turns on verbose logging, including the AWS API operations and error codes
+behind a failure (never request bodies or credentials).
 
 Inside `haru chat`, slash commands switch targets mid-session:
 
@@ -93,7 +97,15 @@ haru chat --agent supervisor --session-id demo
 AWS accounts and permission-set roles are discovered automatically (like
 `aws configure sso`), auto-selected when there is exactly one, prompted
 otherwise, and remembered for later sessions. Pin `auth.sso.account_id` /
-`role_name` in configuration only if you want to skip the discovery.
+`role_name` in configuration only if you want to skip the discovery — pins
+are validated against your actual assignments, and a stale pin falls back to
+the chooser with a warning rather than failing later.
+
+The consent screen you see in the browser ("Allow haru-cli to access your
+data?") is rendered by AWS IAM Identity Center, and its wording reflects the
+scopes the client requests. haru requests only `sso:account:access`, so AWS
+describes exactly that: the ability to assume roles you have been assigned.
+Once you approve, haru serves a local result page confirming the outcome.
 
 Authentication uses the same PKCE authorization-code flow as `aws sso login`,
 caching tokens in the botocore-compatible schema under `~/.aws/sso/cache`
@@ -139,6 +151,27 @@ Declarative YAML under `config/` — models, agents, orchestration
 logging, and OpenTelemetry. No secrets in YAML: values reference environment
 variables with `${env:VAR}`. See [docs/configuration.md](docs/configuration.md).
 
+## Troubleshooting
+
+If `haru login` succeeds but `haru chat` fails, the role you signed in with
+almost certainly lacks Bedrock permissions. Signing in and being allowed to
+call Bedrock are separate things: haru assumes a role in **your** AWS account
+and calls Bedrock there, so that role needs `bedrock:InvokeModel` and
+`bedrock:InvokeModelWithResponseStream`.
+
+Kiro and Amazon Q working is not evidence that haru will — they send your SSO
+token to the managed Amazon Q service and never call Bedrock in your account,
+so there is no Kiro role to copy.
+
+```bash
+haru doctor              # what is configured, signed in, and permitted
+haru doctor --all-roles  # which of your assigned roles can reach Bedrock
+haru doctor --invoke     # definitive check (makes one billable call)
+```
+
+See [docs/troubleshooting.md](docs/troubleshooting.md) for the IAM policy to
+hand your AWS administrator.
+
 ## Development
 
 All quality gates must pass before a change is considered done:

{haru_cli-0.1.4 → haru_cli-0.1.6}/README.md

@@ -28,6 +28,8 @@ uv sync
 
 | Command                          | Purpose                                                       |
 | -------------------------------- | ------------------------------------------------------------- |
+| `haru doctor`                    | Diagnose config, sign-in, and Bedrock permissions              |
+| `haru doctor --all-roles`        | Find which account+role can actually reach Bedrock            |
 | `haru config init`               | Create a starter configuration (interactive)                  |
 | `haru config show`               | Show the resolved configuration (no secrets)                  |
 | `haru login`                     | Browser sign-in to IAM Identity Center (OAuth 2.0 + PKCE)     |
@@ -40,7 +42,9 @@ uv sync
 | `haru --version`                 | Print the installed version                                   |
 
 Configuration is resolved from `--config`, then `$HARU_CONFIG`, then
-`./config/haru.yaml`, then `~/.config/haru/haru.yaml`.
+`./config/haru.yaml`, then `~/.config/haru/haru.yaml`. `haru --debug <command>`
+turns on verbose logging, including the AWS API operations and error codes
+behind a failure (never request bodies or credentials).
 
 Inside `haru chat`, slash commands switch targets mid-session:
 
@@ -65,7 +69,15 @@ haru chat --agent supervisor --session-id demo
 AWS accounts and permission-set roles are discovered automatically (like
 `aws configure sso`), auto-selected when there is exactly one, prompted
 otherwise, and remembered for later sessions. Pin `auth.sso.account_id` /
-`role_name` in configuration only if you want to skip the discovery.
+`role_name` in configuration only if you want to skip the discovery — pins
+are validated against your actual assignments, and a stale pin falls back to
+the chooser with a warning rather than failing later.
+
+The consent screen you see in the browser ("Allow haru-cli to access your
+data?") is rendered by AWS IAM Identity Center, and its wording reflects the
+scopes the client requests. haru requests only `sso:account:access`, so AWS
+describes exactly that: the ability to assume roles you have been assigned.
+Once you approve, haru serves a local result page confirming the outcome.
 
 Authentication uses the same PKCE authorization-code flow as `aws sso login`,
 caching tokens in the botocore-compatible schema under `~/.aws/sso/cache`
@@ -111,6 +123,27 @@ Declarative YAML under `config/` — models, agents, orchestration
 logging, and OpenTelemetry. No secrets in YAML: values reference environment
 variables with `${env:VAR}`. See [docs/configuration.md](docs/configuration.md).
 
+## Troubleshooting
+
+If `haru login` succeeds but `haru chat` fails, the role you signed in with
+almost certainly lacks Bedrock permissions. Signing in and being allowed to
+call Bedrock are separate things: haru assumes a role in **your** AWS account
+and calls Bedrock there, so that role needs `bedrock:InvokeModel` and
+`bedrock:InvokeModelWithResponseStream`.
+
+Kiro and Amazon Q working is not evidence that haru will — they send your SSO
+token to the managed Amazon Q service and never call Bedrock in your account,
+so there is no Kiro role to copy.
+
+```bash
+haru doctor              # what is configured, signed in, and permitted
+haru doctor --all-roles  # which of your assigned roles can reach Bedrock
+haru doctor --invoke     # definitive check (makes one billable call)
+```
+
+See [docs/troubleshooting.md](docs/troubleshooting.md) for the IAM policy to
+hand your AWS administrator.
+
 ## Development
 
 All quality gates must pass before a change is considered done:

{haru_cli-0.1.4 → haru_cli-0.1.6}/docs/configuration.md

@@ -50,6 +50,15 @@ configuration; `top_k` and `seed` travel via
 non-default sampling values (HTTP 400), and no Claude model honours `seed` —
 use these fields with models that accept them (for example Haiku 4.5).
 
+## Logging
+
+`logging.yaml` is honoured: `level` (DEBUG/INFO/WARNING/ERROR), `format`
+(`json` or `text`), and `file` (a path also writes a 0600 log file). The
+global `--debug` flag overrides the level and additionally raises AWS SDK
+logging to INFO - operation names, endpoints, retries, and error codes, never
+request bodies or headers. A redaction filter masks credential-shaped values
+in all log output.
+
 ## Sessions
 
 Conversation persistence is configured in the base file:

haru_cli-0.1.6/docs/troubleshooting.md

@@ -0,0 +1,136 @@
+# Troubleshooting
+
+Start with `haru doctor`. It checks configuration, sign-in, and Bedrock
+permissions, and prints what to fix.
+
+```bash
+haru doctor                # configuration, token, identity, Bedrock reachability
+haru doctor --invoke       # definitive: makes one real (billable) Bedrock call
+haru doctor --all-roles    # probe every account and role you are assigned
+haru doctor --json         # machine-readable, for a support ticket
+```
+
+## "`haru login` works but `haru chat` fails"
+
+This is the common case, and it is usually not a bug. **Signing in and being
+allowed to call Bedrock are two different permissions.**
+
+haru's path is: browser SSO → `sso:GetRoleCredentials` → an assumed role in
+**your own AWS account** → `bedrock-runtime` Converse. Signing in proves only
+that IAM Identity Center assigned you a role; calling Bedrock additionally
+requires that role to hold `bedrock:InvokeModel` and
+`bedrock:InvokeModelWithResponseStream`, and that Bedrock model access is
+enabled for the Claude models in that account and region.
+
+### Kiro or Amazon Q working tells you nothing about haru
+
+Kiro CLI and Amazon Q authenticate through the same Identity Center, then send
+the SSO token as a bearer credential to the **managed Amazon Q service**. They
+never call Bedrock in your account, so they need no `bedrock:*` IAM
+permissions at all — [Kiro's IAM documentation](https://kiro.dev/docs/cli/enterprise/iam/)
+lists `sso:*`, `user-subscriptions:*`, and `q:*` actions and no
+`bedrock:InvokeModel`.
+
+Consequently an Amazon Q permission set (names like `AmazonQUsers`) is
+**expected to fail** with haru, and there is no Kiro role to copy. Run
+`haru doctor --all-roles` to find which of your assigned roles can actually
+reach Bedrock:
+
+```
+ACCOUNT       NAME                ROLE                 CREDS   BEDROCK   INVOKE
+881490127383  amazonq-prod        AmazonQUsers         ok      denied    denied
+111122223333  ml-sandbox          BedrockDeveloper     ok      ok        ok
+```
+
+Then re-run `haru login` and choose the working combination, or pin it with
+`auth.sso.account_id` and `auth.sso.role_name`.
+
+## Policy to give your AWS administrator
+
+Attach to the permission set you sign in with. **Both invoke statements are
+required.** haru defaults to `us.` cross-region inference profiles, so Bedrock
+authorizes against the underlying foundation-model ARN in *every region the
+profile routes to* — a policy granting only the inference-profile ARN produces
+an `AccessDeniedException` naming a foundation-model ARN you never configured.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "InvokeViaInferenceProfile",
+      "Effect": "Allow",
+      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
+      "Resource": "arn:aws:bedrock:us-east-1:ACCOUNT_ID:inference-profile/us.anthropic.claude-*"
+    },
+    {
+      "Sid": "InvokeUnderlyingFoundationModelsInEveryRoutedRegion",
+      "Effect": "Allow",
+      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"],
+      "Resource": [
+        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-*",
+        "arn:aws:bedrock:us-east-2::foundation-model/anthropic.claude-*",
+        "arn:aws:bedrock:us-west-2::foundation-model/anthropic.claude-*"
+      ]
+    },
+    {
+      "Sid": "GuardrailsWhenConfigured",
+      "Effect": "Allow",
+      "Action": "bedrock:ApplyGuardrail",
+      "Resource": "arn:aws:bedrock:us-east-1:ACCOUNT_ID:guardrail/*"
+    },
+    {
+      "Sid": "Diagnostics",
+      "Effect": "Allow",
+      "Action": ["bedrock:ListFoundationModels", "bedrock:GetInferenceProfile"],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+There is **no `bedrock:Converse` IAM action** — Converse is authorized by
+`bedrock:InvokeModel` and ConverseStream by
+`bedrock:InvokeModelWithResponseStream`. A policy naming `bedrock:Converse`
+grants nothing.
+
+`sts:GetCallerIdentity` and the `sso:*` calls need no policy; they are
+authorized by the service itself. That is why `haru doctor` can show a valid
+assumed-role ARN while Bedrock is still denied.
+
+## Model access is separate from IAM
+
+Even with the policy above, Bedrock refuses models that are not enabled for
+the account. In the AWS console: **Bedrock → Model access → Manage model
+access**, enable the Anthropic models, and confirm the region matches
+`auth.bedrock_region` (or the model entry's `region`, which wins).
+
+## Debug logging
+
+```bash
+haru --debug chat
+```
+
+Raises haru's own logging to DEBUG and AWS SDK logging to INFO, showing the
+API operations, endpoints, retries, and error codes behind a failure. Request
+and response bodies and headers are never logged, and a redaction filter masks
+credential-shaped values as defence in depth.
+
+Set persistent logging in `logging.yaml`:
+
+```yaml
+logging:
+  level: INFO      # DEBUG, INFO, WARNING, ERROR
+  format: json     # json or text
+  file: null       # a path here writes a 0600 log file as well as stderr
+```
+
+## Other failures
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `No configuration found` | Run `haru config init`, or pass `--config`, or set `$HARU_CONFIG`. |
+| `No cached SSO token` | Run `haru login`. |
+| `AWS rejected role 'X' in account 'Y'` | The role is not assigned to you, or a stale pin is in your config. Run `haru doctor --all-roles`. |
+| `Guardrails are enabled but no guardrail_id` | Set `guardrails.guardrail_id`, or `enabled: false`. Guardrails fail closed by design. |
+| Bedrock rejects sampling parameters | Claude 5-series and Opus 4.7+ reject non-default `temperature`/`top_p`/`top_k`. Leave them unset for those models. |

{haru_cli-0.1.4 → haru_cli-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "haru-cli"
-version = "0.1.4"
+version = "0.1.6"
 description = "Secure, scriptable CLI for Amazon Bedrock Claude models via the AWS Strands Agents SDK."
 readme = "README.md"
 license = "Apache-2.0"
@@ -61,8 +61,21 @@ select = ["E", "F", "I", "N", "UP", "B", "SIM", "PL", "RUF", "S"]
 
 [tool.ruff.lint.per-file-ignores]
 # S101: pytest uses bare asserts. S105/S106/S107: tests exercise secret
-# handling with deliberately fake credential strings.
-"tests/**" = ["S101", "PLR2004", "S105", "S106", "S107"]
+# handling with deliberately fake credential strings. S603: the import-time
+# guard runs the interpreter in a subprocess with a fixed argv.
+"tests/**" = ["S101", "PLR2004", "S105", "S106", "S107", "S603"]
+# PLC0415: heavy third-party imports (strands, mcp, boto3, opentelemetry)
+# are deliberately deferred to call sites so `haru --help` stays fast; the
+# guard test tests/unit/test_import_time.py enforces this.
+"src/haru/agents/factory.py" = ["PLC0415"]
+"src/haru/auth/*" = ["PLC0415"]
+"src/haru/commands/doctor.py" = ["PLC0415"]
+"src/haru/commands/streaming.py" = ["PLC0415"]
+"src/haru/diagnostics/*" = ["PLC0415"]
+"src/haru/models/bedrock.py" = ["PLC0415"]
+"src/haru/observability/telemetry.py" = ["PLC0415"]
+"src/haru/sessions/manager.py" = ["PLC0415"]
+"src/haru/tools/mcp.py" = ["PLC0415"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["haru"]

haru_cli-0.1.6/src/haru/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent factories and multi-agent orchestration."""

{haru_cli-0.1.4 → haru_cli-0.1.6}/src/haru/agents/factory.py

@@ -5,15 +5,9 @@ tools, and MCP tools. Multi-agent orchestration composes these in
 ``haru.agents.orchestration``.
 """
 
-from collections.abc import Mapping
-from pathlib import Path
-from typing import Any
+from __future__ import annotations
 
-import boto3
-from strands import Agent
-from strands.models import BedrockModel
-from strands.session.session_manager import SessionManager
-from strands.tools.mcp import MCPClient
+from typing import TYPE_CHECKING, Any
 
 from haru.config.schema import HaruConfig, SamplingConfig
 from haru.errors import ConfigError
@@ -21,6 +15,16 @@ from haru.models.bedrock import build_model, get_model_config, merge_sampling
 from haru.steering.prompts import DEFAULT_PROMPTS_ROOT, load_prompts, resolve_prompt
 from haru.tools.mcp import collect_tools
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    import boto3
+    from strands import Agent
+    from strands.models import BedrockModel
+    from strands.session.session_manager import SessionManager
+    from strands.tools.mcp import MCPClient
+
 
 def build_agent(  # noqa: PLR0913 - keyword-only wiring points, all optional
     config: HaruConfig,
@@ -41,6 +45,8 @@ def build_agent(  # noqa: PLR0913 - keyword-only wiring points, all optional
     model entry). Raises ConfigError for unknown agents, prompt references,
     tools, or an invalid override.
     """
+    from strands import Agent
+
     if agent_name is None:
         model_cfg = get_model_config(config, model_name)
         model = build_model(model_cfg, session, guardrails=config.guardrails, sampling=sampling)

{haru_cli-0.1.4 → haru_cli-0.1.6}/src/haru/auth/identity.py

@@ -4,8 +4,14 @@ Kiro-style browser sign-in needs no upfront AWS knowledge: after the token
 exchange, the accessible accounts and permission-set roles are listed from
 IAM Identity Center (as ``aws configure sso`` does), auto-selected when there
 is exactly one, and persisted next to the token cache for later sessions.
+
+Configuration pins (``account_id``/``role_name``) are validated against the
+user's actual assignments; a stale pin produces a warning and falls back to
+the chooser instead of persisting a broken identity.
 """
 
+from __future__ import annotations
+
 import json
 import os
 from collections.abc import Callable
@@ -13,9 +19,6 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-import boto3
-from botocore.exceptions import ClientError
-
 from haru.auth.cache import cache_path
 from haru.auth.sso import SsoToken
 from haru.config.schema import SsoConfig
@@ -24,6 +27,12 @@ from haru.errors import AuthError
 Chooser = Callable[[str, list[str]], int]
 """Callback picking one option: (question, labels) -> chosen index."""
 
+Notify = Callable[[str], None]
+"""Callback for user-facing warnings during selection."""
+
+SOURCE_SELECTED = "login selection"
+SOURCE_CONFIG = "pinned in config"
+
 
 @dataclass(frozen=True)
 class SelectedIdentity:
@@ -32,6 +41,8 @@ class SelectedIdentity:
     account_id: str
     role_name: str
     account_name: str | None = None
+    account_source: str = SOURCE_SELECTED
+    role_source: str = SOURCE_SELECTED
 
 
 def identity_path(start_url: str, cache_dir: Path | None = None) -> Path:
@@ -72,57 +83,121 @@ def read_identity(start_url: str, cache_dir: Path | None = None) -> SelectedIden
         return None
 
 
-def select_identity(
+def effective_identity(
+    sso_cfg: SsoConfig, cache_dir: Path | None = None
+) -> tuple[str | None, str, str | None, str]:
+    """Resolve the effective account and role with their provenance.
+
+    Returns ``(account_id, account_source, role_name, role_source)``;
+    values are None (source ``"unset"``) when nothing provides them.
+    Precedence per field: config pin, then ``account_id_env``, then the
+    identity persisted at login.
+    """
+    stored = read_identity(sso_cfg.start_url, cache_dir)
+
+    if sso_cfg.account_id is not None:
+        account, account_source = sso_cfg.account_id, SOURCE_CONFIG
+    elif sso_cfg.account_id_env is not None and os.environ.get(sso_cfg.account_id_env):
+        account = os.environ[sso_cfg.account_id_env]
+        account_source = f"from ${sso_cfg.account_id_env}"
+    elif stored is not None:
+        account, account_source = stored.account_id, SOURCE_SELECTED
+    else:
+        account, account_source = None, "unset"
+
+    if sso_cfg.role_name is not None:
+        role, role_source = sso_cfg.role_name, SOURCE_CONFIG
+    elif stored is not None:
+        role, role_source = stored.role_name, SOURCE_SELECTED
+    else:
+        role, role_source = None, "unset"
+
+    return account, account_source, role, role_source
+
+
+def select_identity(  # noqa: PLR0913 - keyword-only wiring points, all optional
     sso_cfg: SsoConfig,
     token: SsoToken,
     *,
     sso_client: Any | None = None,
     cache_dir: Path | None = None,
     chooser: Chooser | None = None,
+    notify: Notify | None = None,
 ) -> SelectedIdentity:
     """Resolve the account and role for this sign-in and persist the choice.
 
-    Configuration pins win (``account_id``/``role_name``, or the account id
-    from ``account_id_env``); anything unpinned is discovered from Identity
-    Center. With multiple choices and no ``chooser``, raises AuthError.
+    Configuration pins are honoured only when they match the user's actual
+    assignments; a stale pin triggers a ``notify`` warning and falls back to
+    discovery. With multiple choices and no ``chooser``, raises AuthError.
     """
     if sso_client is None:
-        sso_client = boto3.Session().client("sso", region_name=sso_cfg.sso_region)
+        import boto3
 
-    account_id = _pinned_account(sso_cfg)
-    account_name: str | None = None
-    if account_id is None:
-        accounts = _list_accounts(sso_client, token.access_token)
+        sso_client = boto3.Session().client("sso", region_name=sso_cfg.sso_region)
+    warn = notify if notify is not None else _ignore_warning
+
+    accounts = list_accounts(sso_client, token.access_token)
+    pinned_account, pin_source = _pinned_account(sso_cfg)
+    account_source = SOURCE_SELECTED
+    chosen = next((account for account in accounts if account["accountId"] == pinned_account), None)
+    if chosen is not None:
+        account_source = pin_source
+    else:
+        if pinned_account is not None:
+            warn(
+                f"Warning: configured account {pinned_account} is not accessible with"
+                " this sign-in; choose from your accessible accounts."
+            )
         chosen = _choose(
             "Choose the AWS account to use",
             accounts,
             lambda account: f"{account['accountId']}  {account.get('accountName', '')}".strip(),
             chooser,
         )
-        account_id = chosen["accountId"]
-        account_name = chosen.get("accountName")
-
-    role_name = sso_cfg.role_name
-    if role_name is None:
-        roles = _list_roles(sso_client, token.access_token, account_id)
+    account_id: str = chosen["accountId"]
+    account_name: str | None = chosen.get("accountName")
+
+    roles = list_roles(sso_client, token.access_token, account_id)
+    role_source = SOURCE_SELECTED
+    if sso_cfg.role_name is not None and sso_cfg.role_name in roles:
+        role_name = sso_cfg.role_name
+        role_source = SOURCE_CONFIG
+    else:
+        if sso_cfg.role_name is not None:
+            warn(
+                f"Warning: configured role {sso_cfg.role_name!r} is not assigned to you"
+                f" in account {account_id}; choose from your assigned roles."
+            )
         role_name = _choose(f"Choose the role for account {account_id}", roles, str, chooser)
 
     identity = SelectedIdentity(
-        account_id=account_id, role_name=role_name, account_name=account_name
+        account_id=account_id,
+        role_name=role_name,
+        account_name=account_name,
+        account_source=account_source,
+        role_source=role_source,
     )
     write_identity(identity, sso_cfg.start_url, cache_dir)
     return identity
 
 
-def _pinned_account(sso_cfg: SsoConfig) -> str | None:
+def _ignore_warning(message: str) -> None:
+    """Default notify callback: drop the warning (non-interactive callers)."""
+
+
+def _pinned_account(sso_cfg: SsoConfig) -> tuple[str | None, str]:
     if sso_cfg.account_id is not None:
-        return sso_cfg.account_id
+        return sso_cfg.account_id, SOURCE_CONFIG
     if sso_cfg.account_id_env is not None:
-        return os.environ.get(sso_cfg.account_id_env)
-    return None
+        value = os.environ.get(sso_cfg.account_id_env)
+        if value:
+            return value, f"from ${sso_cfg.account_id_env}"
+    return None, ""
 
 
-def _list_accounts(sso_client: Any, access_token: str) -> list[dict[str, Any]]:
+def list_accounts(sso_client: Any, access_token: str) -> list[dict[str, Any]]:
+    from botocore.exceptions import ClientError
+
     try:
         paginator = sso_client.get_paginator("list_accounts")
         accounts = [
@@ -137,7 +212,9 @@ def _list_accounts(sso_client: Any, access_token: str) -> list[dict[str, Any]]:
     return sorted(accounts, key=lambda account: str(account["accountId"]))
 
 
-def _list_roles(sso_client: Any, access_token: str, account_id: str) -> list[str]:
+def list_roles(sso_client: Any, access_token: str, account_id: str) -> list[str]:
+    from botocore.exceptions import ClientError
+
     try:
         paginator = sso_client.get_paginator("list_account_roles")
         roles = [