Complete Inventory of Remote HTTP/API Endpoints

Based on my comprehensive analysis of the Entire CLI Go codebase, here's the complete inventory of all remote HTTP/gRPC/API endpoints:

1. CONTROL-PLANE CORE API (via internal/coreapi package)

Base URL Resolution:/Users/soph/Work/entire/devenv/cli_experiments/internal/coreapi/client.go

• Resolved via auth.ResolveControlPlaneTarget() for active context
• Base path: /api/v1 (appended to core host)
• Cross-jurisdiction support via RFC 8693 token exchange

All endpoints: 54 total operations at <core-host>/api/v1

Organization Operations

Repository Operations

Project Operations

Mirror Operations (Git Mirrors)

Service Account Operations

Identity/Access Operations

Audit & System Operations

Batch/Search Operations

2. DATA API (via cmd/entire/cli/api/client.go)

Base URL Resolution:/Users/soph/Work/entire/devenv/cli_experiments/cmd/entire/cli/api/base_url.go

• Default: https://entire.io
• Override: ENTIRE_API_BASE_URL env var
• Defaults to https://entire.io (production)

Repository Management

Trails (Change Intelligence)

Recap/Activity (AI analysis & activity)

General Data API Patterns

• Dynamic paths with forge, owner, repo URL-escaped parameters
• Pagination via query params (limit, offset, page_token)
• Authentication: Bearer token via Authorization header
• Content negotiation: Accept/Content-Type application/json

3. AUTHENTICATION/LOGIN ENDPOINTS (via internal/entireclient/httputil)

Base URL: Control-plane login server (resolved per context)

OAuth Token Exchange

Details:

• POST form: grant_type, subject_token, subject_token_type, requested_token_type, audience, client_id, client_secret
• Response: {access_token, expires_in}
• Client credentials lifted into HTTP Basic auth per RFC 6749 §2.3.1
• Used for cross-jurisdiction token exchange when a resource's home core differs from user's login core

Login Session Management (via cmd/entire/cli/api/auth_sessions.go)

Note: Auth sessions path is set via WithAuthSessionsPath() when targeting auth server

4. CLUSTER/FEDERATION DISCOVERY (via internal/entireclient/clusterdiscovery)

Cluster Well-Known Discovery

Response shape:{core_urls: ["https://core1", "https://core2"]}

API Well-Known Discovery

Response shape:{trusted_issuers: ["https://core1", "https://core2"]}

Federation Peer Trust List

Response shape:{peer_auth_hosts: ["core1.host", "core2.host"]}

5. GIT PROTOCOL ENDPOINTS (via internal/remotehelper/transport)

These are Git smart-HTTP / stateless-RPC endpoints, not Entire-specific:

Host resolution: Dynamic per resource URL; cluster replicas via failover

• Entry point and replica nodes
• Replica discovery via cluster well-known endpoint

6. KEY INFRASTRUCTURE / BASE URL RESOLUTION

Control-Plane Resolution

• File:/Users/soph/Work/entire/devenv/cli_experiments/cmd/entire/cli/auth/ + /Users/soph/Work/entire/devenv/cli_experiments/internal/coreapi/client.go
• Sources:

1. ENTIRE_TOKEN env var (CI/workload-identity) → extract aud claim as core URL
2. Active context from contexts.json → CoreURL field
3. NewForCluster(clusterHost) → discover core from cluster's well-known endpoint

• STS Token Exchange: When token audience differs from target core (cross-jurisdiction), uses /oauth/token to mint region-scoped token

Data API Resolution

• File:/Users/soph/Work/entire/devenv/cli_experiments/cmd/entire/cli/api/base_url.go
• Sources:

1. ENTIRE_API_BASE_URL env var (dev override)
2. Default: https://entire.io (production)

• Trust Root Discovery:/.well-known/entire-api.json → list of trusted issuers

Authentication

• Bearer token injection: All API requests carry Authorization: Bearer <token> header
• Token sources:
  • Login context's stored refresh token (re-minted per request)
  • ENTIRE_TOKEN env var (static, used verbatim)
  • Service account credentials (for mirror collaborator ops)

7. SUMMARY BY CLI PACKAGE/COMMAND

8. NO GRPC/STREAMING BEYOND GIT PROTOCOL

The codebase contains no gRPC or Protobuf definitions (no .proto files, no *_pb.go generated files). All remote communication is HTTP/REST except Git protocol which is stateless RPC over HTTP.

KEY FILES FOR REFERENCE

• Core API Client:/Users/soph/Work/entire/devenv/cli_experiments/internal/coreapi/client.go
• Generated Core Operations:/Users/soph/Work/entire/devenv/cli_experiments/internal/coreapi/oas_client_gen.go (6606 lines)
• Data API Client:/Users/soph/Work/entire/devenv/cli_experiments/cmd/entire/cli/api/client.go
• Auth/Token Exchange:/Users/soph/Work/entire/devenv/cli_experiments/internal/entireclient/httputil/oauth.go
• Cross-Jurisdiction Transport:/Users/soph/Work/entire/devenv/cli_experiments/internal/coreapi/cross_juris_transport.go
• Discovery:/Users/soph/Work/entire/devenv/cli_experiments/internal/entireclient/clusterdiscovery/{discovery.go,api_discovery.go}
• Base URL Config:/Users/soph/Work/entire/devenv/cli_experiments/cmd/entire/cli/api/base_url.go <subagent_tokens>65293</subagent_tokens><tool_uses>40</tool_uses><duration_ms>117642</duration_ms>

Analysis of Entire.io API v1 Endpoints

Based on my investigation of the codebase at /Users/soph/Work/entire/devenv/entire.io/api, here's a detailed breakdown of each endpoint the CLI uses:

1. GET /api/v1/repositories

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/repositories.ts:981-1061
• Description: Lists non-archived repositories accessible via the GitHub App installation, annotated with checkpoint counts.
• Backing Data Source: Local Postgres database (PlanetScale). Queries repos table via db.repos.getForUser(userId), filters locally on app-access + archived status, and sorts by push_date or name.
• Auth: requireAuthOrBearer middleware (session cookie OR Bearer token). Validates via requireBearerAuth (lines 263-317 in middleware.ts) which validates entire-core JWT tokens, or session cookies via requireSessionAuth.

2. GET /api/v1/trails/{forge}/{owner}/{repo} (List trails, with ?limit and ?stream variants)

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/trails.ts:1972-2090
• Description: Lists trails for a repository with pagination support. Accepts limit parameter (1-200, default 50) and optional stream query for SSE streaming.
• Backing Data Source: Local Postgres database. Queries trails table via db.trails.listForRepo(). The endpoint also calls GitHub API via fetchPullRequestsForTrails() to enrich trail state and verify PR membership.
• Auth: requireAuthOrBearer + requireUserFeatureFlag(FLAG_TRAILS) middleware. Auth validated at router level (line 1968-1969 in trails.ts).

3. GET /api/v1/trails/{forge}/{owner}/{repo}/{number} (Get one trail)

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/trails.ts:2684-2839

• Description: Returns detailed trail information including metadata, body document, checkpoints on the branch, and monitor results.

• Backing Data Source: Multi-source:

• Local DB: db.trails.getByNumber() (trail row), db.checkpoints.getForBranchExcludingBase() (checkpoints on trail branch), db.trails.listMonitorResults() (monitor enrichment)

  • GitHub API: Called via linkExistingPR() and resolveAndMaybeSyncActiveTrailBase() using the user's GitHub token to verify PR state
  • Editor Collaboration Service: ensureTrailBodyDocument() calls Durable Objects (c.env.EDITOR_DOCUMENTS) to fetch/create the trail body document

• Auth: requireAuthOrBearer middleware + retrieves user GitHub token for GitHub API calls.

4. DELETE /api/v1/trails/{forge}/{owner}/{repo}/{number}

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/trails.ts:3223-3303

• Description: Deletes a trail and optionally cleans up its associated Git branch.

• Backing Data Source: Multi-source:

• Local DB: Marks trail as status='closed', deletes related threads/comments

  • GitHub API: Closes the associated PR (if exists) via closeTrailPR(), attempts to delete the trail branch via deleteBranch()

• Auth: requireAuthOrBearer middleware; resolves user context and GitHub token for API calls.

5. GET /api/v1/trails/{trail_id}/reviews/comments

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/code-review.ts:1751-1867
• Description: Paginated list of code review comments across all reviews for a trail. Supports filtering by status (open/resolved/dismissed), severity (high/medium/low), and staleness (current/stale). Returns cursor for event streaming.
• Backing Data Source: Local Postgres database. Queries review_comments table via db.codeReview.listReviewComments() with filters. Retrieves event cursor via db.codeReview.getEventCursor().
• Auth: requireAuthOrBearer + requireUserFeatureFlag(FLAG_TRAILS) middleware (lines 50-51 in code-review.ts).

