expandai 0.0.2 → 0.0.3

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
+		}),
+	},
+) {}

package/src/Auth/PendingInit.ts

@@ -0,0 +1,338 @@
+import { createHash } from 'node:crypto'
+import { FileSystem, Path, Error as PlatformError } from '@effect/platform'
+import { NodeContext } from '@effect/platform-node'
+import { DateTime, Effect, Either, Option, Schema } from 'effect'
+import { xdgConfigDirectory } from '../Xdg.js'
+import {
+	CLI_AUTHORIZATION_CLIENT_ID,
+	PendingInitCorrupt,
+	type PendingInitKey,
+	PendingInitRecord,
+	PendingInitStorageError,
+} from './Domain.js'
+
+const PendingInitRecordJson = Schema.parseJson(PendingInitRecord)
+const COMPLETION_CODE_RETENTION_GRACE_MS = 5 * 60 * 1_000
+
+const PendingInitKeyTupleJson = Schema.parseJson(
+	Schema.Tuple(
+		Schema.String,
+		Schema.Literal(CLI_AUTHORIZATION_CLIENT_ID),
+		Schema.Literal('agent-harnesses'),
+		Schema.Literal('project', 'global'),
+		Schema.String,
+	),
+)
+
+function isErrnoCode(input: unknown, code: string): boolean {
+	return typeof input === 'object' && input !== null && 'code' in input && input.code === code
+}
+
+function isAlreadyExists(error: unknown): boolean {
+	return (
+		error instanceof PlatformError.SystemError &&
+		(error.reason === 'AlreadyExists' || isErrnoCode(error.cause, 'EEXIST'))
+	)
+}
+
+/** Canonical, collision-free serialization of all pending authorization key fields. */
+export function serializePendingInitKey(key: PendingInitKey): string {
+	return Schema.encodeSync(PendingInitKeyTupleJson)([
+		key.apiOrigin,
+		key.clientId,
+		key.harness,
+		key.scope,
+		key.canonicalScopeRoot,
+	])
+}
+
+function ancestorPaths(path: Path.Path, current: string): string[] {
+	const parent = path.dirname(current)
+	return parent === current ? [current] : [current, ...ancestorPaths(path, parent)]
+}
+
+export class PendingInitStore extends Effect.Service<PendingInitStore>()('@expandai/cli/Auth/PendingInitStore', {
+	dependencies: [NodeContext.layer],
+	effect: Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+		const configDirectory = path.join(yield* xdgConfigDirectory, 'expandai')
+		const pendingPath = path.join(configDirectory, 'pending-init')
+
+		const storageError = (targetPath: string, error: unknown) =>
+			new PendingInitStorageError({ path: targetPath, error })
+
+		/**
+		 * Maps a platform failure to the domain error for `targetPath`.
+		 *
+		 * Deliberately applied per call rather than once around each function: a
+		 * blanket `mapError` over a whole `Effect.fn` body would also swallow
+		 * `PendingInitCorrupt`, which `decodeRecord` raises and which `Status.ts`
+		 * reports differently — corrupt state is recoverable by deleting the file,
+		 * a storage failure is not.
+		 */
+		const onStorage = <A>(targetPath: string, effect: Effect.Effect<A, PlatformError.PlatformError>) =>
+			effect.pipe(Effect.mapError((error) => storageError(targetPath, error)))
+
+		const assertNotSymbolicLink = Effect.fnUntraced(function* (targetPath: string) {
+			const result = yield* Effect.either(fileSystem.readLink(targetPath))
+			if (Either.isRight(result)) {
+				return yield* storageError(targetPath, new Error('Symbolic links are not allowed for pending authorization'))
+			}
+			const error = result.left
+			if (
+				error instanceof PlatformError.SystemError &&
+				(error.reason === 'InvalidData' ||
+					error.reason === 'NotFound' ||
+					(error.method === 'readLink' && isErrnoCode(error.cause, 'EINVAL')))
+			) {
+				return
+			}
+			return yield* storageError(targetPath, error)
+		})
+
+		const ensureDirectory = Effect.fnUntraced(function* () {
+			yield* assertNotSymbolicLink(configDirectory)
+			yield* assertNotSymbolicLink(pendingPath)
+			yield* onStorage(pendingPath, fileSystem.makeDirectory(pendingPath, { recursive: true, mode: 0o700 }))
+			yield* assertNotSymbolicLink(configDirectory)
+			yield* assertNotSymbolicLink(pendingPath)
+			const directoryInfo = yield* onStorage(pendingPath, fileSystem.stat(pendingPath))
+			if (directoryInfo.type !== 'Directory') {
+				return yield* storageError(pendingPath, new Error('Pending authorization path is not a directory'))
+			}
+			if (process.platform !== 'win32') {
+				yield* onStorage(configDirectory, fileSystem.chmod(configDirectory, 0o700))
+				yield* onStorage(pendingPath, fileSystem.chmod(pendingPath, 0o700))
+			}
+		})
+
+		const recordPath = (key: PendingInitKey) => {
+			const digest = createHash('sha256').update(serializePendingInitKey(key)).digest('hex')
+			return path.join(pendingPath, `${digest}.json`)
+		}
+
+		const decodeRecord = Effect.fnUntraced(function* (targetPath: string, encoded: string) {
+			const record = yield* Schema.decode(PendingInitRecordJson)(encoded).pipe(
+				Effect.mapError(
+					() =>
+						new PendingInitCorrupt({
+							path: targetPath,
+							error: new Error('Stored pending authorization did not match the expected schema'),
+						}),
+				),
+			)
+			if (recordPath(record.key) !== targetPath) {
+				return yield* new PendingInitCorrupt({
+					path: targetPath,
+					error: new Error('Stored pending authorization key did not match its file'),
+				})
+			}
+			return record
+		})
+
+		const readRecordPath = Effect.fnUntraced(function* (targetPath: string) {
+			yield* assertNotSymbolicLink(targetPath)
+			const exists = yield* onStorage(targetPath, fileSystem.exists(targetPath))
+			if (!exists) return Option.none<PendingInitRecord>()
+			const info = yield* onStorage(targetPath, fileSystem.stat(targetPath))
+			if (info.type !== 'File') return yield* storageError(targetPath, new Error('Pending state is not a regular file'))
+			if (process.platform !== 'win32' && (info.mode & 0o777) !== 0o600) {
+				return yield* storageError(targetPath, new Error('Pending state file mode is not 600'))
+			}
+			const encoded = yield* onStorage(targetPath, fileSystem.readFileString(targetPath))
+			return Option.some(yield* decodeRecord(targetPath, encoded))
+		})
+
+		const readRecord = (key: PendingInitKey) => readRecordPath(recordPath(key))
+
+		const isExpired = Effect.fnUntraced(function* (record: PendingInitRecord) {
+			const now = DateTime.toEpochMillis(yield* DateTime.now)
+			return DateTime.toEpochMillis(record.approvalExpiresAt) + COMPLETION_CODE_RETENTION_GRACE_MS <= now
+		})
+
+		const writeExclusive = Effect.fnUntraced(function* (record: PendingInitRecord) {
+			yield* ensureDirectory()
+			const targetPath = recordPath(record.key)
+			const encoded = yield* Schema.encode(PendingInitRecordJson)(record).pipe(
+				Effect.mapError((error) => storageError(targetPath, error)),
+			)
+			const created = yield* Effect.either(
+				Effect.scoped(
+					Effect.gen(function* () {
+						const file = yield* fileSystem.open(targetPath, { flag: 'wx', mode: 0o600 })
+						yield* file.writeAll(new TextEncoder().encode(encoded))
+						yield* file.sync
+					}),
+				),
+			)
+			if (Either.isLeft(created)) {
+				// `wx` means an existing file belongs to another attempt — leave it.
+				if (isAlreadyExists(created.left)) return false
+				// Anything else failed *after* we created the file, so a zero-byte or
+				// half-written record is now sitting at the final path. Left there it
+				// fails every later read of this key, and interrupting between `open`
+				// and `writeAll` is enough to cause it.
+				yield* fileSystem.remove(targetPath).pipe(Effect.ignore)
+				return yield* storageError(targetPath, created.left)
+			}
+			if (process.platform !== 'win32') {
+				const chmodResult = yield* Effect.either(fileSystem.chmod(targetPath, 0o600))
+				if (Either.isLeft(chmodResult)) {
+					yield* fileSystem.remove(targetPath).pipe(Effect.ignore)
+					return yield* storageError(targetPath, chmodResult.left)
+				}
+			}
+			return true
+		})
+
+		/**
+		 * Publishes `next` over the record for the same key, atomically.
+		 *
+		 * The caller used to do `removeIfMatch` then `putIfAbsent`. An interrupt
+		 * between those two — Ctrl-C during the poll that runs on *every* `expandai
+		 * init` while authorization is pending — deleted the pending record and
+		 * wrote nothing back, so the next run minted a fresh code and asked the user
+		 * to approve again with no error to explain it.
+		 *
+		 * `rename` over the target is atomic on POSIX, so an interrupt either leaves
+		 * the old record or completes the new one. It is **not** a cross-process
+		 * compare-and-swap: another process can publish between our read and our
+		 * rename, and ours wins. That race is pre-existing and unaddressed here —
+		 * closing it needs a per-key lock, and Windows replacement semantics need
+		 * checking first. The name says `IfMatch` because it verifies before
+		 * writing, not because it is a CAS.
+		 */
+		const replaceIfMatch = Effect.fn('PendingInitStore.replaceIfMatch')(function* (
+			previous: PendingInitRecord,
+			next: PendingInitRecord,
+		) {
+			yield* ensureDirectory()
+			const targetPath = recordPath(next.key)
+			if (recordPath(previous.key) !== targetPath) {
+				return yield* storageError(targetPath, new Error('Pending authorization replacement changed its key'))
+			}
+			const current = yield* readRecordPath(targetPath)
+			if (Option.isNone(current) || current.value.userCode !== previous.userCode) return false
+
+			const encoded = yield* Schema.encode(PendingInitRecordJson)(next).pipe(
+				Effect.mapError((error) => storageError(targetPath, error)),
+			)
+			// Same directory, so `rename` stays on one filesystem and is atomic.
+			//
+			// `acquireRelease` rather than manual cleanup on the typed-failure branches:
+			// a defect or an interrupt bypasses those branches entirely, and an
+			// abandoned `.tmp` is worse than it looks — it is a second copy of a live
+			// credential, `pruneExpired` only scans `.json` records so it never reaps
+			// one, and a fixed name made the next attempt fail on its own leftovers.
+			const staging = `${targetPath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`
+			const published = yield* Effect.scoped(
+				Effect.acquireRelease(Effect.succeed(staging), () => fileSystem.remove(staging).pipe(Effect.ignore)).pipe(
+					Effect.zipRight(
+						Effect.gen(function* () {
+							yield* assertNotSymbolicLink(staging)
+							yield* Effect.scoped(
+								Effect.gen(function* () {
+									const file = yield* fileSystem.open(staging, { flag: 'wx', mode: 0o600 })
+									yield* file.writeAll(new TextEncoder().encode(encoded))
+									yield* file.sync
+								}),
+							)
+							yield* fileSystem.rename(staging, targetPath)
+						}),
+					),
+				),
+			).pipe(Effect.either)
+			if (Either.isLeft(published)) return yield* storageError(targetPath, published.left)
+			return true
+		})
+
+		const removeIfCurrent = Effect.fnUntraced(function* (record: PendingInitRecord) {
+			const targetPath = recordPath(record.key)
+			const current = yield* readRecordPath(targetPath)
+			if (Option.isNone(current) || current.value.userCode !== record.userCode) return false
+			yield* onStorage(targetPath, fileSystem.remove(targetPath))
+			return true
+		})
+
+		const get = Effect.fn('PendingInitStore.get')(function* (key: PendingInitKey) {
+			const record = yield* readRecord(key)
+			if (Option.isNone(record) || !(yield* isExpired(record.value))) return record
+			yield* removeIfCurrent(record.value)
+			return Option.none<PendingInitRecord>()
+		})
+
+		const peek = Effect.fn('PendingInitStore.peek')(function* (key: PendingInitKey) {
+			return yield* readRecord(key)
+		})
+
+		const putIfAbsent = Effect.fn('PendingInitStore.putIfAbsent')(function* (record: PendingInitRecord) {
+			const existing = yield* readRecord(record.key)
+			if (Option.isSome(existing) && !(yield* isExpired(existing.value))) return existing.value
+			if (Option.isSome(existing)) yield* removeIfCurrent(existing.value)
+			if (yield* writeExclusive(record)) return record
+			const winner = yield* readRecord(record.key)
+			return yield* Option.match(winner, {
+				onNone: () => storageError(recordPath(record.key), new Error('Pending record creation lost without a winner')),
+				onSome: Effect.succeed,
+			})
+		})
+
+		const removeIfMatch = Effect.fn('PendingInitStore.removeIfMatch')((record: PendingInitRecord) =>
+			removeIfCurrent(record),
+		)
+
+		const pruneExpired = Effect.fn('PendingInitStore.pruneExpired')(function* () {
+			yield* assertNotSymbolicLink(pendingPath)
+			const exists = yield* onStorage(pendingPath, fileSystem.exists(pendingPath))
+			if (!exists) {
+				return 0
+			}
+			const entries = yield* onStorage(pendingPath, fileSystem.readDirectory(pendingPath))
+			const removed = yield* Effect.forEach(
+				entries.filter((entry) => entry.endsWith('.json')),
+				(entry) =>
+					Effect.gen(function* () {
+						const record = yield* readRecordPath(path.join(pendingPath, entry))
+						if (Option.isNone(record) || !(yield* isExpired(record.value))) {
+							return 0
+						}
+						return (yield* removeIfCurrent(record.value)) ? 1 : 0
+						// One unreadable entry must not fail the sweep. Pruning runs
+						// on every begin, resume and refreshStatus, so a single
+						// corrupt or newer-format file would otherwise block all
+						// three — including the resume that would have recovered.
+					}).pipe(Effect.orElseSucceed(() => 0)),
+			)
+			return removed.reduce<number>((total, count) => total + count, 0)
+		})
+
+		const canonicalScopeRoot = Effect.fn('PendingInitStore.canonicalScopeRoot')(function* (
+			scope: PendingInitKey['scope'],
+			cwd = process.cwd(),
+		) {
+			if (scope === 'global') return 'global'
+			const canonicalCwd = yield* onStorage(cwd, fileSystem.realPath(cwd))
+			const inspected = yield* Effect.forEach(ancestorPaths(path, canonicalCwd), (candidate) =>
+				onStorage(candidate, fileSystem.exists(path.join(candidate, '.git'))).pipe(
+					Effect.map((exists) => ({ candidate, exists })),
+				),
+			)
+			const repositoryRoot = inspected.find(({ exists }) => exists)?.candidate
+			return repositoryRoot === undefined
+				? canonicalCwd
+				: yield* onStorage(repositoryRoot, fileSystem.realPath(repositoryRoot))
+		})
+
+		return {
+			pendingPath,
+			get,
+			peek,
+			putIfAbsent,
+			replaceIfMatch,
+			removeIfMatch,
+			pruneExpired,
+			canonicalScopeRoot,
+		} as const
+	}),
+}) {}