{
  "schemaVersion": 2,
  "date": "2026.07.26",
  "publishedAt": "2026-07-26T14:53:53-07:00",
  "timeZone": "America/Los_Angeles",
  "title": "Diagnosing Hiro's Gmail authorization failure",
  "publicationStatus": "Published",
  "executiveSummary": [
    "The personal task dashboard's Gmail import returned a RefreshError during its first live authorization attempt.",
    "The local OAuth configuration was inspected without exposing credentials. The credential and token files both exist, the saved authorization has the required read-only Gmail and Calendar scopes, a refresh token is present, and the OAuth client identities match.",
    "A direct refresh request to Google's token service returned invalid_grant. This identifies the stored Google authorization as revoked or otherwise no longer renewable rather than a task-import, Gmail-label, or requested-scope defect.",
    "No token was deleted or replaced. A fresh interactive Google authorization is the required recovery step."
  ],
  "workstreams": [
    {
      "title": "Credential configuration inspection",
      "status": "Completed",
      "details": [
        "Confirmed that Hiro resolves both the Google OAuth client file and the saved authorization token at their configured local paths.",
        "Confirmed that the saved token contains a refresh credential and the required Gmail read-only and Calendar read-only scopes.",
        "Confirmed that the saved token belongs to the same OAuth client described by the configured client file.",
        "Inspected only non-secret metadata and did not print, publish, copy, delete, or replace any credential value."
      ]
    },
    {
      "title": "OAuth refresh diagnosis",
      "status": "Completed",
      "details": [
        "Confirmed that the saved access token is expired and therefore requires refresh before the Gmail API can be called.",
        "Sent a direct refresh request using the configured local authorization and captured Google's structured failure response.",
        "Google returned invalid_grant with a generic Bad Request description. That response means the refresh credential is no longer accepted and cannot be repaired by retrying the import."
      ]
    }
  ],
  "decisions": [
    "Do not alter Gmail scopes because the saved authorization already includes the required read-only scopes.",
    "Do not retry imports repeatedly when Google reports invalid_grant.",
    "Do not delete or overwrite the saved token until a fresh interactive authorization is intentionally initiated.",
    "Keep the integration read-only; fresh consent should request only Gmail read-only and Calendar read-only access."
  ],
  "validation": [
    {
      "check": "OAuth file presence",
      "status": "passed",
      "result": "Both configured local OAuth files exist."
    },
    {
      "check": "Saved authorization metadata",
      "status": "passed",
      "result": "The token contains a refresh credential, both required read-only scopes, and a client identity matching the configured OAuth client."
    },
    {
      "check": "Google token refresh response",
      "status": "failed",
      "result": "Google rejected the refresh request with invalid_grant: Bad Request. This is the confirmed cause of the Gmail import failure."
    }
  ],
  "currentState": [
    "Hiro's task and reading dashboard remains operational.",
    "Gmail imports cannot run until the local Google account is authorized again.",
    "The existing saved token remains in place and was not modified by this diagnosis.",
    "The required recovery is an interactive Google sign-in and consent flow using the existing OAuth client."
  ],
  "limitations": [
    "Google's generic invalid_grant response does not distinguish among revocation, account security changes, refresh-token expiration, or OAuth testing-mode expiration.",
    "No Gmail messages were read or imported during this diagnosis.",
    "Fresh authorization requires an interactive browser sign-in by the account owner."
  ],
  "nextSteps": [
    "Initiate a fresh local Google OAuth flow and complete the account-owner sign-in and read-only consent.",
    "Preserve the rejected token as a recoverable backup until the replacement authorization succeeds.",
    "Retry a small labeled Gmail import and confirm that review-first ingestion and duplicate prevention operate correctly.",
    "Improve the dashboard error message later so invalid_grant is presented as a clear reauthorization requirement rather than a generic RefreshError."
  ],
  "disclosureNote": "This public entry omits credential paths, client identifiers, token values, account information, email data, and private network details."
}