headlesscode 1.0.2

package/src/engine/types.ts

@@ -0,0 +1,291 @@
+/**
+ * Shared types for the headless harness engine.
+ *
+ * These are deliberately minimal, local interfaces for the OpenAI-compatible
+ * chat message shapes used by OpenRouter. We do NOT pull in the `openai` SDK —
+ * the vendored Zoo Code core already provides its own type-only shim for the
+ * tool schemas (see `src/vendor/zoo-code/shim/openai.d.ts`), and the harness
+ * only needs the handful of message shapes below to talk to a chat-completions
+ * endpoint.
+ */
+
+import type { PermissionsConfig } from "../permissions/config.js"
+
+export type ChatRole = "system" | "user" | "assistant" | "tool"
+
+/** A single OpenAI-style function call emitted by the model. */
+export interface ChatToolCall {
+	id: string
+	type: "function"
+	function: {
+		name: string
+		arguments: string
+	}
+}
+
+/** A chat message in OpenAI/OpenRouter chat-completions format. */
+export interface ChatMessage {
+	role: ChatRole
+	content: string | null
+	tool_calls?: ChatToolCall[]
+	/** Present on `role: "tool"` messages, links back to the assistant call. */
+	tool_call_id?: string
+	/** Present on `role: "tool"` messages. */
+	name?: string
+	/**
+	 * The model's reasoning/"thinking" text for this assistant message
+	 * (streaming-and-reasoning). OpenRouter normalizes DeepSeek's
+	 * `reasoning_content` to `reasoning` on the response message; we echo it
+	 * back onto outgoing assistant history the same way. Optional — absent
+	 * for models/calls that don't produce reasoning content.
+	 */
+	reasoning?: string
+}
+
+/** An OpenAI-format ChatCompletionTool (function schema). */
+export interface ChatTool {
+	type: "function"
+	function: {
+		name: string
+		description?: string
+		strict?: boolean | null
+		parameters?: Record<string, unknown>
+		[key: string]: unknown
+	}
+	[key: string]: unknown
+}
+
+/** Request shape accepted by an LlmClient. */
+export interface LlmRequest {
+	model: string
+	messages: ChatMessage[]
+	tools?: ChatTool[]
+	temperature?: number
+	maxTokens?: number
+	signal?: AbortSignal
+	/**
+	 * Opt-in SSE streaming (streaming-and-reasoning). When true the client
+	 * streams deltas and assembles the final message from the stream instead
+	 * of one blocking fetch. Default OFF — existing callers/tests are
+	 * unaffected.
+	 */
+	stream?: boolean
+	/**
+	 * Streaming-and-reasoning: invoked for each incremental chunk as a streamed
+	 * response arrives (kind "text" | "reasoning" | "tool"). Only called when
+	 * `stream` is true and the client actually streams; the loop uses it to emit
+	 * `llm_stream_chunk` events for the dashboard's live-typing view. Non-fatal
+	 * by contract: a throw from this callback must not fail the LLM call.
+	 */
+	onStreamChunk?: (kind: "text" | "reasoning" | "tool", chunk: string) => void
+	/**
+	 * Graded reasoning effort for models that support it (the pinned DeepSeek
+	 * family — issue #30 experiment). User-facing vocabulary is DeepSeek's
+	 * native set low/medium/high/max, plus OpenRouter's normalized "xhigh"
+	 * (an alias for the native max); the client normalizes to OpenRouter's
+	 * `reasoning: { effort }` field on the wire. Optional — when unset, no
+	 * effort field is sent and the endpoint's own undeclared default applies
+	 * (pre-existing behavior, unchanged).
+	 */
+	reasoningEffort?: string
+	/**
+	 * Sampling-level override for llama.cpp's `repeat_penalty`, applied for
+	 * exactly one request. The loop sets this once its identical-consecutive-
+	 * call guardrail (see DEFAULT_IDENTICAL_CALL_NUDGE_THRESHOLD in
+	 * src/engine/loop.ts) detects a repeat starting, as an alternative to a
+	 * text-only nudge — three rounds of increasingly specific injected
+	 * corrections were verified live not to reliably interrupt a local model
+	 * mid-repetition (2026-08-21/22), so this escalates at the sampler
+	 * instead of only in the prompt. Ignored by clients/backends that don't
+	 * support per-request sampling overrides (e.g. OpenRouter).
+	 */
+	repeatPenalty?: number
+	/**
+	 * Forces the model to call SOME tool rather than allowing a free
+	 * text/empty response — the OpenAI-style `"required"` value (also
+	 * `"none"`/`"auto"`). Verified live 2026-08-20: once the identical-call
+	 * guard's tool exclusion removes a strongly-preferred tool from the
+	 * schema, the model doesn't substitute a different tool call — it
+	 * produces a genuinely EMPTY (zero-token) generation instead, 100% of
+	 * the time (148/148 in one trial), consistent with the default
+	 * `tool_choice: "auto"` leaving a free-text/empty branch available for
+	 * the grammar-constrained decoder to collapse into once its preferred
+	 * path is removed. `"required"` closes that branch. Ignored by
+	 * clients/backends that don't support it.
+	 */
+	toolChoice?: "auto" | "none" | "required"
+}
+
+/** Response shape returned by an LlmClient. */
+export interface LlmResponse {
+	message: ChatMessage
+	usage?: {
+		promptTokens?: number
+		completionTokens?: number
+		totalTokens?: number
+		/**
+		 * Prompt tokens served from the provider's prefix cache (a subset of
+		 * promptTokens, not additional) — OpenRouter surfaces this as
+		 * `usage.prompt_tokens_details.cached_tokens` when the underlying
+		 * provider (e.g. DeepSeek) supports automatic prompt caching. Cached
+		 * tokens are billed at a steep discount; see src/budget/cost.ts.
+		 */
+		cachedTokens?: number
+	}
+}
+
+/**
+ * The LLM client contract the orchestration loop depends on.
+ *
+ * The loop must NOT hardcode OpenRouter: tests inject a fake client that
+ * implements this interface, so the loop is fully unit-testable without a
+ * network or API key.
+ */
+export interface LlmClient {
+	createChatCompletion(request: LlmRequest): Promise<LlmResponse>
+}
+
+/** Result of executing one tool call. */
+export interface ToolResult {
+	content: string
+	isError: boolean
+}
+
+/**
+ * Usage of one LLM call made OUTSIDE the main loop's request path — e.g. the
+ * cloud vision captioning in src/vision/describe.ts (browser screenshots and
+ * the `describe_image` tool). Auxiliary calls are recorded into the SAME
+ * BudgetTracker + running session totals as a main call (see
+ * recordAuxLlmUsage in src/engine/loop.ts), so their real token/cost shows up
+ * in the session's budget/usage accounting instead of being an untracked side
+ * channel. Shape mirrors the token counts of LlmResponse.usage.
+ */
+export interface AuxLlmUsage {
+	/** The model id the auxiliary call actually ran (echoed by the provider). */
+	model: string
+	inputTokens: number
+	outputTokens: number
+	/** Subset of inputTokens served from the provider's prompt cache. */
+	cachedTokens?: number
+}
+
+/** Per-call context handed to tool handlers. */
+export interface ToolContext {
+	workspaceRoot: string
+	/**
+	 * Resolved command allow/deny + protected-file permissions for this
+	 * executor/session (see src/permissions/). Always present — the executor
+	 * resolves built-in defaults when nothing is configured — so handlers can
+	 * enforce command gating (execute_command) and protected-file refusals
+	 * (write_to_file) without guessing.
+	 */
+	permissions: PermissionsConfig
+	/**
+	 * See HeadlessSessionConfig.guardLargeOverwrites (loop.ts) for the full
+	 * writeup. When true, `write_to_file` refuses to overwrite an existing
+	 * file that already has substantial content (see the guard in
+	 * `writeToFileHandler`, src/tools/executor.ts) — creating a brand-new
+	 * file is never affected. Absent/false for cloud sessions and bare
+	 * executors (tests, reviewer/QA).
+	 */
+	guardLargeOverwrites?: boolean
+	/**
+	 * Decision escalation (ask_followup_question, see src/tools/executor.ts):
+	 * how long to block waiting for `.harness.decision-answer` before falling
+	 * back to today's autonomous-decision error, and how often to poll for it.
+	 * Both optional — handlers fall back to their own defaults when absent.
+	 */
+	decisionTimeoutMs?: number
+	decisionPollIntervalMs?: number
+	/**
+	 * Budget-clock pause/resume hooks, wired by HeadlessSession right after it
+	 * constructs a BudgetTracker (see src/budget/budget.ts's pauseClock /
+	 * resumeClock). ask_followup_question calls these around its blocking wait
+	 * so time spent waiting on a human/orchestrator answer isn't charged
+	 * against the session's duration budget. Absent when no budget is
+	 * configured, or when the injected executor never wired them.
+	 */
+	pauseBudgetClock?: () => void
+	resumeBudgetClock?: () => void
+	/**
+	 * Live worker monitoring: fired at the same lifecycle points where the
+	 * `.harness.needs-decision` marker is written/cleared (see the
+	 * ask_followup_question handler in src/tools/executor.ts), so the session
+	 * can mirror those transitions on its structured event feed
+	 * (`decision_blocked` / `decision_answered`). Absent when no hook was
+	 * wired (plain executor use, tests without a session).
+	 */
+	onDecisionEvent?: (eventType: "decision_blocked" | "decision_answered", fields: Record<string, unknown>) => void
+	/**
+	 * Live todo-list monitoring: fired each time update_todo_list replaces the
+	 * session's checklist (see the handler in src/tools/executor.ts), carrying
+	 * the full normalized checklist plus done/in-progress/pending counts, so
+	 * the session can mirror it on its structured event feed (`todo_updated`).
+	 * Absent when no hook was wired (plain executor use, tests without a
+	 * session).
+	 */
+	onTodoEvent?: (fields: { todos: string; done: number; inProgress: number; pending: number }) => void
+	/**
+	 * Auxiliary LLM usage reporting (cloud vision captioning — see
+	 * src/vision/describe.ts): fired after every LLM call made outside the
+	 * main loop's request path, so the session can record its tokens/cost into
+	 * the same BudgetTracker + totals as a main call (see recordAuxLlmUsage in
+	 * src/engine/loop.ts). Absent when no hook was wired — plain executor use,
+	 * tests without a session. Its presence also gates the screenshot action's
+	 * auto-describe behavior (browser_action only captions screenshots when
+	 * attached to a real accounting session; bare executors skip the call and
+	 * the model can still use `describe_image` explicitly).
+	 */
+	onAuxLlmUsage?: (usage: AuxLlmUsage) => void
+}
+
+/** A tool handler: dispatch any registered tool by name. */
+export type ToolHandler = (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult> | ToolResult
+
+/** Parsed result of one assistant tool call. */
+export interface ParsedToolCall {
+	id: string
+	name: string
+	args: Record<string, unknown>
+	rawArguments: string
+	/** Set when JSON.parse failed and best-effort extraction also failed. */
+	parseError?: string
+}
+
+export type SessionStatus = "success" | "error"
+
+/**
+ * Phase 6 — budget accounting surfaced on every SessionResult when a
+ * per-session budget is configured (null budget → absent → zero change).
+ */
+export interface SessionBudgetUsage {
+	/** Estimated USD spend (tokens × pricing) accumulated across LLM calls. */
+	costUsd: number
+	/** Wall-clock elapsed since the session's budget tracker started, ms. */
+	elapsedMs: number
+	/** Number of LLM calls (ticks) performed. */
+	iterations: number
+	/** Model id the session ran with. */
+	model: string
+}
+
+export interface SessionResult {
+	status: SessionStatus
+	result?: string
+	error?: string
+	/** Machine-readable failure reason (e.g. "budget") for callers/CLI. */
+	reason?: string
+	iterations: number
+	toolCalls: number
+	/**
+	 * Issue #34: absolute path to the session's complete final report
+	 * (`<workspaceRoot>/.headlesscode/reports/<sessionId>.md`), present when
+	 * the session ended successfully (attempt_completion or the text-only
+	 * fallback) and the report write succeeded. Callers (runQa/runReview →
+	 * orchestrator state) persist this so the full reasoning behind a
+	 * review/QA verdict is one file-read away, not a re-run away.
+	 */
+	reportPath?: string
+	/** Phase 6: present when the session had a budget (see SessionBudgetUsage). */
+	budgetUsage?: SessionBudgetUsage
+}

package/src/engine/usage.ts

@@ -0,0 +1,186 @@
+/**
+ * Cost/token monitoring (workstream 3) — per-session usage persistence.
+ *
+ * Storage layout, one JSONL file per session, append-only, mirroring the
+ * existing project idiom (`src/memory/local.ts`'s `appendJsonl`/`readJsonl`
+ * — plain `node:fs`, no schema library, loose validation on read):
+ *
+ *   <workspaceRoot>/.headlesscode/usage/<sessionId>.jsonl
+ *
+ * A worker process normally writes exactly ONE line here (its single
+ * completed session), but the format is append-only JSONL rather than a
+ * single JSON object so that concurrent/rerun scenarios (e.g. a worktree
+ * reused across multiple sessions) never corrupt a partial write — same
+ * write-contention rationale as the memory store's per-project files.
+ *
+ * This module is intentionally the ONLY place that knows the on-disk usage
+ * layout, so `src/dashboard/aggregate.ts` (read side) and
+ * `src/engine/loop.ts` (write side) stay in sync.
+ */
+
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+/** One completed session's usage, as persisted to `.headlesscode/usage/<sessionId>.jsonl`. */
+export interface UsageRecord {
+	sessionId: string
+	mode: string
+	model: string
+	iterations: number
+	inputTokens: number
+	outputTokens: number
+	/**
+	 * Subset of inputTokens served from the provider's prompt cache (see
+	 * LlmResponse.usage.cachedTokens). Optional: absent on records written
+	 * before this field existed, or when the provider never reports it.
+	 */
+	cachedTokens?: number
+	costUsd: number
+	startedAt: string
+	endedAt: string
+	status: "success" | "error" | "budget"
+	workspaceRoot: string
+}
+
+/**
+ * A live (in-progress) usage snapshot, overwritten in place at
+ * `.headlesscode/usage/<sessionId>.live.json` after every iteration while a
+ * session runs, so the dashboard can show accumulating cost/tokens before the
+ * session finishes. Same shape as `UsageRecord` minus `endedAt`, with
+ * `status: "running"`.
+ */
+export interface LiveUsageRecord {
+	sessionId: string
+	mode: string
+	model: string
+	iterations: number
+	inputTokens: number
+	outputTokens: number
+	cachedTokens?: number
+	costUsd: number
+	startedAt: string
+	status: "running"
+	workspaceRoot: string
+}
+
+/** The usage dir for a workspace: `<workspaceRoot>/.headlesscode/usage`. */
+export function usageDir(workspaceRoot: string): string {
+	return path.join(workspaceRoot, ".headlesscode", "usage")
+}
+
+/** The usage file path for one session. */
+export function usageFilePath(workspaceRoot: string, sessionId: string): string {
+	return path.join(usageDir(workspaceRoot), `${sessionId}.jsonl`)
+}
+
+/** The live (in-progress) usage snapshot path for one session. */
+export function liveUsageFilePath(workspaceRoot: string, sessionId: string): string {
+	return path.join(usageDir(workspaceRoot), `${sessionId}.live.json`)
+}
+
+/**
+ * Append one usage record for a completed session. Creates the usage dir if
+ * needed. Callers (see `HeadlessSession.recordUsage`) are expected to wrap
+ * this in try/catch and treat failures as non-fatal — this function itself
+ * does not swallow errors, so it fails loudly for direct callers/tests.
+ */
+export async function recordSessionUsage(workspaceRoot: string, record: UsageRecord): Promise<void> {
+	const file = usageFilePath(workspaceRoot, record.sessionId)
+	await fsp.mkdir(path.dirname(file), { recursive: true })
+	await fsp.appendFile(file, JSON.stringify(record) + "\n", "utf-8")
+}
+
+/**
+ * Overwrite a session's live (in-progress) usage snapshot. Never appended —
+ * this is a point-in-time snapshot, not a log (unlike `recordSessionUsage`).
+ * Creates the usage dir if needed. Callers (see `HeadlessSession`) are
+ * expected to wrap this in try/catch and treat failures as non-fatal.
+ */
+export async function writeLiveUsage(workspaceRoot: string, record: LiveUsageRecord): Promise<void> {
+	const file = liveUsageFilePath(workspaceRoot, record.sessionId)
+	await fsp.mkdir(path.dirname(file), { recursive: true })
+	await fsp.writeFile(file, JSON.stringify(record, null, 2) + "\n", "utf-8")
+}
+
+/**
+ * Delete a session's live snapshot. Called on every completion path once the
+ * final `.jsonl` record is written — that record is the authoritative source,
+ * so a stale live snapshot must not linger. Never throws for a missing file
+ * (`force: true`). Callers are expected to wrap this in try/catch (non-fatal).
+ */
+export async function removeLiveUsage(workspaceRoot: string, sessionId: string): Promise<void> {
+	await fsp.rm(liveUsageFilePath(workspaceRoot, sessionId), { force: true })
+}
+
+/**
+ * Read + loosely validate one usage JSONL file. Malformed/partially-written
+ * lines are skipped; a missing file yields an empty array (never throws for
+ * ENOENT — matches the memory store's `readJsonl` idiom).
+ *
+ * Deduped by `sessionId` (issue #81): a session id can be reused across a
+ * restart/retry of the same worker, which appends another line to the same
+ * file (the file itself is named `<sessionId>.jsonl`, so every line here
+ * already shares one id) — without dedup, dashboard `sumSessions` would sum
+ * every one of those rows and double/triple-count cost and tokens. The last
+ * record for a given sessionId wins (most recent write reflects the final
+ * outcome of that session id).
+ */
+export async function readUsageFile(file: string): Promise<UsageRecord[]> {
+	let raw: string
+	try {
+		raw = await fsp.readFile(file, "utf-8")
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return []
+		}
+		throw error
+	}
+	const bySessionId = new Map<string, UsageRecord>()
+	const order: string[] = []
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim()
+		if (!trimmed) {
+			continue
+		}
+		try {
+			const parsed = JSON.parse(trimmed) as Partial<UsageRecord>
+			if (typeof parsed.sessionId === "string" && typeof parsed.status === "string") {
+				if (!bySessionId.has(parsed.sessionId)) {
+					order.push(parsed.sessionId)
+				}
+				bySessionId.set(parsed.sessionId, parsed as UsageRecord)
+			}
+		} catch {
+			// Loose validation: skip malformed / partially-written lines.
+		}
+	}
+	return order.map((id) => bySessionId.get(id) as UsageRecord)
+}
+
+/**
+	* Read + loosely validate one live usage snapshot (`*.live.json` — a single
+	* JSON object, overwritten in place, NOT JSONL). Missing or malformed files
+	* yield `null` (never throws for ENOENT / bad JSON — same ethos as
+	* `readUsageFile`).
+	*/
+export async function readLiveUsageFile(file: string): Promise<LiveUsageRecord | null> {
+	let raw: string
+	try {
+		raw = await fsp.readFile(file, "utf-8")
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return null
+		}
+		throw error
+	}
+	try {
+		const parsed = JSON.parse(raw) as Partial<LiveUsageRecord>
+		if (typeof parsed.sessionId === "string" && parsed.status === "running") {
+			return parsed as LiveUsageRecord
+		}
+		return null
+	} catch {
+		// Loose validation: a partially-written snapshot is not a session.
+		return null
+	}
+}

