headlesscode 1.0.2

package/src/github/pr.ts

@@ -0,0 +1,321 @@
+/**
+ * Open a pull request via the GitHub REST API using the installation token.
+ *
+ * `openPullRequest()` is the PR half of push-back: after `pushBranch()` has
+ * pushed a named branch (see src/github/push.ts), this opens a PR from that
+ * `head` branch into a `base` branch.
+ *
+ * `getPullRequestStatus()` is the read-back half used by orchestrator
+ * worktree cleanup (`src/orchestrator/merge-check.ts`): a squash/rebase PR
+ * merge creates a NEW commit whose hash is nothing on the source branch, so
+ * the local `merge-base --is-ancestor` check alone would wrongly report
+ * "not merged". GitHub's server-computed `.merged` boolean on
+ * `GET /repos/{owner}/{repo}/pulls/{number}` is the only authoritative
+ * "is this PR merged" answer for that workflow.
+ *
+ * The base branch is never hardcoded: when `base` is omitted it is resolved
+ * fresh from the repo API (`GET /repos/{owner}/{repo}` → `default_branch`),
+ * so the PR always targets the repo's REAL default branch unless the caller
+ * overrides it explicitly.
+ *
+ * Transport: plain authenticated `fetch` (Node >= 18) against the one REST
+ * endpoint needed, matching src/github/installations.ts — no new runtime
+ * dependency (this project deliberately avoids heavy SDKs; @octokit/rest is
+ * not even present). The token goes in an `Authorization: Bearer` header and
+ * is never logged.
+ *
+ * Failure honesty: a PR whose head→base has nothing to merge is a REAL GitHub
+ * API error (HTTP 422 "No commits between ..." / "The head and base branches
+ * are the same"). It is surfaced as a typed NoDiffError — never silently
+ * succeeded or retried.
+ */
+
+/** The function that supplies a fresh installation access token. */
+type TokenSupplier = () => Promise<string>
+
+export interface OpenPrOptions {
+	installationId: number | string
+	owner: string
+	repo: string
+	/** Branch name pushed in step 1 (the PR's source). */
+	head: string
+	/**
+	 * Target branch, e.g. "main"/"master". Omitted → resolved fresh from the
+	 * repo API's default_branch (never hardcoded here).
+	 */
+	base?: string
+	title: string
+	body: string
+	getToken: TokenSupplier
+	/** API base URL override (tests/mocks; default api.github.com). */
+	baseUrl?: string
+	/** Injectable fetch for tests (default: global fetch). */
+	fetchImpl?: typeof fetch
+}
+
+export interface OpenPrResult {
+	number: number
+	/** The human-facing PR page URL (GitHub's `html_url`), not the API URL. */
+	url: string
+}
+
+/** Non-2xx GitHub API response for one of the PR endpoints. */
+export class OpenPrError extends Error {
+	readonly status: number
+	readonly url: string
+	constructor(status: number, message: string, url: string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = "OpenPrError"
+		this.status = status
+		this.url = url
+	}
+}
+
+/** The PR has nothing to merge (no commits between head and base, or head ===
+ * base) — GitHub's real "you cannot open this PR" case. */
+export class NoDiffError extends OpenPrError {
+	constructor(status: number, message: string, url: string, options?: ErrorOptions) {
+		super(status, message, url, options)
+		this.name = "NoDiffError"
+	}
+}
+
+const DEFAULT_GH_BASE_URL = "https://api.github.com"
+const GH_API_VERSION = "2022-11-28"
+const USER_AGENT = "headlesscode-push-pr"
+
+function ghHeaders(token: string): Record<string, string> {
+	return {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": GH_API_VERSION,
+		Authorization: `Bearer ${token}`,
+		"User-Agent": USER_AGENT,
+		"Content-Type": "application/json",
+	}
+}
+
+interface ErrorPayload {
+	message?: unknown
+	errors?: unknown
+}
+
+async function parseErrorPayload(response: Response): Promise<ErrorPayload> {
+	try {
+		return (await response.json()) as ErrorPayload
+	} catch {
+		return {}
+	}
+}
+
+/** The message GitHub gives for "nothing to merge" (top-level or in errors[]). */
+const NO_DIFF_PATTERNS = [/no commits between/i, /head and base branches are the same/i]
+
+function isNoDiff(payload: ErrorPayload): boolean {
+	const message = payload.message
+	if (typeof message === "string" && NO_DIFF_PATTERNS.some((re) => re.test(message))) {
+		return true
+	}
+	if (Array.isArray(payload.errors)) {
+		for (const entry of payload.errors) {
+			if (entry === null || typeof entry !== "object") {
+				continue
+			}
+			const entryMessage = (entry as { message?: unknown }).message
+			if (typeof entryMessage === "string" && NO_DIFF_PATTERNS.some((re) => re.test(entryMessage))) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+function formatErrorMessage(payload: ErrorPayload, fallback: string): string {
+	if (typeof payload.message === "string" && payload.message !== "") {
+		return payload.message
+	}
+	return fallback
+}
+
+/** The repo API's `default_branch` for <owner>/<repo> (never hardcoded). */
+export async function getRepoDefaultBranch(options: {
+	owner: string
+	repo: string
+	getToken: TokenSupplier
+	baseUrl?: string
+	fetchImpl?: typeof fetch
+}): Promise<string> {
+	const { owner, repo, getToken, baseUrl, fetchImpl = fetch } = options
+	const token = await getToken()
+
+	const apiBase = (baseUrl ?? DEFAULT_GH_BASE_URL).replace(/\/+$/, "")
+	const url = `${apiBase}/repos/${owner}/${repo}`
+
+	let response: Response
+	try {
+		response = await fetchImpl(url, {
+			method: "GET",
+			headers: ghHeaders(token),
+		})
+	} catch (err) {
+		throw new OpenPrError(
+			0,
+			`GitHub API network error (GET ${url}): ${err instanceof Error ? err.message : String(err)}`,
+			url,
+			{ cause: err },
+		)
+	}
+
+	if (!response.ok) {
+		const payload = await parseErrorPayload(response)
+		throw new OpenPrError(response.status, formatErrorMessage(payload, `GitHub API HTTP ${response.status} for GET ${url}`), url)
+	}
+
+	const body = (await response.json()) as { default_branch?: unknown }
+	if (typeof body.default_branch !== "string" || body.default_branch === "") {
+		throw new OpenPrError(response.status, `repo API for ${owner}/${repo} returned no default_branch`, url)
+	}
+	return body.default_branch
+}
+
+/**
+ * Open a PR from `head` into `base` (resolved to the repo's real default
+ * branch when omitted) on <owner>/<repo>. Returns the PR number + human-facing
+ * URL. A "nothing to merge" API response surfaces as NoDiffError.
+ */
+export async function openPullRequest(options: OpenPrOptions): Promise<OpenPrResult> {
+	const { owner, repo, head, title, body, getToken, baseUrl, fetchImpl = fetch } = options
+	if (!owner || !repo) {
+		throw new OpenPrError(0, "openPullRequest: owner and repo are required", "")
+	}
+	if (!head) {
+		throw new OpenPrError(0, "openPullRequest: head is required", "")
+	}
+	if (!title) {
+		throw new OpenPrError(0, "openPullRequest: title is required", "")
+	}
+
+	const token = await getToken()
+	if (!token) {
+		throw new OpenPrError(0, "openPullRequest: no installation token provided", "")
+	}
+
+	// Resolve the real target branch fresh unless the caller overrode it.
+	const base = options.base ?? (await getRepoDefaultBranch({ owner, repo, getToken: async () => token, baseUrl, fetchImpl }))
+
+	const apiBase = (baseUrl ?? DEFAULT_GH_BASE_URL).replace(/\/+$/, "")
+	const url = `${apiBase}/repos/${owner}/${repo}/pulls`
+
+	let response: Response
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers: ghHeaders(token),
+			body: JSON.stringify({ title, head, base, body }),
+		})
+	} catch (err) {
+		throw new OpenPrError(
+			0,
+			`GitHub API network error (POST ${url}): ${err instanceof Error ? err.message : String(err)}`,
+			url,
+			{ cause: err },
+		)
+	}
+
+	if (!response.ok) {
+		const payload = await parseErrorPayload(response)
+		const message = formatErrorMessage(payload, `GitHub API HTTP ${response.status} for POST ${url}`)
+		if (isNoDiff(payload)) {
+			// Nothing to merge is a real, permanent API rejection (422) — a
+			// retry would fail identically. Surface it clearly, never retry.
+			throw new NoDiffError(response.status, `nothing to merge: ${message}`, url)
+		}
+		throw new OpenPrError(response.status, message, url)
+	}
+
+	const pr = (await response.json()) as { number?: unknown; html_url?: unknown }
+	if (typeof pr.number !== "number" || typeof pr.html_url !== "string") {
+		throw new OpenPrError(response.status, `unexpected PR response shape from POST ${url}`, url)
+	}
+	return { number: pr.number, url: pr.html_url }
+}
+
+export interface PullRequestStatus {
+	number: number
+	/** "open" | "closed" — the PR's lifecycle state, NOT its merge status. */
+	state: string
+	/** GitHub's server-computed merge boolean — the authoritative answer. */
+	merged: boolean
+	mergedAt?: string
+	htmlUrl?: string
+	title?: string
+}
+
+/**
+	* Read a PR's status back from `GET /repos/{owner}/{repo}/pulls/{number}`.
+	* The `.merged` field is computed server-side by GitHub and is the ONLY
+	* correct "is this PR merged" answer for squash/rebase merges (which create
+	* a new commit hash unrelated to anything on the source branch). Non-2xx
+	* API responses throw OpenPrError exactly like openPullRequest; a malformed
+	* 2xx body (missing `merged`/`state`) also throws rather than guessing.
+	*/
+export async function getPullRequestStatus(options: {
+	owner: string
+	repo: string
+	prNumber: number
+	getToken: TokenSupplier
+	baseUrl?: string
+	fetchImpl?: typeof fetch
+}): Promise<PullRequestStatus> {
+	const { owner, repo, prNumber, getToken, baseUrl, fetchImpl = fetch } = options
+	if (!owner || !repo || !Number.isInteger(prNumber) || prNumber <= 0) {
+		throw new OpenPrError(0, "getPullRequestStatus: owner, repo and a positive prNumber are required", "")
+	}
+
+	const token = await getToken()
+	if (!token) {
+		throw new OpenPrError(0, "getPullRequestStatus: no installation token provided", "")
+	}
+
+	const apiBase = (baseUrl ?? DEFAULT_GH_BASE_URL).replace(/\/+$/, "")
+	const url = `${apiBase}/repos/${owner}/${repo}/pulls/${prNumber}`
+
+	let response: Response
+	try {
+		response = await fetchImpl(url, {
+			method: "GET",
+			headers: ghHeaders(token),
+		})
+	} catch (err) {
+		throw new OpenPrError(
+			0,
+			`GitHub API network error (GET ${url}): ${err instanceof Error ? err.message : String(err)}`,
+			url,
+			{ cause: err },
+		)
+	}
+
+	if (!response.ok) {
+		const payload = await parseErrorPayload(response)
+		throw new OpenPrError(response.status, formatErrorMessage(payload, `GitHub API HTTP ${response.status} for GET ${url}`), url)
+	}
+
+	const body = (await response.json()) as {
+		number?: unknown
+		state?: unknown
+		merged?: unknown
+		merged_at?: unknown
+		html_url?: unknown
+		title?: unknown
+	}
+	if (typeof body.number !== "number" || typeof body.state !== "string" || typeof body.merged !== "boolean") {
+		throw new OpenPrError(response.status, `unexpected PR status shape from GET ${url}`, url)
+	}
+	return {
+		number: body.number,
+		state: body.state,
+		merged: body.merged,
+		...(typeof body.merged_at === "string" ? { mergedAt: body.merged_at } : {}),
+		...(typeof body.html_url === "string" ? { htmlUrl: body.html_url } : {}),
+		...(typeof body.title === "string" ? { title: body.title } : {}),
+	}
+}