6. GET /api/v1/trails/{trail_id}/reviews/{id} (Get review state)

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/code-review.ts:2035-2111

• Description: Returns a review's full state: review metadata, code version, comment counts, and a cursor-paginated page of comments with inlined suggested changes and link summaries. Includes event cursor for SSE.

• Backing Data Source: Local Postgres database. Queries:

• db.codeReview.getReviewById() (review metadata)

  • db.codeReview.getReviewSnapshot() (cursor-paginated comments with full details)

• Auth: requireAuthOrBearer + requireUserFeatureFlag(FLAG_TRAILS) middleware.

7. GET /api/v1/activity

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/me.ts:175-312

• Description: Pre-aggregated activity rollups for the authenticated user: stats (tasks, orchestration, iteration, throughput, continuity, streaks), daily/hourly contributions grouped by agent, and per-repo breakdown. Requires timezone query parameter (IANA format).

• Backing Data Source: Local Postgres database. Queries checkpoints table via:

• db.checkpoints.getByUser() (checkpoints in window)

  • db.checkpoints.getStreakTimestamps() (lifetime streak calculation)
  • Aggregates locally in TypeScript via computeStats(), computeDaily/HourlyContributions(), computeRepoBreakdown(), computeStreaks().

• Auth: requireBearerAuth middleware at meRoutes level (line 23 in me.ts). Bearer token only (CLI usage).

8. GET /api/v1/me/recap

• File:Line: /Users/soph/Work/entire/devenv/entire.io/api/src/routes/recap.ts:140-408

• Description: Per-agent recap aggregates for the CLI: for every agent used in the window, returns checkpoints, tokens, transcript tokens, files changed, labels, skills, MCP servers, and tool-mix. When ?repo=org/name supplied, also includes contributor-side aggregates (same shape).

• Backing Data Source: Multi-source:

• Local DB: db.checkpoints.getByUser() (my checkpoints) and db.checkpoints.getTeamOnUserRepos() (team checkpoints if ?repo= supplied)

  • Local DB: db.analyses.aggregateFacetsByAgent() (SQL-side aggregation of labels, skills, MCP servers, toolMix) — optimized SQL aggregate, not per-checkpoint JSON parsing
  • Fallback: db.analyses.getByCheckpointIds() + JSON parsing if facet aggregation missing
  • Optional: currentIdentityIfEnabled() calls entire-core to resolve the user's GitHub ID if identity federation is enabled

• Auth: requireBearerAuth middleware. Bearer token only.

Summary Table

Authentication Details

All endpoints use middleware configured at the route-group level:

• requireAuthOrBearer (trails, code-review): Accepts either session cookie (with CSRF for mutations) OR Authorization: Bearer <entire-core-JWT>. Resolves to userId context variable.

  • Session path: Validates session cookie, looks up user in DB
  • Bearer path: Validates entire-core JWT (calls validateCoreJwt() in lib/core-jwt.ts), extracts githubId, looks up user

• requireBearerAuth (me.ts routes): Bearer token only. Validates entire-core JWT, rejects session cookies with 401.

• requireUserFeatureFlag(FLAG_TRAILS): Post-auth gate that checks PostHog feature flags before proceeding (trails feature flag required).

Key Architectural Insights

1. No Rails: This is a Node.js/Hono (modern TypeScript web framework) API, not Rails.
2. Local-First: All endpoints read from a local Postgres database (PlanetScale). No proxying to a separate "core" backend for trail/checkpoint data.
3. GitHub Integration: Trail detail, deletion, and PR linking make direct GitHub API calls using the user's GitHub token or installation token.
4. Code Review as DB-Native: Code review (comments, state, reviews) is stored locally in PlanetScale, not proxied elsewhere.
5. Activity/Recap as Local Aggregation: Activity and recap aggregates are computed server-side from checkpoint rows — no external LLM or AI service involved in these endpoints.
6. Optional External Calls:

• entire-core (identity federation): Optional call to look up GitHub ID if enabled
  • Durable Objects (editor collaboration): Trail body documents stored in Cloudflare Durable Objects, not the main DB

7. Bearer Auth Standard: CLI clients authenticate with entire-core JWTs, validated server-side without contacting entire-core on every request (JWT validation is stateless). <subagent_tokens>79156</subagent_tokens><tool_uses>36</tool_uses><duration_ms>169591</duration_ms>

Summary Report

Based on my investigation of the Go service at /Users/soph/Work/entire/devenv/entire-api, here is a comprehensive map of the HTTP endpoints, authentication mechanism, and domain coverage.

1. HTTP ENDPOINTS (59 routes total)

All routes are served under the /api/v1 base path. Routes are grouped by domain.

Health & Readiness

• GET /healthz — Liveness probe
• GET /readyz — Readiness check (verifies downstream dependencies)

