feat(integrations): expose bounded authorized repository reads

[iscekic]

No new behavior — the product does not use the new repository-listing options yet.

---

Summary

listGitHubRepositories and listGitLabRepositories add opt-in bounded reads and explicit provider status values; organizations also expose bounded listBitbucketRepositories.
ListRepositoriesInput rejects extra fields for bounded: true; omitted or false bounded preserves legacy response shapes and the forceRefresh: false default.
withRepositoryReadDeadline applies 30 seconds through usage ordering; organization reads recheck membership before returning and preserve UNAUTHORIZED and FORBIDDEN errors.

Files

• apps/web/src/routers/cloud-agent-next-router.ts — source, modified; 134 changed lines. Adds bounded personal inputs, optional status outputs, deadlines, and temporary-failure responses.
• apps/web/src/routers/organizations/organization-cloud-agent-next-router.ts — source, modified; 248 changed lines. Shares the bounded input across three providers and checks organization access after usage ordering.
• apps/web/src/routers/cloud-agent-next-router.test.ts — test, modified; 158 changed lines. Updates the personal repository procedure suite.
• apps/web/src/routers/organizations/organization-cloud-agent-next-router.test.ts — test, modified; 258 changed lines. Updates the organization repository procedure suite.

GitHubRepositoriesResult.status distinguishes not_connected, available, suspended, reconnect_required, misconfigured, temporarily_unavailable, and integration_limit_exceeded for callers that use bounded RepositoryReadOptions.
Bounded reads validate every configured installation, reject more than ten integrations, and inspect integrations sequentially even after the 50-repository result limit.
Initialized empty caches stay available; bounded refreshes never write shared caches, and failures discard partial results instead of returning legacy partial-success lists.

Files

• apps/web/src/lib/cloud-agent/github-integration-helpers.ts — source, modified; 101 changed lines. Adds bounded owner reads, retains integration labels and the oldest sync time, and limits cache parsing before mapping.
• apps/web/src/lib/cloud-agent/github-integration-helpers.test.ts — test, modified; 206 changed lines. Updates the GitHub integration helper suite.

GitLabRepositoriesResult.status distinguishes not_connected, available, suspended, reconnect_required, misconfigured, and temporarily_unavailable when callers opt into bounded RepositoryReadOptions.
Bounded reads validate optional gitlab_instance_url metadata, keep token requests scoped to the actor and organization, and map authentication failures to reconnect_required.
Bounded reads cap results at 50 repositories, accept initialized empty caches, and preserve complete shared caches and legacy callers.

Files

• apps/web/src/lib/cloud-agent/gitlab-integration-helpers.ts — source, modified; 104 changed lines. Adds bounded organization and personal reads, normalizes instance addresses, and forwards cancellation through project fetching.
• apps/web/src/lib/cloud-agent/gitlab-integration-helpers.test.ts — test, modified; 261 changed lines. Updates the GitLab integration helper suite.

fetchBitbucketRepositoriesForOrganization accepts RepositoryReadOptions for both credential types; the existing BitbucketOrganizationRepositoryListResult contract still reports absent integrations as not_connected.
Bounded reads refresh uninitialized workspace-token caches, classify missing integration types as reconnect_required, and map disappearing integrations or request failures to temporarily_unavailable.
Both credential types share cancellation and deadlines; without bounded, workspace-token reads retain the cache-only default and existing force-refresh behavior.

Files

• apps/web/src/lib/cloud-agent/bitbucket-integration-helpers.ts — source, modified; 75 changed lines. Distinguishes an absent integration from an empty integration type and forwards bounded options through both credential flows.

ListBitbucketRepositoriesInput, ReadCachedRepositoriesInput, and RefreshRepositoriesForMemberInput add readOptions to limit cache parsing and provider results to 50 repositories.
Bounded reads propagate aborts, return reconnect_required for suspended or invalidated credentials, and convert transport failures to temporarily_unavailable.
Bounded refreshes preserve full caches and recheck credential generations, workspace identities, and cache versions before returning; legacy refreshes retain full-cache writes.

Files