package/src/github/provision.ts

@@ -0,0 +1,118 @@
+/**
+ * Repo provisioning: installation + repo → a real local clone.
+ *
+ * `provisionRepo()` gets a fresh installation access token (via
+ * src/github/app-auth.ts), constructs GitHub's documented authenticated clone
+ * URL for App installation tokens
+ * (https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation:
+ * `git clone https://x-access-token:TOKEN@github.com/owner/repo.git`), clones
+ * into `targetDir`, then REWRITES the remote to a plain token-free
+ * `https://github.com/owner/repo.git` so the token never lingers in
+ * `.git/config`. The resulting path is exactly what the rest of headlesscode
+ * expects as a `--workspace` value — no downstream changes needed.
+ *
+ * The token never touches disk beyond the transient clone URL (and even that
+ * is scrubbed immediately after): it is never written to the cloned repo's
+ * config, never logged, never persisted.
+ */
+
+import { execFile } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { promisify } from "node:util"
+
+const execFileP = promisify(execFile)
+
+export interface ProvisionOptions {
+	installationId: number | string
+	owner: string
+	repo: string
+	/** Local directory to clone into. Created if missing; must be empty if it exists. */
+	targetDir: string
+	/** The function that supplies a fresh installation access token. */
+	getToken: () => Promise<string>
+	/** Optional explicit git binary (tests). Defaults to "git" on PATH. */
+	gitBin?: string
+}
+
+export class ProvisionError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = "ProvisionError"
+	}
+}
+
+function isDirEmpty(dir: string): boolean {
+	return fs.readdirSync(dir).length === 0
+}
+
+/**
+ * Clone <owner>/<repo> into <targetDir> using a fresh installation token, then
+ * strip the token out of the clone's remote URL. Returns the absolute local
+ * path, ready for use as a `--workspace` value.
+ */
+export async function provisionRepo(options: ProvisionOptions): Promise<string> {
+	const { installationId, owner, repo, targetDir, getToken, gitBin = "git" } = options
+	if (!owner || !repo) {
+		throw new ProvisionError("provisionRepo: owner and repo are required")
+	}
+	if (!targetDir) {
+		throw new ProvisionError("provisionRepo: targetDir is required")
+	}
+
+	const target = path.resolve(targetDir)
+
+	// Refuse to silently overwrite: the target must be missing, or an existing
+	// EMPTY directory (a stray empty dir is fine to clone into).
+	if (fs.existsSync(target)) {
+		if (!fs.statSync(target).isDirectory()) {
+			throw new ProvisionError(`provisionRepo: target exists and is not a directory: ${target}`)
+		}
+		if (!isDirEmpty(target)) {
+			throw new ProvisionError(`provisionRepo: target directory is not empty: ${target}`)
+		}
+	} else {
+		fs.mkdirSync(target, { recursive: true })
+	}
+
+	const token = await getToken()
+	if (!token) {
+		throw new ProvisionError("provisionRepo: no installation token provided")
+	}
+
+	// GitHub's documented pattern for App installation tokens:
+	//   git clone https://x-access-token:<token>@github.com/<owner>/<repo>.git
+	const authenticatedUrl = `https://x-access-token:${token}@github.com/${owner}/${repo}.git`
+	const cleanUrl = `https://github.com/${owner}/${repo}.git`
+
+	try {
+		await execFileP(gitBin, ["clone", "--quiet", authenticatedUrl, target], { timeout: 120_000 })
+	} catch (err) {
+		throw new ProvisionError(
+			`provisionRepo: git clone failed for ${owner}/${repo}: ${err instanceof Error ? err.message : String(err)}`,
+			{ cause: err },
+		)
+	}
+
+	// Security: rewrite the remote to a plain URL immediately, so the token
+	// does not linger in <target>/.git/config for the life of the clone.
+	try {
+		await execFileP(gitBin, ["-C", target, "remote", "set-url", "origin", cleanUrl], { timeout: 30_000 })
+	} catch (err) {
+		throw new ProvisionError(
+			`provisionRepo: clone succeeded but failed to strip the token from the remote URL: ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+			{ cause: err },
+		)
+	}
+
+	return target
+}
+
+/** Read the clone's origin URL (exported so the security test can assert on
+ * the ACTUAL .git/config contents, not on our own assumptions). */
+export async function readOriginUrl(repoDir: string, gitBin = "git"): Promise<string> {
+	const { stdout } = await execFileP(gitBin, ["-C", repoDir, "remote", "get-url", "origin"])
+	return stdout.trim()
+}

package/src/github/push.ts

@@ -0,0 +1,122 @@
+/**
+ * Repo push-back: push a local branch to GitHub using the installation token.
+ *
+ * `pushBranch()` is the write half of repo provisioning: it gets a fresh
+ * installation access token (same `getToken` shape as `provisionRepo` in
+ * src/github/provision.ts), pushes the local HEAD to an explicitly NAMED
+ * branch on <owner>/<repo>, and strips the token out of the repo's origin URL
+ * before returning.
+ *
+ * Token discipline matches provision.ts exactly: the token only ever appears
+ * inside a transient `https://x-access-token:<token>@github.com/...` URL. The
+ * push is done via `git remote set-url origin <auth-url>` → `git push origin
+ * HEAD:<branch>` → `git remote set-url origin <original>` in a `finally`, so
+ * the token never persists in `.git/config` past this call — even when the
+ * push itself fails. The ORIGINAL origin URL is captured first and restored
+ * verbatim (for a provisioned repo that is the token-free
+ * `https://github.com/<owner>/<repo>.git`, but whatever it was, it ends up
+ * exactly as it started).
+ *
+ * Never pushes to a repo's default branch: the refspec is always the explicit
+ * `HEAD:<branchName>` — there is no code path that pushes to an implicit
+ * upstream/default branch. The CLI layer additionally refuses
+ * `--branch == --base` (see src/github/cli.ts).
+ */
+
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+const execFileP = promisify(execFile)
+
+export interface PushOptions {
+	installationId: number | string
+	owner: string
+	repo: string
+	/** Local repo path to push from (already has the work committed). */
+	localDir: string
+	/** Branch name to push to on the remote (created if it doesn't exist). */
+	branchName: string
+	/** The function that supplies a fresh installation access token. */
+	getToken: () => Promise<string>
+	/** Optional explicit git binary (tests). Defaults to "git" on PATH. */
+	gitBin?: string
+}
+
+export class PushError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = "PushError"
+	}
+}
+
+/**
+ * Push the current HEAD of <localDir> to <branchName> on <owner>/<repo>,
+ * using a fresh installation token, then restore the origin URL to its
+ * original token-free form. The token never persists past this call.
+ */
+export async function pushBranch(options: PushOptions): Promise<void> {
+	const { owner, repo, localDir, branchName, getToken, gitBin = "git" } = options
+	if (!owner || !repo) {
+		throw new PushError("pushBranch: owner and repo are required")
+	}
+	if (!localDir) {
+		throw new PushError("pushBranch: localDir is required")
+	}
+	if (!branchName) {
+		throw new PushError("pushBranch: branchName is required")
+	}
+
+	const token = await getToken()
+	if (!token) {
+		throw new PushError("pushBranch: no installation token provided")
+	}
+
+	// GitHub's documented pattern for App installation tokens (same as
+	// provision.ts): git push https://x-access-token:<token>@github.com/<owner>/<repo>.git
+	const authenticatedUrl = `https://x-access-token:${token}@github.com/${owner}/${repo}.git`
+
+	// Capture the CURRENT origin URL BEFORE touching anything. Whatever it is
+	// (a provisioned repo's token-free clean URL, or anything else), it gets
+	// restored verbatim after the push — so this call is a no-op on the
+	// remote config except for the transient authenticated window inside it.
+	let originalUrl: string
+	try {
+		const { stdout } = await execFileP(gitBin, ["-C", localDir, "remote", "get-url", "origin"], { timeout: 30_000 })
+		originalUrl = stdout.trim()
+	} catch (err) {
+		throw new PushError(
+			`pushBranch: cannot read the 'origin' remote URL in ${localDir}: ${err instanceof Error ? err.message : String(err)}`,
+			{ cause: err },
+		)
+	}
+
+	try {
+		await execFileP(gitBin, ["-C", localDir, "remote", "set-url", "origin", authenticatedUrl], { timeout: 30_000 })
+		// Always an EXPLICIT named-branch refspec: `git push origin HEAD:<name>`
+		// creates/updates exactly <name> on the remote and never touches the
+		// repo's default branch (no bare `git push`, no upstream inference).
+		await execFileP(gitBin, ["-C", localDir, "push", "origin", `HEAD:${branchName}`], { timeout: 120_000 })
+	} catch (err) {
+		throw new PushError(
+			`pushBranch: git push ${owner}/${repo} failed for branch '${branchName}': ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+			{ cause: err },
+		)
+	} finally {
+		// Security: strip the token out of .git/config IMMEDIATELY — including
+		// on failure. If the restore itself fails, that is the one error we
+		// cannot paper over (the token may be on disk), so it REPLACES any
+		// push error.
+		try {
+			await execFileP(gitBin, ["-C", localDir, "remote", "set-url", "origin", originalUrl], { timeout: 30_000 })
+		} catch (err) {
+			throw new PushError(
+				`pushBranch: failed to strip the token from the origin URL in ${localDir}/.git/config: ${
+					err instanceof Error ? err.message : String(err)
+				}`,
+				{ cause: err },
+			)
+		}
+	}
+}

package/src/index-util.ts

@@ -0,0 +1,50 @@
+/**
+ * Workspace codebase-index detection helpers.
+ *
+ * The codebase-search index now lives in the CENTRAL per-project data store
+ * (see src/project-store.ts): `<dataRoot>/projects/<project-key>/codesearch/
+ * index.jsonl`, keyed by the resolved git-common-dir parent so every worktree
+ * of a repo shares the SAME index — the property that made the old
+ * spawn-script index-seeding step unnecessary. These helpers answer "does a
+ * usable index exist here?" in one place, used by:
+ *   - HeadlessSession (src/engine/loop.ts) for the read-only-nudge guardrail,
+ *   - the spawn-parallel-worktrees scripts (which decide whether a fresh
+ *     worktree already has an index — now a central-store lookup, no seeding),
+ *   - the spawn-parallel-worktrees smoke test.
+ *
+ * A "usable" index is one that exists AND is non-empty (an empty file is a
+ * crashed/partial build — treat it as absent so the spawner rebuilds it).
+ */
+
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+import { resolveProjectDataDir } from "./project-store.js"
+
+/** Absolute path of the codebase-search index for a workspace root. */
+export function indexFilePathFor(workspaceRoot: string): string {
+	return path.join(resolveProjectDataDir(workspaceRoot), "codesearch", "index.jsonl")
+}
+
+/**
+ * True when the workspace already has a non-empty codebase-search index.
+ * Also counts a legacy workspace-relative `.headlesscode/codesearch/index.jsonl`
+ * (pre-migration grace — the same rule the spawn scripts rely on so a fresh
+ * worktree of an already-indexed repo never rebuilds unnecessarily).
+ */
+export async function hasCodebaseIndex(workspaceRoot: string): Promise<boolean> {
+	for (const file of [
+		indexFilePathFor(workspaceRoot),
+		path.join(workspaceRoot, ".headlesscode", "codesearch", "index.jsonl"),
+	]) {
+		try {
+			const st = await fsp.stat(file)
+			if (st.isFile() && st.size > 0) {
+				return true
+			}
+		} catch {
+			// missing — try the next candidate
+		}
+	}
+	return false
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * headlesscode package entry — runs the CLI when executed directly
+ * (`tsx src/index.ts`, `npm run dev`) and re-exports the public API for
+ * programmatic use.
+ */
+
+import { main } from "./cli.js"
+
+// Run the CLI when this file is executed directly (e.g. `tsx src/index.ts`).
+main()
+	.then((code) => {
+		process.exitCode = code
+	})
+	.catch((err) => {
+		process.stderr.write(`headlesscode: unexpected error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+		process.exitCode = 2
+	})
+
+export * from "./cli.js"
+export * from "./memory/index.js"
+export { OpenRouterClient, OpenRouterError, DEFAULT_MODEL } from "./llm/openrouter.js"
+export { HeadlessSession, truncateHistory, DEFAULT_MAX_TOKENS } from "./engine/loop.js"
+export {
+	maybeCondense,
+	condenseOldestTurns,
+	computeCondenseCount,
+	computeCondensePlan,
+	DEFAULT_CONDENSE_THRESHOLD_FRACTION,
+	DEFAULT_CONDENSE_EARLY_FIRE_FRACTION,
+	DEFAULT_CONDENSE_MAX_TOKENS,
+	DEFAULT_CONTEXT_WINDOW_TOKENS,
+} from "./engine/condense.js"
+export {
+	runLocalExplorePhase,
+	buildLocalExploreHandoffMessage,
+	buildLocalExploreTools,
+	OllamaLocalChatClient,
+	LocalExploreError,
+	isLocalExploreEnabled,
+	LOCAL_EXPLORE_ENV,
+	DEFAULT_LOCAL_EXPLORE_MODEL,
+	DEFAULT_LOCAL_EXPLORE_MAX_ITERATIONS,
+	DEFAULT_LOCAL_EXPLORE_CONTEXT_TOKENS,
+	EXPLORE_SYSTEM_PROMPT,
+} from "./engine/local-explore.js"
+export { Logger } from "./engine/logger.js"
+export { parseToolCalls, parseToolCall, bestEffortPartialJson } from "./engine/parser.js"
+export {
+	createHeadlessExecutor,
+	ToolExecutor,
+	resolveWithinWorkspace,
+	PathTraversalError,
+} from "./tools/executor.js"
+export {
+	buildSystemPrompt,
+	loadCustomModes,
+	selectToolsForMode,
+	EXECUTABLE_TOOL_NAMES,
+} from "./engine/prompt.js"
+export {
+	detectStacks,
+	loadStackRules,
+	appendStackRulesSection,
+	STACK_NAMES,
+	STACK_RULES_HEADER,
+	getCentralStackRulesDir,
+	getCentralStackRulesFile,
+	getProjectStackRulesFile,
+} from "./engine/stacks.js"
+export type { StackName, LoadedStackRules } from "./engine/stacks.js"
+export type {
+	ChatMessage,
+	ChatTool,
+	ChatToolCall,
+	LlmClient,
+	LlmRequest,
+	LlmResponse,
+	ParsedToolCall,
+	SessionResult,
+	ToolResult,
+} from "./engine/types.js"