User Activity (/me/* - authenticated user's data)

• GET /me — Experimental: caller identity + jurisdictions where caller has data
• GET /me/activity — Pre-aggregated activity (daily buckets, per-repo, per-agent rollups, streak)
• GET /me/checkpoints — Recent checkpoints + streak dates
• GET /me/commits — Recent commits grouped with their checkpoints
• GET /me/recap — Per-agent recap aggregates; ?repo= adds team column
• GET /me/sessions — Cross-repo session list in a timeframe

Experimental User Activity (/experimental/me/* - residency-safe pointer model)

• GET /experimental/me — Caller identity + jurisdictions
• GET /experimental/me/commits — Commits as residency-safe pointers
• GET /experimental/me/checkpoints — Checkpoints as residency-safe pointers + streak
• GET /experimental/me/activity — Daily buckets + per-repo/per-agent rollups + streak
• GET /experimental/me/recap — Per-agent recap; ?repo= adds team column

Preferences (user-owned product state)

• GET /preferences/session-detail-filters — Session detail filter defaults
• PUT /preferences/session-detail-filters — Save session detail filter defaults
• GET /preferences/diff-view — Diff view settings
• PUT /preferences/diff-view — Save diff view settings
• GET /preferences/filter-tabs — Saved list filter tabs
• PUT /preferences/filter-tabs — Save list filter tabs

Repository Preferences

• GET /preferences/repos — Caller's pinned + recent repositories
• POST /preferences/repos/pinned — Pin a repository
• DELETE /preferences/repos/pinned/{repo_id} — Unpin a repository
• POST /preferences/repos/recent — Record a repository in recent list
• DELETE /preferences/repos/recent/{repo_id} — Remove from recent list

Repository Discovery & Aggregates

• GET /repos — Repos the caller can read (discovery list, with optional ?include=activity)
• GET /repos/{repo_id}/summary — Headline activity rollup (commits, checkpoints, contributors, tokens, lines, active days)
• GET /repos/{repo_id}/activity — Time-bucketed activity (day or week granularity)
• GET /repos/{repo_id}/contributors — Per-contributor leaderboard (sortable by commits/checkpoints/tokens/lines)
• GET /repos/{repo_id}/agents — Per-agent checkpoint rollup
• GET /repos/{repo_id}/branches — Branch list (composed from git refs)
• GET /repos/{repo_id}/checkpoint-status — Lightweight checkpoint status (access + sync flags + count)

Repository Overview Panels (detailed metrics)

• GET /repos/{repo_id}/overview/commit-stats — Commit-vs-checkpoint stats
• GET /repos/{repo_id}/overview/checkpoint-metrics — Per-checkpoint metric averages
• GET /repos/{repo_id}/overview/agent-activity — Per-day, per-agent checkpoint activity
• GET /repos/{repo_id}/overview/session-patterns — Session timing/depth/velocity patterns
• GET /repos/{repo_id}/overview/contributors — Per-contributor commit leaderboard
• GET /repos/{repo_id}/overview/contributor-tokens — Per-contributor token totals
• GET /repos/{repo_id}/overview/contributor-agents — Per-contributor commit totals + agent breakdown

Commits (read-through to Repo API)

• GET /repos/{repo_id}/commits — Paginated commit list with checkpoint previews (public repo support via X-Anon-Repo header)
• GET /repos/{repo_id}/commits/{sha} — Single commit detail + diffstats + checkpoint preview
• GET /repos/{repo_id}/compare — Branch compare: commit delta + ahead/behind + checkpoint rollup

Checkpoints (checkpoint-anchored data)

• GET /repos/{repo_id}/checkpoints — Fully composed checkpoints (commit + diffstat + fileStats + sessions)
• GET /repos/{repo_id}/checkpoints/{checkpoint_id} — One checkpoint: composed + branch membership + redirect decision
• GET /repos/{repo_id}/checkpoints/{checkpoint_id}/analysis — Checkpoint LLM analysis (labels + narratives)
• GET /repos/{repo_id}/commits/{sha}/checkpoints — All checkpoints linked to a commit (fully composed)
• GET /repos/{repo_id}/checkpoint-status — Lightweight checkpoint sync status

Sessions

• GET /repos/{repo_id}/sessions — Paginated materialised sessions (rollup of checkpoints)
• GET /repos/{repo_id}/sessions/{session_id} — One materialised session (same shape as list)
• PATCH /repos/{repo_id}/session/{session_id}/display-name — Set/clear session display name (requires push access)
• POST /repos/{repo_id}/sessions/{session_id}/share — Mark session publicly viewable (captures encrypted snapshot)
• DELETE /repos/{repo_id}/sessions/{session_id}/share — Revert session's public share

Session Transcripts (read-through to Repo API)

• GET /repos/{repo_id}/checkpoints/{checkpoint_id}/transcript — Checkpoint's sessions parsed into message tree
• GET /repos/{repo_id}/checkpoints/{checkpoint_id}/transcript/raw — Stream checkpoint session's raw full.jsonl
• GET /repos/{repo_id}/sessions/{session_id}/transcript — Session's transcript merged/parsed (optional-auth: shared sessions readable without repo access)
• GET /repos/{repo_id}/sessions/{session_id}/transcript/raw — Stream session's raw full.jsonl

Repository Settings (requires push access)

• PATCH /repos/{repo_id}/runner-settings — Set runner settings
• PATCH /repos/{repo_id}/trail-settings — Set trail settings
• PATCH /repos/{repo_id}/settings/public-sharing — Toggle repo-level public sharing

Projects (scoped to single region)

• GET /projects/{project_id}/summary — Project rollup (complete; project's region)
• GET /projects/{project_id}/repos — Per-repo rollup within project
• GET /projects/{project_id}/contributors — Project contributor leaderboard
• GET /projects/{project_id}/activity — Project time buckets

Cache / Utilities

• GET /cache/prs — Caller's open pull requests across readable repos

2. AUTHENTICATION MECHANISM

The service uses the SAME authentication model as the "core" control-plane API:

Authentication Flow

1. Bearer JWT Token (only accepted credential)
   • Extracted from Authorization: Bearer <token> header
   • No session cookies or API keys
2. Token Validation (via auth.Authenticator)
   • Verified against Core's JWKS (CORE_JWKS_URL)
   • Uses EdDSA, RS256, or ES256 signatures
   • Validates token expiration (exp), not-before (nbf), issued-at (iat)
3. Audience Pinning (audience-scoped tokens)
   • Token's aud claim must equal exactlyENTIRE_JURISDICTION_AUDIENCE (this cell's jurisdiction host)
   • A token minted for another audience or jurisdiction is rejected
   • Prevents cross-region/cross-jurisdiction token reuse
4. Scope Assertion
   • Token's scope claim must contain openid (ADR 20260612)
   • Enforced by the verifier; missing scope is rejected
5. Identity Extraction
   • Token's sub claim → AccountID
   • Additional fields extracted: Handle, HomeJurisdiction, Provider, ProviderUserID
   • home_jurisdiction rides on the token itself (no per-request Core call needed)

Authorization (Post-Authentication)

• Access gate: Runs AFTER requireAuth validates the bearer

• Regional read-only SpiceDB (authz.Reader) — single process-shared gRPC connection

• Fail-closed posture: Any SpiceDB error surfaces as HTTP 503 (never stale-allows)

• Access ordering: Authorization checked before existence (403/503 before 404)

• Prevents leaking whether a repo exists in this region to unauthorized callers

• Permission verbs:

• repo.pull — read access to a repo

  • repo.push — write access to a repo
  • project.view — read access to a project

Authentication Variations

1. Standard Authenticated (requireAuth)

• Requires valid bearer token
• Returns 401 if missing or invalid
• Used by /me, /repos/{repo_id}/*, /projects/{project_id}/*, preferences, etc.

2. Optional Authentication (optionalAuth)

• Used by: GET /repos/{repo_id}/sessions/{session_id}/transcript
• Proceeds without auth if no token (anonymous visitor)
• If token present but invalid, treats as anonymous (not a hard 401)
• Downstream handler fail-closes on access

3. Anonymous Public Repo (anonOrRequireAuth)

• Used by: GET /repos/{repo_id}/commits only (so far)

• Accepts either authenticated OR anonymous reads via X-Anon-Repo header

• Anonymous flow:

• Client sends X-Anon-Repo: {repo_id} header (no Authorization)

  • Middleware checks SpiceDB for public_viewer wildcard on repo
  • If public: mints short-lived scoped JWT (forwarded to content read-through)
  • If private or signing key missing: returns 403
  • Returns 404 if repo not in this region

• Authenticated flow: Normal requireAuth + requireRepoAccess chain

mTLS Internal Listener (Optional)

• Second listener (ENTIRE_INTERNAL_LISTEN_ADDR) for in-cluster workloads
• Requires client certificate mTLS + valid jurisdiction bearer token
• Not a cert-identity bypass — all routes still run requireAuth
• SPIFFE workload allowlist gates inbound leaf cert (ENTIRE_INTERNAL_ALLOWED_WORKLOADS, default: entire-mcp)

3. DOMAIN COVERAGE

The service covers activity and checkpoint analytics for residency-safe multi-region federation:

Primary Domains

1. User Activity (/me/*)
   • Authenticated user's own commits, checkpoints, sessions, activity streams
   • Residency-safe: forwarded metadata lives in user's home jurisdiction
   • Cross-region federation: /me lists caller's jurisdictions; clients fan-out per-jurisdiction
2. Repository Analytics (/repos/{repo_id}/*)
   • Team metrics: activity, contributors, agents, sessions
   • Commits & checkpoints: lists, details, comparisons, transcripts
   • Per-repo scope: stored in single jurisdiction (complete view here, empty elsewhere)
3. Project Analytics (/projects/{project_id}/*)
   • Cross-repo rollups within a project
   • Single-jurisdiction scope (project + all repos co-located)
4. Checkpoints & Sessions
   • Checkpoint-anchored data: LLM analysis, recap labels, narrative summaries
   • Sessions: materialised views, transcripts (parsed + raw), public sharing with encrypted snapshots
   • Optional checkpoint storage repo (separate ACL gate when applicable)
5. User Preferences
   • Pinned/recent repos
   • Session detail filter defaults, diff view, filter tabs
   • User-owned product state (writable)
6. Repository Settings (requires push access)
   • Runner settings, trail settings, public sharing enablement

NOT Covered (Delegated)

• Git content (commits, diffs, branch reachability, transcripts) — read through to Repo API (entiredb git plane)
• Message text — fetched from Repo API via batch endpoint, cached immutably
• LLM inference — handled by repo-activity worker; API only serves pre-computed analysis

Residency Model

• User store (my_activity): residency-safe per-author metadata
  • Forwarded to author's home jurisdiction by repo-activity worker
  • Consumed by /me in home region only
  • Synchronized across NATS clusters (direct publish per cluster, not supercluster)
• Repo store: repo/project data stored in repo's hosting region
  • Single jurisdiction per repository
  • Team aggregates (repo_author_day rollup) from default-branch commits
  • Failure-safe lifecycle: commits without pusher_id stay unattributed

4. OPENAPI / CODE GENERATION

Yes, OpenAPI-generated:

• Framework: Huma (Go OpenAPI framework, similar to ogen)

• Document location: /api/v1/openapi.yaml and /api/v1/openapi

• Docs UI: /api/v1/docs

• Approach: Huma operations registered at runtime (not ogen schema codegen)

• Gateway merge: Product surface merged with Repo API (git plane) at gateway level

• Product owns bare /api/v1/repos/..., /me, /projects

  • Git plane sub-pathed under /api/v1/git/...
  • Single served spec without path collision

5. KEY ARCHITECTURAL NOTES

• Unified HTTP server (cmd/api): Single process serving /me/* (user store) + repo/project aggregates (repo store) + proxied git plane
• Bearer forwarding: Caller's jurisdiction token forwarded to Repo API for content read-through; authorization re-checked live there
• Fail-closed access: Every scoped route gates on SpiceDB; revoked grants stop being honored within cache TTL + replication lag
• Residency enforcement: Repos in other regions return 404; cross-region reads are client-side fan-out
• Immutable caching: Commit messages, branch SHAs cached per (repo, tip); ref move invalidates naturally
• No external NATS/workers: HTTP layer is in-process; background work (checkpoint analysis) via separate repo-activity/user-activity workers

File Paths for Reference

• Auth implementation: /Users/soph/Work/entire/devenv/entire-api/internal/auth/auth.go
• Authorization gates: /Users/soph/Work/entire/devenv/entire-api/internal/httpapi/authz.go
• Router/routes: /Users/soph/Work/entire/devenv/entire-api/internal/httpapi/router.go
• Handler implementations: /Users/soph/Work/entire/devenv/entire-api/internal/httpapi/*.go (59 routes across 10+ files)
• Context: /Users/soph/Work/entire/devenv/entire-api/CONTEXT.md (detailed auth/authz terminology)
• README: /Users/soph/Work/entire/devenv/entire-api/README.md (architecture, deployments, topology) <subagent_tokens>68112</subagent_tokens><tool_uses>33</tool_uses><duration_ms>251346</duration_ms>

Summary

Based on my investigation of the entire-api codebase, here are the answers to your questions:

1. Format of {repo_id} path parameter

Format: ULID (stored as 16-byte bytea in Postgres)

• Database schema (/Users/soph/Work/entire/devenv/entire-api/internal/store/migrations/repo/001_init.sql:100): The repos.id column is ulid PRIMARY KEY — a 26-character Crockford base32-encoded ULID
• Wire encoding (001_init.sql:22-25): ULIDs are stored internally as 16 raw bytes in the database (bytea domain), decoded to base32 on the API boundary when exposed
• No validation code in handlers: The {repo_id} parameter is extracted as a raw string via Huma and passed directly to the store without explicit parsing/validation. The store's queries simply compare the decoded bytea values
• Authorization gate (/Users/soph/Work/entire/devenv/entire-api/internal/httpapi/authz.go:121-137): The path param is passed to ac.HasPermission(ctx, "repo", repoID, permission) — no parsing, just the string value

2. Endpoints accepting repo by owner/repo name instead of ID

None exist.

The API has no lookup/resolve endpoint that maps forge/owner/repo or owner/repo to repo_id. All repo-scoped routes require the ULID {repo_id} in the path:

• GET /api/v1/repos/{repo_id}/summary
• GET /api/v1/repos/{repo_id}/checkpoints
• etc.

3. Discovery mechanism for repo_id ↔ owner/repo resolution

Yes, but only one-way (repo_id → owner/repo):

The GET /api/v1/repos discovery list returns BOTH:

• id (the ULID repo_id)
• full_name (the "owner/repo" human-readable name)

Code (/Users/soph/Work/entire/devenv/entire-api/internal/httpapi/repos.go:753-811, specifically lines 769-780):

1
2
3
4
5
6
7
8
9
10
11
12
13

// full_name prefers the GitHub "owner/repo" from github_repo_meta (entire.io's
// full_name is the GitHub name) and falls back to the repos.full_name → repo_id
// chain when there's no meta row. The derived name tracks the same resolved
// human name so the two never disagree.
humanFull := r.MetaFullName
if humanFull == "" {
    humanFull = r.FullName
}
item := RepoListItem{
    ID:       r.ID,  // ← ULID repo_id
    FullName: repoFullNameOr(store.RepoMeta{FullName: humanFull}, r.ID),  // ← "owner/repo"
    ...
}

The /me/* endpoints also return repo_full_name alongside activity items (not a separate repo_id, but the repo identity is always the full_name).

4. Format of {project_id}

Format: ULID (same as repo_id)

• Schema: repos.owning_project_id is ulid (/Users/soph/Work/entire/devenv/entire-api/internal/store/migrations/repo/001_init.sql:101)
• No lookup by name: Like repos, projects are accessed only by ULID (GET /api/v1/projects/{project_id}/summary, etc.)
• No separate discovery list: There is no GET /api/v1/projects endpoint — a client must infer project_id from the owning_project_id field on repos or know the project ULID a priori

5. GET /repos discovery list

Returns both repo_id and human name:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "repos": [\
    {\
      "id": "<ULID>",           // 26-char base32 repo_id\
      "full_name": "owner/repo", // GitHub "owner/repo" or fallback to id if unresolved\
      "name": "repo",            // Bare repo segment (null if unresolved)\
      ...\
    }\
  ],
  "updated_at": "...",
  "from_db": true
}

A client with only "owner/repo" must call GET /api/v1/repos, iterate to find the matching full_name, and extract the id field to use it in subsequent requests. <subagent_tokens>73377</subagent_tokens><tool_uses>38</tool_uses><duration_ms>4746308</duration_ms>

2w ago·49.5s

Confirmed — and this actually sharpens the picture in a useful way. Here's what repo_id turns out to be:

• entire-api addresses everything repo-scoped by ULID.repos.id is a ulid PRIMARY KEY (migrations/repo/001_init.sql:100), and {project_id} is a ULID too. Handlers pass the path string straight to SpiceDB/store with no parse — it's just expected to be the ULID.
• There is no resolve-by-remote endpoint. Nothing maps forge/owner/repo → repo_id. The only bridge is GET /api/v1/repos, which returns both id (ULID) and full_name ("owner/repo") per repo — so a client that only knows the remote must list /repos and match full_name client-side. One-way, and it costs an extra call.

But here's the key distinction for your migration: the ULID requirement bites the repo-scoped family (/repos/{repo_id}/...) — and that's not what we're moving.

The three candidates we identified don't take a repo_id in the path:

So to directly answer "the new endpoints want a ULID also, right?": yes for the per-repo endpoints, but no for the three movable ones.activity, recap, and repositories are all identity-scoped /me/* calls or the /repos list itself — full-name/identity-keyed, no ULID input.

Where the ULID genuinely blocks you is if you later want to move the repo-scoped data (per-repo checkpoints, sessions, transcripts, analytics panels). Those force a owner/repo → ULID resolution the CLI can't do cleanly today: coreapi's resolveRepoRef needs a --project to resolve a name, and entire-api only offers "list /repos and match full_name yourself." That's the resolution hop worth designing before touching the repo-scoped surface.

*One thing to verify before moving recap: entire.io's me/recap?repo=org/name takes a full name — confirm entire-api's /me/recap?repo= filter also accepts full_name and not a ULID. Want me to check that one param?

yes, please check

2w ago·13m·5 calls

Definitive answer, and it lands on the ULID side. From me_types.go:328-332:

1
2
3
4
5

// MeRecapInput mirrors entire.io /me/recap's params. repo carries a repo_id ULID
// (entire.io takes org/name). since+until (when both present) override timeframe.
type MeRecapInput struct {
    ...
    Repo string `query:"repo" doc:"Restrict to one repo_id; enables the contributors side"`

And recapRepos (me.go:840) confirms it: "Repos are repo_id ULIDs."

So entire-api's /me/recap?repo= expects a repo_id ULID, whereas entire.io's takes org/name. The port author explicitly flagged the divergence in that comment.

Net effect on the recap move

So the recap migration splits: the unfiltered recap moves cleanly, but the ?repo= team/contributor variant hits exactly the resolution gap we discussed — the CLI would need to turn org/name into the repo ULID (via GET /repos match, or a coreapi resolve), same hop the repo-scoped family needs.

activity is unaffected either way — /me/activity takes no repo param.

Summary of the whole investigation

• Clean moves, no ULID:activity → /me/activity; unfiltered me/recap → /me/recap; repositories → /repos (it's the discovery list that emits the ULIDs).
• Move + one resolution hop:me/recap?repo= (org/name → ULID).
• Not movable without building new domain: all trails/* and code-review endpoints (no trail/review surface in entire-api; depend on GitHub API + Cloudflare Durable Objects).
• The core blocker for going further (per-repo checkpoints/sessions/transcripts): everything under /repos/{repo_id}/* is ULID-addressed with no resolve-by-remote endpoint, so any move needs a owner/repo → ULID bridge the CLI doesn't have cleanly today.

Want me to sketch what that resolution bridge would look like (e.g. a cached GET /repos full_name→ULID lookup in the CLI), since it's the common unlock for both me/recap?repo= and the repo-scoped surface?

where do we want to cache it, it's a single operation, we should rather fetch it each time since it's a cli, right?

2w ago·38.5s

Agree — don't cache it. For a CLI the reasoning is straightforward:

• The process is short-lived and resolves one repo per invocation. An in-memory cache would only pay off if a single command resolved the same repo repeatedly, which none of these do. So in-process memoization buys nothing here.
• A persistent (on-disk) cache is net-negative. It trades one cheap HTTP GET for a staleness-invalidation problem: repos get renamed, access gets revoked, a repo moves region — and a stale full_name → ULID map silently points commands at the wrong (or a gone) ULID. That's exactly the class of bug the existing resolveRepoRef avoids by resolving on demand, and it's the right pattern to follow.

So: fetch each time. One extra round-trip on the commands that actually need a ULID, and correctness is free.

Two things worth keeping in mind, though:

1. It's a list-and-match, not a point lookup. entire-api has no resolve-by-remote endpoint — the only bridge is GET /repos, which returns all accessible repos and you match full_name client-side. So each "resolution" is really "fetch the whole list + scan." For a normal user that's one modest call; for someone with a very large accessible-repo set it's a bigger payload than a targeted lookup would be. Still fine to do per-invocation, but the response size grows with account size, not with what you asked for.

2. If that ever becomes the bottleneck, the fix is server-side, not a client cache — a proper GET /repos/resolve?full_name=owner/repo (or accepting forge/owner/repo on the repo-scoped routes) on entire-api. That eliminates the hop entirely instead of papering over it with cache invalidation logic on the CLI side.

And to keep it in scope: this resolution only matters for me/recap?repo= and the future repo-scoped family. The three clean-move endpoints (activity, unfiltered recap, repositories → /repos) need no resolution at all.

ok, let's do it, start a new branch and do meaningful commits

2w ago·2h 3m·14 calls

I'll wait for that trace to come back — it'll tell me the exact template format, placeholder substitution, and how the cell resolves from a mirror, which is what I need to design the CLI-side base-URL resolver correctly.

1
2
3

export function buildBaseUrl(template: string, cell: string): string {
  return template.replace("{cell}", cell).replace(/\/+$/, "")
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

export interface Mirror {
  owner: string
  repo: string
  clusterHost: string
  /**
   * Physical cell the mirror's cluster runs in, e.g. "aws-us-east-2". Fills
   * {cell} in ENTIRE_API_BASE_URL_TEMPLATE to address the cell's entire-api.
   * Optional on the wire (older cores omit it); absence means we can't route to
   * entire-api for this repo.
   */
  cell?: string
  /**
   * Jurisdiction the repo is homed in, e.g. "us"/"eu"/"au". Fills
   * {jurisdiction} in ENTIRE_API_AUDIENCE_TEMPLATE for the jurisdictional
   * identity-token audience. Optional on the wire; absence is non-routable.
   */
  jurisdiction?: string
  repoId: string
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

export async function resolveCell(args: ResolveCellArgs): Promise<ResolvedCell | null> {
  const all = await listMirrors({
    coreBaseUrl: args.coreBaseUrl,
    loginJwt: args.loginJwt,
    owner: args.owner,
    fetchImpl: args.fetchImpl,
  })
  // Filter to routable rows (cell/jurisdiction/repoId all present) BEFORE
  // selecting, so a non-routable row ordered first doesn't mask a routable
  // sibling — mirrors how resolveClusterHost filters on clusterHost.
  const matches = all.filter(
    (m) =>
      m.owner.toLowerCase() === args.owner.toLowerCase() &&
      m.repo.toLowerCase() === args.repo.toLowerCase() &&
      m.cell &&
      m.jurisdiction &&
      m.repoId,
  )
  if (matches.length === 0) {
    return null
  }

const preferred = args.preferredCluster
    ? matches.find((m) => m.clusterHost === args.preferredCluster)
    : undefined
  const match = preferred ?? matches[0]

return {
    cell: match.cell as string,
    jurisdiction: match.jurisdiction as string,
    repoId: match.repoId,
    owner: match.owner,
    repo: match.repo,
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

async function callEntireApi(ctx: Ctx, entry: ResolveCellCacheEntry): Promise<Response> {
     const audience = buildAudience(ctx.deps.audienceTemplate, entry.jurisdiction)
     const coreBaseUrl = buildCoreBaseUrl(
       ctx.deps.coreBaseUrlTemplate,
       entry.jurisdiction,
       ctx.deps.cfg.coreBaseUrl,
     )
     const token = await getTokenCached(ctx, audience, coreBaseUrl)
     const baseUrl = buildBaseUrl(ctx.deps.baseUrlTemplate, entry.cell)
     return fetchEntireApi({
       baseUrl,
       token,
       path: ctx.params.pathFor(entry.repoId),
       search: ctx.params.search,
       method: ctx.params.method,
       body: ctx.params.body,
       fetchImpl: ctx.fetchImpl,
     })
}

1
2
3
4
5
6
7
8
9

const audience = buildAudience(ctx.deps.audienceTemplate, entry.jurisdiction)
// Mint at the repo's own jurisdiction core, not a single fixed one — a cell
// only trusts a token signed by its region's core.
const coreBaseUrl = buildCoreBaseUrl(
  ctx.deps.coreBaseUrlTemplate,
  entry.jurisdiction,
  ctx.deps.cfg.coreBaseUrl,
)
const token = await getTokenCached(ctx, audience, coreBaseUrl)

2w ago·10m·9 calls

entire.io/api uses three templates (buildBaseUrl/buildAudience/buildCoreBaseUrl). I'll port them as pure, validated Go functions. Writing commit 1:

sorry, misstyped, yes please do

2w ago·1h 31m·62 calls

Full CI gate is green — unit tests, integration, and both E2E canary suites (Vogon 59/59, roger-roger 4/4) all pass.

Done — branch soph/cli-me-endpoints-to-entire-api

Four meaningful commits migrate activity and recap from the entire.io data API to entire-api (same-auth-as-core), gated behind operator templates with graceful fallback:

Key findings that shaped it:

• activity/recap already call /me/activity and /me/recap — the exact paths entire-api serves — so this was a routing change, not a response rewrite.
• entire-api serves no .well-known, so I added ResolveEntireAPIToken to mint a jurisdictional token (aud = {jurisdiction}) from the active context — reusing the existing NewRefreshingResourceProvider primitive.
• The ULID blocker dissolved: coreapi.Mirror.MirrorId is the repo ULID entire-api wants (per entire.io/api's own docs), and the CLI already fetches it — so recap's team column works with no extra lookup, and no scope creep.

Behavior: entire-api routing is opt-in — with the templates unset (every current user), both commands behave exactly as before. When set, routing kicks in only for repos with a routable mirror; unroutable repos fall back silently, while genuine failures (control plane down, bad template, rejected token) surface.

Not done (as scoped):repositories → /repos was left out per your earlier call. I didn't push — branch is local and CI-green whenever you want to open a PR.

One deferred follow-up worth noting in the code comments: token minting uses the active context's core, which is correct for single-core deployments; minting at a foreign jurisdiction's core (via ENTIRE_CORE_BASE_URL_TEMPLATE) is stubbed but not wired.

cb49244cli: resolve entire-api cell/jurisdiction from a repo's mirror\ \ entire-api is addressed per-cell, and (per the chosen design) the cell\ comes from the target repo's mirror — the same source entire.io/api's\ resolveCell uses. Add the placement selector: given a repo's mirrors\ (listed via the existing listMirrorsForRepo), pick one carrying both a\ cell and a jurisdiction, preferring a named cluster and otherwise taking\ the first routable row — matching resolveCell's `preferred ?? matches[0]`\ and its filter-before-select ordering.\ \ Pure selector + forge→provider mapping only (both unit-tested); the\ repo-resolution glue that calls the control plane lands with the client\ wiring so nothing here is dead.\ \ Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com\ Entire-Checkpoint: 5b0d9a00a86d+176

efe23fdcli: route `entire activity` to entire-api when configured\ \ Assemble the entire-api client for the current repo and point `activity`\ at it. The command already calls /me/activity and /me/commits — the exact\ paths entire-api serves — so this is a routing change, not a response\ rewrite:\ \ - auth.ResolveEntireAPIToken mints a jurisdictional identity token for\ an explicit audience (no /.well-known; entire-api serves none),\ exchanged from the active login context.\ - newEntireAPIClientForCurrentRepo ties it together: resolve the repo's\ mirror → cell/jurisdiction, fill the base-URL/audience templates, mint\ the token, return a client pointed at https://{cell}.api.entire.io.\ - runAuthenticatedActivityAPI prefers that client and falls back to the\ data API when the ENTIRE_API_* templates are unset or the repo isn't\ routable, so existing users are unaffected.\ \ Fallback is silent; genuine failures (control plane down, token rejected,\ bad template) surface. recap moves next.\ \ Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com\ Entire-Checkpoint: 690550a49bd7+194/-1

2bf185acli: route `entire recap` to entire-api, team column included\ \ recap always sends the current repo as /me/recap's ?repo= to render the\ team/contributors column. entire-api addresses repos by ULID there, not\ owner/repo — but entire.io/api documents the mirror id as *exactly* that\ repo_id (repo_id = mirror_repos.id; "mirrorId is exactly the repoId\ entire-api wants"). The CLI already fetches mirrorId in the same listing\ it uses for the cell, so no extra lookup is needed.\ - Carry the mirror id through as entireAPIPlacement.RepoID and expose it\ from the entire-api client as repoID.\ - newRecapClient now returns the correct ?repo= value for its client: the\ repo ULID on entire-api, the owner/repo slug on the data API. It prefers\ the entire-api cell and, keeping recap's render-through-401 behaviour,\ falls back to the data API when not logged in.\ \ Both personal and team recap work on entire-api; no owner/repo→ULID\ side-lookup required after all.\ \ Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com\ Entire-Checkpoint: 43577009ee6c+65/-29

can you look at in this context: https://entire.io/gh/entireio/cli/trails/715

2w ago·21.4s·1 call

Let me pull up trail 715 using the authenticated CLI rather than the web (which needs a browser login).

I moved this session to the cli folder, it's the right folder now, no need to move to cli_experiments

2w ago·4m·9 calls

Sure — what would you like to clarify before I reframe the options? A few things that might be behind your question:

• Ownership/coordination — is 715 (suhaanthayyil) yours to sequence, or would landing order need to be coordinated with them?
• Scope of sharing — are you questioning whether activity/recap should really share 715's client at all (e.g. /me/* home-routing vs. the repo-scoped path 715 was built for), rather than just when?
• Something about my comparison — did I mischaracterize how 715 works, or is there a constraint (e.g. 715 might change significantly, or it's blocked) that makes my framing off?

Tell me what's on your mind and I'll rework the question — or just tell me the direction and I'll proceed.

can you review 715 fully, then I can stamp it and merge it and we can continue

2w ago·5m·8 calls

Review: trail 715 / codex/experts-cell-routing

Verdict: approve — safe to stamp and merge. It builds, all tests pass, lint is clean (0 issues), and the security-sensitive parts (JWT handling, token exchange, URL construction) are carefully hardened. No blocking issues. A handful of minor notes below, none merge-blocking.

What it does

Routes the experts commands' repo-scoped calls to the entire-api cell that hosts the repo, with a jurisdictional identity token (scope=openid, aud=<jurisdiction host>) — because the BFF doesn't proxy those routes for bearer callers (COR-666). Cell is resolved from the control plane (repo → ClusterHost → cluster catalog apiUrl+jurisdiction); on any failure it degrades to home-jurisdiction routing.

Strengths

• Genuinely fail-safe fallback. Every resolution failure (not logged in, core error, timeout, ambiguous placement, missing apiUrl) returns nil → home routing = prior behavior. The common same-region case can't regress. The 5s resolve timeout keeps a hung core from stalling the command.
• Security hardening is solid.requireSafeExchangeURL affirmatively requires https (not merely "not http") on both the core (where the login JWT is sent) and the cell (where the identity token is sent), so a buggy catalog can't exfiltrate credentials over ftp/ws/scheme-relative. The home_jurisdiction claim is decoded from an unverified JWT but bounded by jurisdictionLabelPattern to a single DNS label before any URL templating — good defense-in-depth, and the risk is documented.
• Environment-agnostic (isBFFOrigin, entireDomainFamily): recognizes prod/staging and honors loopback + env template overrides without a hardcoded prod default.
• Correct control-plane usage: RFC 8693 exchange as a public client (client_id=entire-cli, no secret) — right for the CLI, vs. the BFF's confidential-client flow.
• Strong test coverage: jurisdiction parsing, BFF detection, family/template precedence, bad-label rejection, safe-URL, home-cell/direct-cell/target routing, multi-region & inactive-mirror handling.
• Thoughtful UX: the 404 "repo not in this region" now surfaces an actionable cross-region hint.

Minor notes (non-blocking; optional follow-ups)

1. Asymmetric jurisdiction casing.resolveExpertsCellTarget lowercases cluster.Jurisdiction, but the home-JWT path (homeJurisdictionFromLoginJWT → targetJurisdiction) doesn't — an uppercase home_jurisdiction claim would hard-fail jurisdictionLabelPattern instead of routing. Convention is lowercase, so low-impact, but lowercasing the JWT-derived value too would be more robust.
2. Home fallback lists clusters at the templated jurisdiction core, not the discovered login core (selected.CoreURL). For the home jurisdiction these normally coincide; in an exotic template/multi-core setup they could differ and 401. Worth a comment or using selected.CoreURL for the home-fallback cluster listing.
3. isBFFOrigin depends on cells containing .api. in the host. Fine given the {cell}.api.<domain> convention, but a vanity cell host would be misclassified as a BFF. Reasonable to leave; just an encoded assumption.
4. 503-on-query broadened to always mean "code search unavailable" — a genuinely transient cell 503 on a query would now read as a config message. Documented trade-off (bare "Service Unavailable" bodies); acceptable.
5. Two cluster-listing paths — hand-parsed in auth (import-cycle avoidance, documented) vs. generated coreapi.ListClusters in the cli layer. Minor duplication, well-justified.

Relevance to our work

This is the mature version of exactly the infra my activity/recap branch built. Once you merge, my branch should collapse onto auth.NewEntireAPICellClient (nil target = home routing for the /me/* endpoints), keeping only the mirrorId == repo_id bit for recap's ?repo=. Note it already carries ENTIRE_API_AUDIENCE_TEMPLATE / ENTIRE_CORE_BASE_URL_TEMPLATE (superset of my entireapi.go templates), so my template file becomes redundant.

Go ahead and stamp it — and once it's on main, tell me and I'll rebase the activity/recap work onto the shared client.

ok, merged, can you also address the nits after rebasing

2w ago·24m·38 calls

Full CI gate is green — all unit tests, integration, and both canary suites (Vogon 59/59, roger-roger 4/4) pass.

Done — rebased, reconciled, nits addressed

Branch soph/cli-me-endpoints-to-entire-api now sits cleanly on the merged 715 with two focused commits (I collapsed the four exploratory commits, since 715's shared client made my parallel template/cell/token machinery redundant — carrying it just to delete it would've been churn):

8a978d3 — cli/auth: address review nits on entire-api cell routing (the 715 follow-ups)

• Nit 1: case-fold the home_jurisdiction JWT claim before the strict [a-z0-9-] label check, so an uppercase claim routes instead of hard-failing. Added a test.
• Nit 2: the home-jurisdiction fallback now lists the cluster catalog against the discovered login core (selected.CoreURL) — which signs the login JWT — rather than the templated jurisdiction core that could reject it in a multi-core setup.
• Added ErrNoCellForJurisdiction sentinel wrapping the "no cell / no apiUrl" errors, so callers can degrade cleanly.

f7eccb6 — cli: route activity/recap through the shared entire-api cell client

• activity and recap now go through auth.NewEntireAPICellClient(…, nil) (home routing) — one routing/token path across the CLI, matching experts.
• Best-effort upgrade: any cell-client failure (no cell yet, not logged in, discovery/exchange error) falls back to the data API, which also serves /me/* and yields the canonical auth errors. This preserved the "not logged in" hint (a regression the test caught) and keeps existing users unaffected until their region has a cell.
• recap's team column keeps working: currentRepoID resolves the repo ULID from the mirror id (which entire-api treats as repo_id), best-effort.

I did not touch the nits I flagged as intentional/acceptable in the review: the 503→"code search unavailable" broadening (a deliberate 715 commit), the .api. host-detection convention, and the two cluster-listing paths (import-cycle-driven, documented).

Note: mise run lint locally flags two pre-existing goconst issues in review_context.go / runner_gather.go — both on main, untouched by me; CI's new-issues-only mode won't flag them. Nothing pushed yet; say the word and I'll open the PR.

8a978d3cli/auth: address review nits on entire-api cell routing\ \ Follow-ups from the 715 review:\ - Case-fold the home_jurisdiction claim from the login JWT before the\ strict [a-z0-9-] label check. The repo-target path already lowercases;\ the JWT path did not, so an uppercase claim would hard-fail instead of\ routing.\ - List the cluster catalog in the home-jurisdiction fallback against the\ discovered login core (selected.CoreURL) rather than the templated\ jurisdiction core — the login JWT is signed by the former, so in a\ multi-core setup the templated core could reject it. The exchange core\ is unchanged.\ - Add the ErrNoCellForJurisdiction sentinel and wrap the "no cell / no\ apiUrl" errors with it, so callers with a data-API fallback (activity,\ recap next) can degrade instead of failing when a region has no cell.\ \ Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com\ Entire-Checkpoint: e94d8b46f42c+30/-6

f7eccb6cli: route activity/recap through the shared entire-api cell client\ \ Reconcile onto the cell-routing client that landed with the experts work\ (#1588) instead of a parallel mechanism. `activity` and `recap` call the\ /me/* endpoints entire-api serves, so they now go through\ auth.NewEntireAPICellClient (home-jurisdiction routing, target=nil) — one\ routing/token path across the CLI.\ \ Cell routing is a best-effort upgrade: any failure building the cell\ client (no cell for the region, not logged in, discovery/exchange error)\ falls back to the data API, which also serves /me/* and yields the\ canonical auth errors — so existing users are unaffected until their\ region has a cell. recap keeps its render-through-401 behaviour via that\ fallback.\ \ recap's team column still needs the repo ULID for /me/recap?repo=;\ currentRepoID resolves it best-effort from the mirror id (which entire-api\ treats as the repo_id), empty → personal recap only.\ \ Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com\ Entire-Checkpoint: dc4fb6be0484+169/-7

/simplify → 4 cleanup agents in parallel → apply the fixes

You are improving the quality of the changed code, not hunting for bugs. Review it for reuse, simplification, efficiency, and altitude issues, then fix what you find. Do not look for correctness bugs — that is what /code-review is for.

Phase 0 — Gather the diff

Run git diff @{upstream}...HEAD (or git diff main...HEAD / git diff HEAD~1 if there's no upstream) to get the unified diff under review. If there are uncommitted changes, or the range diff is empty, also run git diff HEAD and include the working-tree changes in scope — the review often runs before the commit. If a PR number, branch name, or file path was passed as an argument, review that target instead. Treat this diff as the review scope.

Phase 1 — Review (4 cleanup agents in parallel)

Launch 4 independent review agents via the Agent tool, all in a single message so they run concurrently. Pass each agent the diff and one of the four angles below. Each returns its findings with file, line, a one-line summary, and the concrete cost (what is duplicated, wasted, or harder to maintain).

Reuse

Flag new code that re-implements something the codebase already has — Grep shared/utility modules and files adjacent to the change, and name the existing helper to call instead.

Simplification

Flag unnecessary complexity the diff adds: redundant or derivable state, copy-paste with slight variation, deep nesting, dead code left behind. Name the simpler form that does the same job.

Efficiency

Flag wasted work the diff introduces: redundant computation or repeated I/O, independent operations run sequentially, blocking work added to startup or hot paths. Also flag long-lived objects built from closures or captured environments — they keep the entire enclosing scope alive for the object's lifetime (a memory leak when that scope holds large values); prefer a class/struct that copies only the fields it needs. Name the cheaper alternative.

Altitude

Check that each change is implemented at the right depth, not as a fragile bandaid. Special cases layered on shared infrastructure are a sign the fix isn't deep enough — prefer generalizing the underlying mechanism over adding special cases.

Phase 2 — Apply the fixes

Wait for all four agents to complete, dedup findings that point at the same line or mechanism, and fix each remaining one directly. Skip any finding whose fix would change intended behavior, require changes well outside the reviewed diff, or that you judge to be a false positive — note the skip rather than arguing with it. Finish with a brief summary of what was fixed and what was skipped (or confirm the code was already clean).

2w ago·59.5s·5 calls

All four cleanup agents are running. Waiting for their findings before deduping and applying.

newRecapClient() on cell success:
  1. NewEntireAPICellClient() [already happened]
     - Discovers login context and token info
     - Exchanges JWT at entire-core
  2. currentRepoID() [NEW, REDUNDANT]
     - Creates coreapi.New()
     - Calls ListMirrors(gh, owner, repo) ← WASTED call
     - Filters results

1
2
3
4
5
6
7
8
9
10
11

if client, err := auth.NewEntireAPICellClient(ctx, insecureHTTP, nil); err == nil {
    return client, currentRepoID(ctx), nil
} else if !errors.Is(err, auth.ErrNoCellForJurisdiction) {
    // Best-effort upgrade: fall back to the data API on any cell failure...
    logging.Debug(ctx, "recap: entire-api cell client unavailable, using data API", "error", err.Error())
}

if insecureHTTP {
    auth.EnableInsecureHTTP()
}
// ... rest of data API path

1
2
3
4
5
6
7

if client, err := auth.NewEntireAPICellClient(ctx, insecureHTTP, nil); err == nil {
    return client, currentRepoID(ctx), nil
}
// Fall back to data API on any cell failure (including ErrNoCellForJurisdiction, which isn't logged)
if !errors.Is(err, auth.ErrNoCellForJurisdiction) {
    logging.Debug(ctx, "recap: entire-api cell client unavailable, using data API", "error", err.Error())
}

1
2
3
4
5
6
7
8

client, err := auth.NewEntireAPICellClient(ctx, insecureHTTP, nil)
if err != nil {
    if !errors.Is(err, auth.ErrNoCellForJurisdiction) {
        logging.Debug(ctx, "...", "error", err.Error())
    }
    return runAuthenticatedDataAPI(ctx, errW, insecureHTTP, fn) // or fallback to data API path
}
return fn(ctx, client)

1
2
3
4
5
6
7
8
9
10
11
12

// tryAndFallbackToDataAPI attempts cellFn with the cell client, logging non-obvious failures.
// On any error, falls back to dataAPIFn with the data API client.
func tryAndFallbackToDataAPI(ctx context.Context, cellFn func(*api.Client) error, dataAPIFn func(*api.Client) error, insecureHTTP bool, errW io.Writer) error {
    client, err := auth.NewEntireAPICellClient(ctx, insecureHTTP, nil)
    if err != nil {
        if !errors.Is(err, auth.ErrNoCellForJurisdiction) {
            logging.Debug(ctx, "cell client unavailable, using data API", "error", err.Error())
        }
        return runAuthenticatedDataAPI(ctx, errW, insecureHTTP, dataAPIFn)
    }
    return cellFn(client)
}

1
2
3
4
5
6
7
8

func forgeToMirrorProvider(forge string) (string, bool) {
    switch strings.ToLower(strings.TrimSpace(forge)) {
    case "gh", mirrorCloneProviderGitHub:
        return mirrorCloneProviderGitHub, true
    default:
        return "", false
    }
}

1
2
3
4
5
6
7

func forgeToMirrorProvider(forge string) (string, bool) {
    normalized := strings.ToLower(strings.TrimSpace(forge))
    if normalized == "gh" || normalized == mirrorCloneProviderGitHub {
        return mirrorCloneProviderGitHub, true
    }
    return "", false
}

1
2
3
4
5
6
7
8

func forgeToMirrorProvider(forge string) (string, bool) {
    switch strings.ToLower(strings.TrimSpace(forge)) {
    case "gh", "github":
        return mirrorCloneProviderGitHub, true
    default:
        return "", false
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

func firstActiveRepoID(mirrors []coreapi.Mirror) string {
    for i := range mirrors {
        if mirrors[i].IsArchived.Or(false) {
            continue
        }
        if st := mirrors[i].Status.Or(coreapi.MirrorStatusReady); st == coreapi.MirrorStatusFailed || st == coreapi.MirrorStatusSuspended {
            continue
        }
        if id := strings.TrimSpace(mirrors[i].MirrorId); id != "" {
            return id
        }
    }
    return ""
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

func firstActiveRepoID(mirrors []coreapi.Mirror) string {
    for i := range mirrors {
        if mirrors[i].IsArchived.Or(false) {
            continue
        }
        if st := mirrors[i].Status.Or(coreapi.MirrorStatusReady); st == coreapi.MirrorStatusFailed || st == coreapi.MirrorStatusSuspended {
            continue
        }
        if id := strings.TrimSpace(mirrors[i].MirrorId); id != "" {
            return id  // early return on first valid ID
        }
        // Implicitly continue to next mirror if ID is empty
    }
    return ""
}

1
2
3
4
5
6
7
8
9
10
11
12

func firstActiveRepoID(mirrors []coreapi.Mirror) string {
    for i := range mirrors {
        m := mirrors[i]
        if m.IsArchived.Or(false) || (m.Status.Or(coreapi.MirrorStatusReady).In(coreapi.MirrorStatusFailed, coreapi.MirrorStatusSuspended)) {
            continue
        }
        if id := strings.TrimSpace(m.MirrorId); id != "" {
            return id
        }
    }
    return ""
}

1
2
3
4
5
6
7
8

// RepoPlacement describes one of a repo's active mirror placements
type RepoPlacement struct {
    ClusterHost string   // for experts to map to cell via catalog
    MirrorID    string   // for activity/recap to scope ULID-keyed queries
}

// ResolveRepoPlacement best-effort resolves the repo and filters to active placements
func ResolveRepoPlacement(ctx context.Context, ...) ([]RepoPlacement, error)

1
2
3
4
5
6
7
8
9
10
11
12
13

// Categorize cell resolution failures
var (
    // ErrNoCellForJurisdiction: region has no entire-api yet, fallback is safe
    ErrNoCellForJurisdiction = errors.New("...")

// ErrCellResolutionAvailable: discovery/infrastructure problem, not a cell-vs-home choice
    ErrCellResolutionUnavailable = errors.New("...")
)

// Or: a structured error type
type CellResolutionError struct {
    reason string // "jurisdiction", "not_logged_in", "discovery_unavailable", "exchange_failed"
}

entire api [--to core|data|cell] [-X METHOD] [-f k=v] [-F k=v] [-H h:v] [--input f] [-q JQ] [-i] <path>

entire api /api/v1/clusters                            # core (default)
entire api --to cell /api/v1/me/activity               # home cell
entire api --to cell "/api/v1/me/recap?repo={repo_id}" # ULID placeholder
entire api -X POST /api/v1/projects -f name=demo

1

entire api --to cell "/api/v1/me/recap?owner={owner}&repo={repo}&repo_id={repo_id}"

1
2
3
4
5
6
7
8
9
10
11
12

func expandAPIPlaceholders(ctx context.Context, s string) (string, error) {
  // Resolve git once upfront if needed
  var forge, owner, repo string
  if strings.Contains(s, "{owner}") || strings.Contains(s, "{repo}") || strings.Contains(s, "{repo_id}") {
    var err error
    forge, owner, repo, err = gitremote.ResolveRemoteRepo(ctx, "origin")
    if err != nil {
      return "", fmt.Errorf("resolve origin remote: %w", err)
    }
  }
  // ... reuse forge/owner/repo; pass to resolveCurrentRepoID if {repo_id} present
}

1

if body := bytes.TrimSpace(raw); len(body) > 0 && json.Valid(body) {

1
2
3
4
5
6
7
8

toWrite := raw
if body := bytes.TrimSpace(raw); len(body) > 0 {
  var pretty bytes.Buffer
  if err := json.Indent(&pretty, body, "", "  "); err == nil {
    pretty.WriteByte('\n')
    toWrite = pretty.Bytes()
  }
}

1
2
3
4

path, err := expandAPIPlaceholders(ctx, rawPath)      // blocks on git I/O
fields, err := buildAPIFields(f.rawFields, f.typedFields)  // CPU-bound
req, err := buildAPIRequestBody(ctx, path, f, fields)     // CPU-bound, depends on path
headers, err := parseAPIHeaders(f.headers)                 // CPU-bound

1
2
3
4
5
6
7
8
9

var wg sync.WaitGroup
var fields map[string]any
var headers http.Header
var fieldErr, headerErr error

wg.Add(2)
go func() { fields, fieldErr = buildAPIFields(...); wg.Done() }()
go func() { headers, headerErr = parseAPIHeaders(...); wg.Done() }()
wg.Wait()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// Instead of expandAPIPlaceholders calling resolveCurrentRepoID which re-resolves:
func expandAPIPlaceholders(ctx context.Context, s string) (string, error) {
    if !strings.Contains(s, "{") {
        return s, nil
    }
    var forge, owner, repo string
    if strings.Contains(s, "{owner}") || strings.Contains(s, "{repo}") || strings.Contains(s, "{repo_id}") {
        var err error
        forge, owner, repo, err = gitremote.ResolveRemoteRepo(ctx, "origin")
        if err != nil {
            return "", fmt.Errorf("resolve remote: %w", err)
        }
        s = strings.ReplaceAll(s, "{owner}", owner)
        s = strings.ReplaceAll(s, "{repo}", repo)
    }
    if strings.Contains(s, "{repo_id}") {
        id, err := resolveCurrentRepoID(ctx, forge, owner, repo)
        if err != nil {
            return "", err
        }
        s = strings.ReplaceAll(s, "{repo_id}", id)
    }
    return s, nil
}

1
2
3
4
5
6
7
8
9
10
11

// Instead of:
var stdinReader = func(context.Context) io.Reader { return os.Stdin }
// in readAPIInput:
raw, err := io.ReadAll(io.LimitReader(stdinReader(ctx), apiMaxResponseBytes))

// Use direct os.Stdin or inject via a builder type:
type apiCmdDeps struct {
    stdin io.Reader
}
// Default: deps.stdin = os.Stdin
// Test: deps.stdin = testReader

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

func buildAPIFields(rawFields, typedFields []string) (map[string]any, error) {
    out := make(map[string]any, len(rawFields)+len(typedFields))
    for _, kv := range rawFields {
        if err := addField(out, kv, false); err != nil {
            return nil, err
        }
    }
    for _, kv := range typedFields {
        if err := addField(out, kv, true); err != nil {
            return nil, err
        }
    }
    return out, nil
}

func addField(out map[string]any, kv string, infer bool) error {
    k, v, ok := strings.Cut(kv, "=")
    if !ok || k == "" {
        return fmt.Errorf("invalid field %q (want key=value)", kv)
    }
    if infer {
        out[k] = inferFieldValue(v)
    } else {
        out[k] = v
    }
    return nil
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

func runAPI(ctx context.Context, w, errW io.Writer, rawPath string, f *apiFlags) error {
    client, err := resolveAPIClient(ctx, f.to, applyInsecureHTTPAuth(f.insecureHTTP))
    if err != nil {
        return err
    }

// Expand placeholders inline
    path := rawPath
    if strings.Contains(path, "{") {
        if path, err = expandAPIPlaceholders(ctx, path); err != nil {
            return err
        }
    }

// Parse fields inline
    fields := make(map[string]any, len(f.rawFields)+len(f.typedFields))
    for _, kv := range f.rawFields {
        // ... parse …
    }
    // ... etc

// Defer the two substantive builders
    req, err := buildAPIRequestBody(ctx, path, f, fields)
    headers, err := parseAPIHeaders(f.headers)
    // ... send & respond
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

func buildAPIRequestBody(ctx context.Context, path string, f *apiFlags, fields map[string]any) (apiRequest, error) {
    method := strings.ToUpper(strings.TrimSpace(f.method))

// Infer method early
    if method == "" {
        if f.input != "" || len(fields) > 0 {
            method = http.MethodPost
        } else {
            method = http.MethodGet
        }
    }

// Now route by input vs fields
    if f.input != "" {
        if len(fields) > 0 {
            return apiRequest{}, errors.New("use either --input or -f/-F, not both")
        }
        raw, err := readAPIInput(ctx, f.input)
        if err != nil {
            return apiRequest{}, err
        }
        return apiRequest{method: method, path: path, body: bytes.NewReader(raw)}, nil
    }

// Fields: GET → query, else → JSON body
    if len(fields) > 0 && method == http.MethodGet {
        q, err := fieldsToQuery(fields)
        if err != nil {
            return apiRequest{}, err
        }
        return apiRequest{method: method, path: appendQuery(path, q), body: nil}, nil
    }
    if len(fields) > 0 {
        // … marshal to JSON body
    }
    return apiRequest{method: method, path: path, body: nil}, nil
}

1
2
3
4
5
6
7
8
9
10
11

func parseKeyValue(kv, sep string, allowEmptyKey bool) (string, string, error) {
    k, v, ok := strings.Cut(kv, sep)
    if !ok {
        return "", "", fmt.Errorf("invalid format %q (want key%cvalue)", kv, rune(sep[0]))
    }
    k = strings.TrimSpace(k)
    if !allowEmptyKey && k == "" {
        return "", "", fmt.Errorf("empty key in %q", kv)
    }
    return k, strings.TrimSpace(v), nil
}

1
2
3
4
5
6
7
8
9
10
11

for i := range mirrors {
  if mirrors[i].IsArchived.Or(false) {
    continue
  }
  if st := mirrors[i].Status.Or(coreapi.MirrorStatusReady); st == coreapi.MirrorStatusFailed || st == coreapi.MirrorStatusSuspended {
    continue
  }
  if id := strings.TrimSpace(mirrors[i].MirrorId); id != "" {
    return id, nil
  }
}

1
2
3

func distinctActiveClusterHosts(mirrors []coreapi.Mirror) []string {
  // Filters archived + failed/suspended mirrors, returns deduped hosts
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

func resolveAPIClient(ctx context.Context, to string, insecure bool) (*api.Client, error) {
  switch strings.ToLower(strings.TrimSpace(to)) {
  case "", "core":
    target, err := resolveAuthStatusTarget(ctx, auth.Contexts, auth.RefreshedLoginToken)
    if err != nil {
      return nil, err
    }
    // ... token validation, URL check ...
    return api.NewClientWithBaseURL(target.token, target.coreURL), nil
  case "cell":
    client, err := auth.NewEntireAPICellClient(ctx, insecure, nil)
    if err != nil {
      return nil, err
    }
    return client, nil
  }
}

1
2
3
4
5
6

func expandAPIPlaceholders(ctx context.Context, s string) (string, error) {
  if !strings.Contains(s, "{owner}") && !strings.Contains(s, "{repo}") && !strings.Contains(s, "{repo_id}") {
    return s, nil
  }
  // ... lazy resolution: {owner}/{repo} from git remote, {repo_id} from mirror lookup ...
}

1

entire api --to cell "/api/v1/me/activity?timezone=Europe/Berlin&timeframe=last-month&limit=1000"

1
2
3
4
5
6
7
8

# control plane instead of the cell (different data):
entire api --to core "/api/v1/me/activity?timezone=Europe/Berlin"

# see status + headers too:
entire api -i --to cell "/api/v1/me/activity?timezone=UTC&timeframe=last-3-months"

# pipe to jq for a slice:
entire api --to cell "/api/v1/me/activity?timezone=UTC" | jq '.stats'

019f2341-f90  Low  open  current  cmd/entire/cli/api/client.go:157
  The `Request` escape hatch passes user -H headers through, but do() sets
  Content-Type: application/json … clobbering a user-supplied Content-Type…