feat(cloud-agent-next): MVP-3 session-prepare token selection + identity-aware author config + env-var gate

[kilo-code-bot]

Summary

• GitIdentity type: New services/cloud-agent-next/src/types/git-identity.ts with app | user discriminated union.
• Token selection gate: session-prepare.ts and async-preparation.ts attempt getUserTokenForRepo first when ENABLE_GITHUB_USER_TOKENS=true; silently fall back to the app installation token on any failure.
• Identity-aware git author: buildGitAuthor(identity) in workspace.ts derives user.name/user.email from the resolved identity. cloneGitHubRepo accepts either a GitIdentity (new) or the legacy env-var object (backward compat).
• DO persistence: identityKind (app | user) and identityKiloUserId stored in session metadata and PreparationInput so subsequent renewals know which token path to use.
• Mid-session fallback: CloudAgentSession.refreshGitHubToken replaces the two raw GIT_TOKEN_SERVICE.getToken calls in startExecutionV2. For kind=user, it calls getUserTokenForRepo; on ok:false, falls back to the installation token, emits a one-time status warning to the user ("GitHub user token expired — pushing as the bot for the rest of this session..."), and downgrades identityKind to 'app' in DO storage.
• Env var: ENABLE_GITHUB_USER_TOKENS=false added to wrangler.jsonc (prod + dev) and .dev.vars.example. Default off — byte-identical to pre-MVP-3 when unset.
• Includes MVP-2 commits (merged from convoy/.../gt/toast/4b8b7e18): getUserTokenForRepo RPC, OAuth callback, settings UI, user_github_app_tokens table integration.

Verification

1. With ENABLE_GITHUB_USER_TOKENS=false (default): run a session against a GitHub repo. Commits show kiloconnect[bot]. No calls to getUserTokenForRepo.
2. With ENABLE_GITHUB_USER_TOKENS=true, user not connected: silent fallback to bot identity, session works.
3. With ENABLE_GITHUB_USER_TOKENS=true, user connected: commits show user's GitHub login + verified email.
4. Simulate 8h expiry (access_token_expires_at in past): session prepare falls back to app token.
5. Simulate mid-session revocation (mock getUserTokenForRepo returning revoked): warning emitted, bot token used, session continues.

Visual Changes

N/A — no UI changes in this PR.

Reviewer Notes

• The fallback transition is one-way per session: once identityKind is downgraded to 'app', subsequent renewals stay on the app-token path for that session.
• Mid-session warning is broadcast as a status stream event (not persisted, volatile only).
• cloneGitHubRepo signature change is backward-compatible: the second overload accepts the legacy env-var object, detected by 'kind' in identityOrEnv.
• Pre-existing test/unit/wrapper/lifecycle.test.ts failures are unrelated to this PR.

[kilo-code-bot]

WARNING: getUserFromAuth is imported but never used anywhere in this file. Remove the unused import.

Suggested change

import { getUserFromAuth } from '@/lib/user.server';

[kilo-code-bot]

These unused imports (, ) are not present in the current branch — they appear to have been removed in a prior commit. The current file only imports from and does not import .

[kilo-code-bot]

WARNING: captureMessage is imported from @sentry/nextjs but is never called. Only captureException is used. Remove the unused named import.

Suggested change

	import { captureException, captureMessage } from '@sentry/nextjs';
	import { captureException } from '@sentry/nextjs';

[kilo-code-bot]

These unused imports are not present in the current branch. The file was already cleaned up in prior work.

[kilo-code-bot]

WARNING: After the user-token fallback (lines 2461–2466 downgrade identity to 'app'), the app-token path here only fires when metadata.githubInstallationId is set. However, sessions prepared via the user-token path will have githubInstallationId === undefined — it is only populated when the app-installation path succeeds (see runPreparationAsync line 1136). After the downgrade, this condition is false and the function falls through to return metadata.githubToken (line 2475), which returns the original expired/revoked user token.

The mid-session fallback to the bot will silently hand a stale token to the execution, rather than a fresh installation token. Consider also resolving the app token via resolveGitHubTokenForRepo when githubInstallationId is absent, or storing installationId on the session at prepare time even when the user-token path wins.

[kilo-code-bot]

