expandai 0.0.2 → 0.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "expandai",
 	"type": "module",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"private": false,
 	"description": "Unified CLI and MCP server for ExpandAI",
 	"author": "ExpandAI",
@@ -30,13 +30,13 @@
 			"import": "./build/esm/index.js"
 		},
 		"./*": {
-			"types": "./build/dts/*.d.ts",
+			"types": "./src/*.ts",
 			"import": "./build/esm/*.js"
 		}
 	},
 	"scripts": {
 		"dev": "tsx --watch src/main.ts",
-		"build": "tsc -b tsconfig.build.json && cp -R skills build/skills && cp src/Install/Opencode/expandai-webfetch.js build/esm/Install/Opencode/expandai-webfetch.js && chmod +x build/esm/main.js",
+		"build": "tsc -b tsconfig.build.json && rm -rf build/skills && cp -R skills build/skills && cp src/Install/Opencode/expandai-webfetch.js build/esm/Install/Opencode/expandai-webfetch.js && chmod +x build/esm/main.js",
 		"build:bin": "bun ./scripts/build.ts --single",
 		"build:bin:all": "bun ./scripts/build.ts",
 		"check": "tsc -b tsconfig.json",
@@ -54,7 +54,7 @@
 		"@effect/cli": "0.75.1",
 		"@effect/platform": "0.96.1",
 		"@effect/platform-node": "0.106.0",
-		"@expandai/sdk": "0.17.2",
+		"@expandai/sdk": "0.18.0",
 		"effect": "3.21.2",
 		"open": "^11.0.0",
 		"smol-toml": "^1.6.1"

package/src/ApiClient.ts

@@ -4,10 +4,76 @@ import { fetchObjectModeJson, fetchSnapshotSearch } from '@expandai/sdk/FetchJso
 import * as Generated from '@expandai/sdk/Generated'
 import { decodeError, unexpectedStatus } from '@expandai/sdk/HttpClientHelpers'
 import { Data, DateTime, Duration, Effect, flow, Match, Option, Redacted, Schema } from 'effect'
+import { CLI_AUTHORIZATION_CLIENT_ID } from './Auth/Domain.js'
 import { BrowserOAuthService } from './BrowserOAuth.js'
 import { ConfigManager, OAuthConfig, OAuthTokenExpired } from './Config.js'
 import { CurrentRequestHeaders } from './Mcp/RequestHeaders.js'
 
+export class DeviceAuthorizationCreated extends Schema.Class<DeviceAuthorizationCreated>('DeviceAuthorizationCreated')({
+	deviceCode: Schema.Redacted(Schema.NonEmptyString),
+	userCode: Schema.NonEmptyString,
+	// `Schema.URL` decodes to a `URL`; the wire form stays a string. The CLI
+	// hands this to the user to open, so a malformed `appUrls.app` should fail
+	// here rather than in a browser.
+	verificationUri: Schema.URL,
+	// Whole seconds. A zero or negative `expiresIn` is a window that has already
+	// closed, so it must be positive.
+	expiresIn: Schema.Int.pipe(Schema.positive()),
+	// `interval` is RFC 8628's *minimum* wait between polls, so zero is
+	// meaningful — poll without delay. Only negative is nonsense, and it would
+	// make `nextPollAt` drift backwards forever.
+	interval: Schema.Int.pipe(Schema.nonNegative()),
+}) {}
+
+const ManualAuthorizationTokenResponse = Schema.Struct({
+	access_token: Schema.Redacted(Schema.NonEmptyString),
+	refresh_token: Schema.Redacted(Schema.NonEmptyString),
+	token_type: Schema.NonEmptyString,
+	expires_in: Schema.Number.pipe(Schema.positive()),
+	scope: Schema.optional(Schema.String),
+})
+
+export type ManualAuthorizationTokenResponse = typeof ManualAuthorizationTokenResponse.Type
+
+/**
+ * RFC 8628 §3.5 poll outcomes. These are results, not errors: an agent-driven
+ * CLI returns immediately on every one of them, and only a transport failure
+ * is exceptional.
+ */
+export type DevicePollOutcome =
+	| { readonly _tag: 'Tokens'; readonly token: ManualAuthorizationTokenResponse }
+	| { readonly _tag: 'Pending' }
+	| { readonly _tag: 'SlowDown' }
+	| { readonly _tag: 'Denied' }
+	| { readonly _tag: 'Expired' }
+	| { readonly _tag: 'Invalid' }
+	/**
+	 * The server refused for a reason a fresh code cannot fix — a misconfigured
+	 * client, resource, or scope. Distinct from `Invalid` because the recovery is
+	 * opposite: `Invalid` means start over, this means stop and report. Carries
+	 * the server's own `error` so the message names the actual cause instead of
+	 * guessing.
+	 */
+	| { readonly _tag: 'Refused'; readonly error: string; readonly description?: string }
+
+const ManualAuthorizationOperation = Schema.Literal('create', 'poll')
+
+export class ManualAuthorizationApiError extends Schema.TaggedError<ManualAuthorizationApiError>()(
+	'ManualAuthorizationApiError',
+	{
+		operation: ManualAuthorizationOperation,
+		kind: Schema.Literal('request_failed', 'rejected', 'invalid_response'),
+		status: Schema.optional(Schema.Number),
+		recoverable: Schema.Boolean,
+	},
+) {
+	get message() {
+		return this.kind === 'rejected'
+			? `Manual authorization ${this.operation} was rejected. Restart authorization if the problem persists.`
+			: `Manual authorization ${this.operation} could not be completed safely. Try again.`
+	}
+}
+
 /**
  * Single user-facing error for any failure crossing the API boundary. The
  * generated client raises a half-dozen status-specific tagged classes plus
@@ -56,18 +122,18 @@ function getUnsupportedFields(value: unknown): string[] {
 	return Array.isArray(unsupportedFields) ? unsupportedFields.filter((field) => typeof field === 'string') : []
 }
 
-const formatIssue = Effect.fn('ApiClient.formatIssue')(function* ({ path, message }: Issue) {
+function formatIssue({ path, message }: Issue): string {
 	const prefix = path.map((segment) => (typeof segment === 'object' ? segment.key : String(segment))).join('.')
 	return prefix ? `${prefix}: ${message}` : message
-})
+}
 
-const formatApiFailure = Effect.fn('ApiClient.formatApiFailure')(function* (error: ClientError) {
+function formatApiFailure(error: ClientError): string {
 	switch (getStringField(error, '_tag')) {
 		case 'HttpApiDecodeError': {
 			const issues = getIssueList(error)
-			return yield* issues.length === 0
-				? Effect.succeed(getStringField(error, 'message') ?? 'Invalid request')
-				: Effect.forEach(issues, formatIssue).pipe(Effect.map((parts) => parts.join('; ')))
+			return issues.length === 0
+				? (getStringField(error, 'message') ?? 'Invalid request')
+				: issues.map(formatIssue).join('; ')
 		}
 		case 'AuthFailed':
 			return `Authentication failed (${getStringField(error, 'reason') ?? 'unknown'}). Run \`expandai login\` to re-authenticate.`
@@ -88,14 +154,139 @@ const formatApiFailure = Effect.fn('ApiClient.formatApiFailure')(function* (erro
 		default:
 			return error instanceof Error ? error.message : (getStringField(error, 'message') ?? 'Expand API request failed.')
 	}
-})
+}
 
 const liftApiError = <A, R>(self: Effect.Effect<A, ClientError, R>) =>
-	self.pipe(
-		Effect.catchAll((error) =>
-			formatApiFailure(error).pipe(Effect.flatMap((detail) => Effect.fail(new ApiRequestFailed({ detail })))),
-		),
-	)
+	self.pipe(Effect.catchAll((error) => new ApiRequestFailed({ detail: formatApiFailure(error) })))
+
+/** Public, unauthenticated HTTP boundary for device-flow CLI authorization. */
+export class ManualAuthorizationApiClient extends Effect.Service<ManualAuthorizationApiClient>()(
+	'@expandai/cli/ManualAuthorizationApiClient',
+	{
+		dependencies: [NodeHttpClient.layer, ConfigManager.Default],
+		effect: Effect.gen(function* () {
+			const httpClient = yield* HttpClient.HttpClient
+			const configManager = yield* ConfigManager
+
+			const apiError = (
+				operation: typeof ManualAuthorizationOperation.Type,
+				kind: 'request_failed' | 'rejected' | 'invalid_response',
+				status?: number,
+			) =>
+				new ManualAuthorizationApiError({
+					operation,
+					kind,
+					status,
+					recoverable: kind !== 'invalid_response',
+				})
+
+			const create = Effect.fn('ManualAuthorizationApiClient.create')(function* (input: {
+				readonly harness: 'agent-harnesses'
+				readonly scope: 'project' | 'global'
+				readonly platform: string
+				readonly machineLabel: string
+				readonly cliVersion: string
+			}) {
+				const apiUrl = yield* configManager.getApiUrl()
+				const request = yield* HttpClientRequest.post(new URL('/v1/cli-authorization/device', apiUrl)).pipe(
+					HttpClientRequest.bodyJson(input),
+					Effect.mapError(() => apiError('create', 'request_failed')),
+				)
+				return yield* httpClient.execute(request).pipe(
+					Effect.flatMap((response) =>
+						response.status >= 200 && response.status < 300
+							? HttpClientResponse.schemaBodyJson(DeviceAuthorizationCreated)(response).pipe(
+									Effect.mapError(() => apiError('create', 'invalid_response')),
+								)
+							: Effect.fail(apiError('create', 'rejected', response.status)),
+					),
+					Effect.catchAll((error) =>
+						error instanceof ManualAuthorizationApiError
+							? Effect.fail(error)
+							: Effect.fail(apiError('create', 'request_failed')),
+					),
+				)
+			})
+
+			const PollErrorBody = Schema.Struct({
+				error: Schema.String,
+				error_description: Schema.optional(Schema.String),
+			})
+
+			/**
+			 * RFC 6749/8628 errors that describe the *request* rather than the state
+			 * of this particular code. Re-minting produces a code that fails
+			 * identically, so treating these as "expired" is what turns a
+			 * misconfiguration into an endless approve loop.
+			 */
+			const PERMANENT_REFUSALS = new Set([
+				'invalid_target',
+				'invalid_client',
+				'invalid_scope',
+				'unsupported_grant_type',
+				'unauthorized_client',
+				'invalid_request',
+			])
+
+			/**
+			 * One poll of the OAuth token endpoint (RFC 8628). Form-encoded, and
+			 * always against `/oauth2/token`: `/device/token` is the first-party
+			 * session path and the server rejects our client there by design.
+			 */
+			const poll = Effect.fn('ManualAuthorizationApiClient.poll')(function* (deviceCode: Redacted.Redacted<string>) {
+				const apiUrl = yield* configManager.getApiUrl()
+				const request = HttpClientRequest.post(new URL('/api/auth/oauth2/token', apiUrl)).pipe(
+					HttpClientRequest.bodyUrlParams({
+						grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+						device_code: Redacted.value(deviceCode),
+						client_id: CLI_AUTHORIZATION_CLIENT_ID,
+					}),
+				)
+				return yield* httpClient.execute(request).pipe(
+					Effect.flatMap(
+						Effect.fnUntraced(function* (response) {
+							if (response.status >= 200 && response.status < 300) {
+								const token = yield* HttpClientResponse.schemaBodyJson(ManualAuthorizationTokenResponse)(response).pipe(
+									Effect.mapError(() => apiError('poll', 'invalid_response')),
+								)
+								return { _tag: 'Tokens', token } satisfies DevicePollOutcome
+							}
+							if (response.status >= 500) return yield* apiError('poll', 'rejected', response.status)
+							const body = yield* HttpClientResponse.schemaBodyJson(PollErrorBody)(response).pipe(
+								Effect.mapError(() => apiError('poll', 'invalid_response')),
+							)
+							switch (body.error) {
+								case 'authorization_pending':
+									return { _tag: 'Pending' } satisfies DevicePollOutcome
+								case 'slow_down':
+									return { _tag: 'SlowDown' } satisfies DevicePollOutcome
+								case 'access_denied':
+									return { _tag: 'Denied' } satisfies DevicePollOutcome
+								case 'expired_token':
+									return { _tag: 'Expired' } satisfies DevicePollOutcome
+								default:
+									return PERMANENT_REFUSALS.has(body.error)
+										? ({
+												_tag: 'Refused',
+												error: body.error,
+												...(body.error_description === undefined ? {} : { description: body.error_description }),
+											} satisfies DevicePollOutcome)
+										: ({ _tag: 'Invalid' } satisfies DevicePollOutcome)
+							}
+						}),
+					),
+					Effect.catchAll((error) =>
+						error instanceof ManualAuthorizationApiError
+							? Effect.fail(error)
+							: Effect.fail(apiError('poll', 'request_failed')),
+					),
+				)
+			})
+
+			return { create, poll } as const
+		}),
+	},
+) {}
 
 /**
  * Resolves outgoing API auth per call. When the current request scope carries
@@ -126,13 +317,14 @@ export class ApiClient extends Effect.Service<ApiClient>()('@expandai/cli/ApiCli
 		const refreshOAuthToken = Effect.fn('ApiClient.refreshOAuthToken')(function* ({
 			refreshToken,
 			expiresAt,
+			clientId,
 		}: OAuthAuthMethod) {
 			if (refreshToken === undefined) {
 				return yield* new OAuthTokenExpired({ expiredAt: expiresAt })
 			}
 
 			const now = yield* DateTime.now
-			const token = yield* browserOAuth.refreshToken(Redacted.value(refreshToken))
+			const token = yield* browserOAuth.refreshToken(Redacted.value(refreshToken), clientId)
 			if (token === undefined) {
 				return yield* new OAuthTokenExpired({ expiredAt: expiresAt })
 			}
@@ -143,6 +335,7 @@ export class ApiClient extends Effect.Service<ApiClient>()('@expandai/cli/ApiCli
 					accessToken: Redacted.make(token.access_token),
 					refreshToken: nextRefreshToken,
 					expiresAt: refreshedExpiresAt,
+					clientId,
 				}),
 			})
 

package/src/Auth/Domain.ts

@@ -0,0 +1,63 @@
+import { Schema } from 'effect'
+
+/**
+ * The OAuth client for browser-approved CLI setup. Distinct from the
+ * `expandai-cli` client that `expandai login` uses: that one keeps loopback
+ * redirect URIs and must keep showing a consent screen, because Better Auth
+ * matches loopback URIs without comparing the port.
+ */
+export const CLI_AUTHORIZATION_CLIENT_ID = 'expandai-cli-browser'
+
+export const PendingInitKey = Schema.Struct({
+	apiOrigin: Schema.String,
+	clientId: Schema.Literal(CLI_AUTHORIZATION_CLIENT_ID),
+	harness: Schema.Literal('agent-harnesses'),
+	scope: Schema.Literal('project', 'global'),
+	canonicalScopeRoot: Schema.String,
+})
+
+export type PendingInitKey = typeof PendingInitKey.Type
+
+/**
+ * One pending RFC 8628 device authorization. The `deviceCode` is the whole
+ * credential — better-auth binds it to our client id server-side and it never
+ * leaves this machine — so the record keeps the same 0600/no-symlink storage
+ * discipline the PKCE verifier had.
+ */
+export class PendingInitRecord extends Schema.Class<PendingInitRecord>('PendingInitRecord')({
+	key: PendingInitKey,
+	deviceCode: Schema.Redacted(Schema.String),
+	userCode: Schema.String,
+	verificationUri: Schema.String,
+	// RFC 8628 §3.5: current polling interval in seconds. `slow_down` adds five,
+	// permanently, so the backoff has to be persisted — each `init` invocation
+	// polls at most once and exits.
+	intervalSeconds: Schema.Number,
+	// Earliest wall-clock time the next poll may hit the network. An agent
+	// re-running `init` faster than the interval gets a local "still pending"
+	// instead of a request the server would answer with `slow_down`.
+	nextPollAt: Schema.DateTimeUtc,
+	approvalExpiresAt: Schema.DateTimeUtc,
+}) {}
+
+export class PendingInitCorrupt extends Schema.TaggedError<PendingInitCorrupt>()('PendingInitCorrupt', {
+	path: Schema.String,
+	error: Schema.Defect,
+}) {
+	readonly recoverable = true
+
+	get message() {
+		return `Pending authorization state at ${this.path} is corrupt and was left unchanged.`
+	}
+}
+
+export class PendingInitStorageError extends Schema.TaggedError<PendingInitStorageError>()('PendingInitStorageError', {
+	path: Schema.String,
+	error: Schema.Defect,
+}) {
+	readonly recoverable = true
+
+	get message() {
+		return `Could not access pending authorization state at ${this.path}.`
+	}
+}

package/src/Auth/ManualAuthorization.ts

@@ -0,0 +1,296 @@
+import { DateTime, Duration, Effect, Either, Option, Schema } from 'effect'
+import { ManualAuthorizationApiClient, ManualAuthorizationApiError } from '../ApiClient.js'
+import { ConfigManager, OAuthConfig } from '../Config.js'
+import { InitScope } from '../Init/Domain.js'
+import { CLI_VERSION } from '../Version.js'
+import { CLI_AUTHORIZATION_CLIENT_ID, type PendingInitKey, PendingInitRecord } from './Domain.js'
+import { PendingInitStore } from './PendingInit.js'
+
+export {
+	ALREADY_AUTHENTICATED_MESSAGE,
+	AUTHORIZATION_CONSUMED_MESSAGE,
+	AUTHORIZATION_REQUIRED_MESSAGE,
+} from '../Init/Domain.js'
+
+const CLIENT_ID = CLI_AUTHORIZATION_CLIENT_ID
+
+/** RFC 8628 §3.5: `slow_down` permanently adds five seconds to the interval. */
+const SLOW_DOWN_INCREMENT_SECONDS = 5
+
+export class ManualAuthorizationInput extends Schema.Class<ManualAuthorizationInput>('ManualAuthorizationInput')({
+	harness: Schema.Literal('agent-harnesses'),
+	scope: InitScope,
+	cwd: Schema.optional(Schema.String),
+	platform: Schema.optional(Schema.String),
+}) {}
+
+/** What the agent relays: where to approve, and the code to type there. */
+export class ManualAuthorizationRequired extends Schema.Class<ManualAuthorizationRequired>(
+	'ManualAuthorizationRequired',
+)({
+	verificationUri: Schema.String,
+	userCode: Schema.NonEmptyString,
+	approvalExpiresAt: Schema.DateTimeUtc,
+}) {}
+
+/**
+ * One `advance` call moves the flow as far as it can without blocking, then
+ * returns. RFC 8628's polling loop is inverted: the agent re-invokes the CLI,
+ * and each invocation polls the token endpoint at most once — or not at all,
+ * when the persisted interval says the server would answer `slow_down`.
+ */
+export class TokensSaved extends Schema.TaggedClass<TokensSaved>()('TokensSaved', {}) {}
+
+export class AuthorizationPending extends Schema.TaggedClass<AuthorizationPending>()('AuthorizationPending', {
+	pending: ManualAuthorizationRequired,
+}) {}
+
+export const ManualAuthorizationOutcome = Schema.Union(TokensSaved, AuthorizationPending)
+export type ManualAuthorizationOutcome = typeof ManualAuthorizationOutcome.Type
+
+export class ManualAuthorizationDenied extends Schema.TaggedError<ManualAuthorizationDenied>()(
+	'ManualAuthorizationDenied',
+	{
+		recoverable: Schema.Literal(true),
+	},
+) {
+	get message() {
+		return 'The authorization request was denied in the browser. Run the same command again to start a new one.'
+	}
+}
+
+/**
+ * The server refused redemption for a reason a fresh code cannot fix. Kept
+ * separate from every other failure because the correct response is the
+ * opposite of the usual one: do not start over, stop and report. Re-minting
+ * here is what produced an endless approve loop — each new code is approved by
+ * the user and then refused identically, with nothing surfaced.
+ */
+export class ManualAuthorizationRefused extends Schema.TaggedError<ManualAuthorizationRefused>()(
+	'ManualAuthorizationRefused',
+	{
+		error: Schema.String,
+		description: Schema.optional(Schema.String),
+		recoverable: Schema.Literal(false),
+	},
+) {
+	get message() {
+		const detail = this.description === undefined ? '' : ` — ${this.description}`
+		return `Expand refused to complete this authorization: ${this.error}${detail}. This is a server-side configuration problem, not something a new code can fix. Do not start setup again; report this error.`
+	}
+}
+
+export class ManualAuthorizationCredentialSaveFailed extends Schema.TaggedError<ManualAuthorizationCredentialSaveFailed>()(
+	'ManualAuthorizationCredentialSaveFailed',
+	{
+		recoverable: Schema.Literal(false),
+	},
+) {
+	get message() {
+		return 'Authorization succeeded, but credentials could not be saved. Start authorization again.'
+	}
+}
+
+function platformName(input: ManualAuthorizationInput): string {
+	return input.platform ?? process.platform
+}
+
+function required(record: PendingInitRecord): ManualAuthorizationRequired {
+	return new ManualAuthorizationRequired({
+		verificationUri: record.verificationUri,
+		userCode: record.userCode,
+		approvalExpiresAt: record.approvalExpiresAt,
+	})
+}
+
+export class ManualAuthorization extends Effect.Service<ManualAuthorization>()(
+	'@expandai/cli/Auth/ManualAuthorization',
+	{
+		dependencies: [ConfigManager.Default, PendingInitStore.Default, ManualAuthorizationApiClient.Default],
+		effect: Effect.gen(function* () {
+			const configManager = yield* ConfigManager
+			const pendingStore = yield* PendingInitStore
+			const apiClient = yield* ManualAuthorizationApiClient
+
+			const preflight = Effect.fnUntraced(function* (input: ManualAuthorizationInput) {
+				yield* configManager.ensureSecureStorage()
+				yield* pendingStore.pruneExpired()
+				const apiUrl = yield* configManager.getApiUrl()
+				const canonicalScopeRoot = yield* pendingStore.canonicalScopeRoot(input.scope, input.cwd)
+				const key: PendingInitKey = {
+					apiOrigin: apiUrl.origin,
+					clientId: CLIENT_ID,
+					harness: input.harness,
+					scope: input.scope,
+					canonicalScopeRoot,
+				}
+				return key
+			})
+
+			const create = Effect.fnUntraced(function* (input: ManualAuthorizationInput, key: PendingInitKey) {
+				const created = yield* apiClient.create({
+					harness: input.harness,
+					scope: input.scope,
+					platform: platformName(input),
+					machineLabel: `${platformName(input)}-${process.arch}`,
+					cliVersion: CLI_VERSION,
+				})
+				const now = yield* DateTime.now
+				const record = new PendingInitRecord({
+					key,
+					deviceCode: created.deviceCode,
+					userCode: created.userCode,
+					// The stored record is JSON on disk, so the decoded `URL` goes back to
+					// its string form here rather than at the schema boundary.
+					verificationUri: created.verificationUri.toString(),
+					intervalSeconds: created.interval,
+					nextPollAt: DateTime.addDuration(now, Duration.seconds(created.interval)),
+					approvalExpiresAt: DateTime.addDuration(now, Duration.seconds(created.expiresIn)),
+				})
+				const stored = yield* Effect.either(pendingStore.putIfAbsent(record))
+				if (Either.isLeft(stored)) return yield* stored.left
+				// A concurrent process may have won the write; its record is the live one.
+				return stored.right
+			})
+
+			const saveTokens = Effect.fnUntraced(function* (token: {
+				readonly access_token: Parameters<typeof OAuthConfig.make>[0]['accessToken']
+				readonly refresh_token: Parameters<typeof OAuthConfig.make>[0]['refreshToken']
+				readonly expires_in: number
+			}) {
+				const now = yield* DateTime.now
+				const saved = yield* Effect.either(
+					configManager.updateConfig({
+						authMethod: OAuthConfig.make({
+							accessToken: token.access_token,
+							refreshToken: token.refresh_token,
+							expiresAt: DateTime.addDuration(now, Duration.seconds(token.expires_in)),
+							clientId: CLIENT_ID,
+						}),
+					}),
+				)
+				if (Either.isLeft(saved)) {
+					return yield* new ManualAuthorizationCredentialSaveFailed({ recoverable: false })
+				}
+			})
+
+			const updateAfterPoll = Effect.fnUntraced(function* (record: PendingInitRecord, slowDown: boolean) {
+				const now = yield* DateTime.now
+				const intervalSeconds = record.intervalSeconds + (slowDown ? SLOW_DOWN_INCREMENT_SECONDS : 0)
+				const next = new PendingInitRecord({
+					...record,
+					intervalSeconds,
+					nextPollAt: DateTime.addDuration(now, Duration.seconds(intervalSeconds)),
+				})
+				// One atomic publish, not delete-then-create: an interrupt between those
+				// two lost the device code entirely, and this runs on every poll.
+				const replaced = yield* Effect.either(pendingStore.replaceIfMatch(record, next))
+				if (Either.isLeft(replaced)) return record
+				return replaced.right ? next : record
+			})
+
+			const advance = Effect.fn('ManualAuthorization.advance')(function* (input: ManualAuthorizationInput) {
+				const key = yield* preflight(input)
+				const existing = yield* pendingStore.get(key)
+				if (Option.isNone(existing)) {
+					const record = yield* create(input, key)
+					return new AuthorizationPending({ pending: required(record) })
+				}
+				const record = existing.value
+				const now = yield* DateTime.now
+
+				if (DateTime.greaterThan(now, record.approvalExpiresAt)) {
+					// Expired locally: start over transparently. The user sees a fresh
+					// code, not an error about a code they never got to use.
+					yield* pendingStore.removeIfMatch(record)
+					const fresh = yield* create(input, key)
+					return new AuthorizationPending({ pending: required(fresh) })
+				}
+
+				if (DateTime.lessThan(now, record.nextPollAt)) {
+					// Inside the polling interval — answering locally is what keeps an
+					// eagerly re-running agent from earning `slow_down` penalties.
+					return new AuthorizationPending({ pending: required(record) })
+				}
+
+				const outcome = yield* apiClient.poll(record.deviceCode)
+				switch (outcome._tag) {
+					case 'Tokens': {
+						yield* saveTokens(outcome.token)
+						yield* pendingStore.removeIfMatch(record)
+						return new TokensSaved()
+					}
+					case 'Pending': {
+						const next = yield* updateAfterPoll(record, false)
+						return new AuthorizationPending({ pending: required(next) })
+					}
+					case 'SlowDown': {
+						const next = yield* updateAfterPoll(record, true)
+						return new AuthorizationPending({ pending: required(next) })
+					}
+					case 'Denied': {
+						yield* pendingStore.removeIfMatch(record)
+						return yield* new ManualAuthorizationDenied({ recoverable: true })
+					}
+					case 'Refused': {
+						// Deliberately keeps the pending record. Discarding it would mint a
+						// fresh code on the next run, which the server refuses identically —
+						// so the user approves again, and again. Holding the record means a
+						// re-run reports the same error instead of asking for more approvals.
+						return yield* new ManualAuthorizationRefused({
+							error: outcome.error,
+							...(outcome.description === undefined ? {} : { description: outcome.description }),
+							recoverable: false,
+						})
+					}
+					case 'Expired':
+					case 'Invalid': {
+						// The server no longer honours this code — expired, already consumed
+						// by a response we never received, or unknown. All three recover the
+						// same way: a fresh request and a fresh approval.
+						yield* pendingStore.removeIfMatch(record)
+						const fresh = yield* create(input, key)
+						return new AuthorizationPending({ pending: required(fresh) })
+					}
+				}
+			})
+
+			/**
+			 * Redeems a device code that arrived out of band — the dashboard's
+			 * pre-approved setup token. No pending record is kept: the code is
+			 * single-use and either redeems on this first poll or never will.
+			 */
+			const redeemPreApproved = Effect.fn('ManualAuthorization.redeemPreApproved')(function* (
+				deviceCode: Parameters<typeof apiClient.poll>[0],
+			) {
+				const outcome = yield* apiClient.poll(deviceCode)
+				switch (outcome._tag) {
+					case 'Tokens':
+						return yield* saveTokens(outcome.token)
+					case 'Denied':
+						return yield* new ManualAuthorizationDenied({ recoverable: true })
+					case 'Refused':
+						return yield* new ManualAuthorizationRefused({
+							error: outcome.error,
+							...(outcome.description === undefined ? {} : { description: outcome.description }),
+							recoverable: false,
+						})
+					case 'Pending':
+					case 'SlowDown':
+					case 'Expired':
+					case 'Invalid':
+						// A dashboard token is minted approved; anything else means it was
+						// not produced by that flow, expired, or is already spent.
+						return yield* new ManualAuthorizationApiError({
+							operation: 'poll',
+							kind: 'rejected',
+							status: 400,
+							recoverable: false,
+						})
+				}
+			})
+
+			return { advance, redeemPreApproved } as const
+		}),
+	},
+) {}