• apps/web/src/lib/integrations/platforms/bitbucket/repository-cache.ts — source, modified; 108 changed lines. Adds bounded OAuth reads, checks current state after provider success or failure, and retries against current state after concurrent changes.
• apps/web/src/lib/integrations/platforms/bitbucket/workspace-access-token-repository-cache.ts — source, modified; 75 changed lines. Bounds member refreshes and cache parsing; retains the locked credential-generation check, workspace validation, and current-cache fallback.
• apps/web/src/lib/integrations/platforms/bitbucket/repository-cache.test.ts — test, modified; 175 changed lines. Updates the Bitbucket OAuth cache suite.
• apps/web/src/lib/integrations/platforms/bitbucket/workspace-access-token-repository-cache.test.ts — test, modified; 180 changed lines. Updates the Bitbucket workspace access-token cache suite.

GitLabInstanceUrlError.reason distinguishes resolution_failed from invalid_url, so bounded GitLab reads report lookup failures as temporarily_unavailable, not misconfigured.
resolution_failed covers failed lookups and empty answers; malformed URLs and unsafe addresses keep invalid_url and remain blocked.
Existing callers retain the same error class and messages; one-argument constructors default to invalid_url.

Files

• apps/web/src/lib/integrations/platforms/gitlab/instance-url.ts — source, modified; 15 changed lines. Adds the error reason and marks lookup failures without changing address safeguards.
• apps/web/src/lib/integrations/platforms/gitlab/instance-url.test.ts — test, modified; 56 changed lines. Updates the GitLab instance URL suite.

Tests: 7 files modified — github-integration-helpers.test.ts, gitlab-integration-helpers.test.ts, repository-cache.test.ts, workspace-access-token-repository-cache.test.ts, instance-url.test.ts, cloud-agent-next-router.test.ts, and organization-cloud-agent-next-router.test.ts.
Generated: 0 files changed.

---

Verification

The handoff contains no manual or live-provider verification.
Runtime verification remains pending at the stack tip because this level does not activate harness consumers.

Visual Changes

Visual Changes: N/A

Reviewer Notes

• Scope: level 18 only, between shared-agent-harness-3bb0-s17 and shared-agent-harness-3bb0-s18; this change adds authorized procedures, not harness consumers.
• Repository: Kilo-Org/cloud; worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• The supplied evidence records six passing scoped commands, including 289 tests across five suites.
• Both PostgreSQL suites were discovered but not executed locally; the evidence does not establish live-provider behavior.

Human steps

• No human steps are required before merge or after merge. This change needs no new environment value, secret, migration, or manual activation.

Notes

Runtime verification remains pending at the stack tip. PostgreSQL execution remains pending in CI. This level adds opt-in procedures without activating harness consumers.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714 ← this PR
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (15 files)

• apps/web/src/lib/cloud-agent/bitbucket-integration-helpers.ts
• apps/web/src/lib/cloud-agent/github-integration-helpers.test.ts
• apps/web/src/lib/cloud-agent/github-integration-helpers.ts
• apps/web/src/lib/cloud-agent/gitlab-integration-helpers.test.ts
• apps/web/src/lib/cloud-agent/gitlab-integration-helpers.ts
• apps/web/src/lib/integrations/platforms/bitbucket/repository-cache.test.ts
• apps/web/src/lib/integrations/platforms/bitbucket/repository-cache.ts
• apps/web/src/lib/integrations/platforms/bitbucket/workspace-access-token-repository-cache.test.ts
• apps/web/src/lib/integrations/platforms/bitbucket/workspace-access-token-repository-cache.ts
• apps/web/src/lib/integrations/platforms/gitlab/instance-url.test.ts
• apps/web/src/lib/integrations/platforms/gitlab/instance-url.ts
• apps/web/src/routers/cloud-agent-next-router.test.ts
• apps/web/src/routers/cloud-agent-next-router.ts
• apps/web/src/routers/organizations/organization-cloud-agent-next-router.test.ts
• apps/web/src/routers/organizations/organization-cloud-agent-next-router.ts

---

_{Reviewed by grok-4.6 · Input: 230.6K · Output: 20K · Cached: 856.8K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s17}