fix: make download preflight invalid-token failures actionable

[ViperCai]

Summary

Keep the existing export-permission preflight for both document media and Drive file downloads. When the preflight returns 1063001 Invalid parameter, classify the input as non-retryable and tell agents how to recover from a stale or wrong token instead of repeatedly retrying it.

Changes

• Preserve docs +media-download preflight with type=file, action=export; a real current document image token was verified to pass this check and download successfully.
• Preserve drive +download preflight for uploaded Drive files.
• Mark preflight code 1063001 as non-retryable and add command-specific token recovery guidance without exposing caller tokens.
• Add contract tests and update the embedded Docs/Drive troubleshooting guidance.

Test Plan

• make unit-test
• go vet ./...
• gofmt -l . produces no output
• go mod tidy produces no module changes
• golangci-lint v2.1.6 reports 0 issues
• Source-built Docs and Drive dry-run E2E tests pass
• Real user-identity verification: existing document image token passed export-permission auth (auth_result=true) and docs +media-download saved 497,808 bytes

Related Issues

• None

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e73565cc-e221-44e8-a684-2cb18d069620

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.45%. Comparing base (82e628b) to head (3a77340).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/drive/drive_errors.go	83.33%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2287   +/-   ##
=======================================
  Coverage   76.45%   76.45%           
=======================================
  Files        1013     1013           
  Lines      112034   112045   +11     
=======================================
+ Hits        85658    85668   +10     
- Misses      19864    19865    +1     
  Partials     6512     6512           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.