package/src/github/app-auth.ts

@@ -0,0 +1,161 @@
+/**
+ * GitHub App authentication — installation access tokens.
+ *
+ * Wraps `@octokit/auth-app` (the GitHub-maintained library for exactly this;
+ * it handles the RS256 JWT signing and the POST /app/installations/{id}/
+ * access_tokens token-exchange protocol — hand-rolling that insecurely would
+ * be worse than taking the dependency). See docs/github-app-setup.md for the
+ * manual App registration the human owner must do first.
+ *
+ * Security model:
+ *  - The durable secret is the App private key (from env, per
+ *    docs/github-app-setup.md). Installation tokens are deliberately
+ *    EPHEMERAL (1h validity) — we cache them in memory only, keyed by
+ *    installation id, refresh on demand past expiry, and never persist a
+ *    token to disk.
+ *  - The default cache uses the library's own LRU (TTL = 59 min < GitHub's
+ *    1h token lifetime). Tests inject a fake cache + fake clock to prove the
+ *    caching and refresh behavior without sleeping or hitting the network.
+ */
+
+import { createAppAuth } from "@octokit/auth-app"
+import { request as octokitRequest } from "@octokit/request"
+
+/** Minimal shape of the library's installation-token auth result (the full
+ * `InstallationAccessTokenAuthentication` type is not re-exported from
+ * "@octokit/auth-app", so we declare the fields we consume). */
+interface InstallationTokenResult {
+	token: string
+	expiresAt: string
+}
+
+/** Minimal callable shape of the auth strategy (matches AuthInterface's
+ * installation overload; the type itself isn't exported from the package). */
+type InstallationAuth = (options: {
+	type: "installation"
+	installationId: number | string
+	refresh?: boolean
+}) => Promise<InstallationTokenResult>
+
+/** In-memory token cache interface (mirrors the shape the library's Cache
+ * option expects; ours is injectable + testable). */
+export interface TokenCache {
+	get(key: string): string | undefined | Promise<string | undefined>
+	set(key: string, value: string): unknown | Promise<unknown>
+}
+
+interface Clock {
+	now(): number
+}
+
+export interface AppAuthConfig {
+	/** GitHub App numeric ID ($GITHUB_APP_ID). */
+	appId: string | number
+	/** App private key PEM text ($GITHUB_APP_PRIVATE_KEY). */
+	privateKey: string
+	/** Optional GitHub API base URL override (tests/mocks). */
+	baseUrl?: string
+	/** Injectable fetch for tests (default: global fetch). */
+	fetchImpl?: typeof fetch
+	/** Injectable clock for tests (default: Date.now). */
+	clock?: Clock
+	/** Optional injectable cache (default: the library's own in-memory LRU). */
+	cache?: TokenCache
+}
+
+export interface AppAuthClient {
+	/** A fresh (or cached, unexpired) installation access token. */
+	getInstallationToken(installationId: number | string): Promise<string>
+}
+
+/** 59 minutes — refresh a minute before GitHub's 1h token lifetime ends. */
+export const TOKEN_TTL_MS = 59 * 60 * 1000
+/** Cache-key prefix so mixed cache implementations stay namespaced. */
+const CACHE_PREFIX = "github-app-installation-token:"
+
+export class AppAuthError extends Error {
+	readonly installationId: number | string
+	constructor(message: string, installationId: number | string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = "AppAuthError"
+		this.installationId = installationId
+	}
+}
+
+/**
+ * Build an AppAuthClient from App ID + private key (from env per
+ * docs/github-app-setup.md). The returned client caches installation tokens
+ * in memory, keyed by installation id, and refreshes them before expiry.
+ */
+export function createAppAuthClient(config: AppAuthConfig): AppAuthClient {
+	const { appId, privateKey, baseUrl, fetchImpl, clock = { now: () => Date.now() }, cache } = config
+
+	// The library's Cache option expects { get, set } with string values; we
+	// wrap our own cache so the expiry bookkeeping stays in ONE place (here),
+	// which is what the tests assert against.
+	const libCache: Exclude<Parameters<typeof createAppAuth>[0]["cache"], undefined> = {
+		get: async (key: string) => (await cache?.get(key)) ?? "",
+		set: (key: string, value: string) => cache?.set(key, value) ?? undefined,
+	}
+
+	// The library's `request` option wants a full RequestInterface; build one
+	// from the package's own @octokit/request with our baseUrl/fetch injected
+	// (fetch is honored per-request by fetch-wrapper via options.request.fetch).
+	const request = octokitRequest.defaults({
+		...(baseUrl ? { baseUrl } : {}),
+		...(fetchImpl ? { request: { fetch: fetchImpl } } : {}),
+	})
+
+	const auth: InstallationAuth = createAppAuth({
+		appId,
+		privateKey,
+		request,
+		cache: libCache,
+	})
+
+	async function getInstallationToken(installationId: number | string): Promise<string> {
+		const key = `${CACHE_PREFIX}${installationId}`
+		const cached = await cache?.get(key)
+		if (typeof cached === "string") {
+			const parsed = JSON.parse(cached) as { token: string; expiresAt: number }
+			// Refresh BEFORE expiry (a 1-minute safety margin — see TOKEN_TTL_MS).
+			if (parsed.expiresAt > clock.now()) {
+				return parsed.token
+			}
+		}
+
+		let authentication
+		try {
+			authentication = await auth({
+				type: "installation",
+				installationId,
+				// `refresh: true` bypasses the library's OWN internal cache so
+				// OUR expiry bookkeeping (with the injectable clock) is what
+				// governs refreshes.
+				refresh: true,
+			})
+		} catch (err) {
+			throw new AppAuthError(
+				`failed to exchange App credentials for an installation access token (installation ${installationId}): ${
+					err instanceof Error ? err.message : String(err)
+				}`,
+				installationId,
+				{ cause: err },
+			)
+		}
+
+		const token = authentication.token
+		if (!token) {
+			throw new AppAuthError(`installation token exchange returned no token (installation ${installationId})`, installationId)
+		}
+		const expiresAt = new Date(authentication.expiresAt).getTime()
+		if (!Number.isFinite(expiresAt)) {
+			throw new AppAuthError(`installation token exchange returned no expiry (installation ${installationId})`, installationId)
+		}
+		await cache?.set(key, JSON.stringify({ token, expiresAt }))
+
+		return token
+	}
+
+	return { getInstallationToken }
+}