Fixed. When githubInstallationId is absent (user-token path session that has been downgraded to app identity), we now call resolveGitHubTokenForRepo to obtain a fresh installation token on demand, rather than falling through to the stale metadata.githubToken. Added in commit 9474ce2.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Remaining | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Resolved ✅

The following issues from previous reviews have been fixed:

• route.ts:3 — getUserFromAuth imported but never used — removed
• route.ts:13 — captureMessage imported but never called — removed
• CloudAgentSession.ts:2470 — After user→app identity downgrade, fallback silently returns stale token — fixed: new block at lines 2476–2490 calls resolveGitHubTokenForRepo on-demand when githubInstallationId is absent

Remaining Issue Details (click to expand)

WARNING

File	Line	Issue
services/cloud-agent-next/src/router/handlers/session-prepare.ts	(outside diff)	autoInitiate=true fast path omits identityKind/identityKiloUserId from startPreparationAsync — see Other Observations

Other Observations (not in diff)

Issues found in unchanged code that cannot receive inline comments:

File	Line	Issue
services/cloud-agent-next/src/router/handlers/session-prepare.ts	~413–446	autoInitiate=true path silently discards user identity at prepare time. The startPreparationAsync call in the fast path does not forward identityKind or identityKiloUserId. executePreparationSteps (async-preparation.ts:72) gates the user-token attempt on input.identityKiloUserId, so the async preparation always clones the repo using the bot installation token, even when the user has a connected GitHub identity. Subsequent mid-session renewals via refreshGitHubToken are unaffected by this (since identityKiloUserId is stored in DO state after prepare() runs). But the initial clone and commit attribution will use the bot identity for all autoInitiate sessions. The synchronous path at lines 694–695 correctly passes these fields — the fast path needs the same treatment.

Files Reviewed

New in this round (incremental diff):

• services/cloud-agent-next/src/persistence/CloudAgentSession.ts — stale-token fallback fixed ✅
• services/git-token-service/src/user-github-token-service.ts — safe getOctokitStatus type guard, no issues

Carried forward from previous reviews (unchanged):

• services/cloud-agent-next/src/router/handlers/session-prepare.ts — 1 issue remaining (outside diff)

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-sonnet-4.6 · 2,250,202 tokens}

[kilo-code-bot]

Review findings — changes required before merge:

1. getUserFromAuth unused import — apps/web/src/app/api/integrations/github/user-connect/callback/route.ts line 3

getUserFromAuth is imported but never called. The user identity comes from the OAuth state payload (decoded.kilo_user_id). Remove this import — it will cause a lint failure.

2. captureMessage unused import — apps/web/src/app/api/integrations/github/user-connect/callback/route.ts line 13

captureMessage is imported alongside captureException but is never called anywhere in the file. Remove it to fix the lint error.

3. Missing eq import — apps/web/src/routers/github-apps-router.test.ts line 114

The disconnectUserIdentity test calls .where(eq(user_github_app_tokens.kilo_user_id, 'user-123')) but eq is never imported. The import block only brings in { beforeEach, describe, expect, test }, { db, cleanupDbForTest }, { githubAppsRouter }, { user_github_app_tokens }, and { encryptWithSymmetricKey }. Add import { eq } from 'drizzle-orm'; — without it the test throws ReferenceError: eq is not defined at runtime.

4. as cast on caught error — services/git-token-service/src/user-github-token-service.ts line 118

const status = (error as { status?: number }).status;

This is a cast on a caught error from Octokit — untrusted external data. The coding standards explicitly prohibit this: "Avoid broad casts that hide real uncertainty, especially on external/untrusted data". Replace with a type guard:

function getOctokitStatus(e: unknown): number | undefined {
  return e != null &&
    typeof e === 'object' &&
    'status' in e &&
    typeof (e as Record<string, unknown>).status === 'number'
    ? (e as { status: number }).status
    : undefined;
}
// ...
const status = getOctokitStatus(error);

---

The rest of the implementation looks correct: the GitIdentity discriminated union, buildGitAuthor, token-selection gate with silent fallback, DO state persistence of identityKind/identityKiloUserId, refreshGitHubToken mid-session helper, and env-var gating are all well-structured and consistent with the spec.

[kilo-code-bot]

Rebased onto current convoy head; dropped the duplicate MVP-2 commits and the WIP eviction-save commit. The squash-merge of #3203 means MVP-2 changes are already present on the base.