pi-onedev-toolkit 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.2.0 — 2026-08-26
+
+### Security and correctness
+
+- Remove attachment download until TOD can enforce same-origin credentials, redirect safety, bounded downloads, and non-destructive destinations.
+- Treat killed TOD processes as aborts or timeouts instead of successful calls.
+- Reject unknown tool parameters and standardize all multiword parameters on `snake_case`.
+- Fix Cobra boolean arguments for issue confidentiality and PR auto-merge, including explicit `false`, and require a branch in branch build mode.
+- Isolate local build runs with a temporary Git index and disclose/approve build-spec upgrades.
+
+### Agent and user experience
+
+- Split the always-active readiness/setup tool (`onedev_context`) from the domain activator (`onedev_tools`), and remove prompt metadata from deferred domain schemas.
+- Add explicit readiness states, lazy authenticated health checks, coalesced context probes, and caller-isolated cancellation.
+- Replace agent-supplied confirmation booleans with real Pi UI approvals scoped once, per session, or persistently by server/project/operation.
+- Add code-comment reply/resolve/unresolve actions and unit-test report support with TOD capability detection.
+- Add bounded, session-scoped one-shot watches for build completion and pull-request attention.
+
+### Quality
+
+- Add execution-level, lifecycle, approval-storage, local-index, context, and watch regression tests.
+- Add Bun checks, Node 22.19/24 import smoke tests, and an opt-in read-only live OneDev smoke workflow.
+
 ## 0.1.1
 
 - Add `/od-settings` to enable or disable the OneDev project status in the TUI footer.
@@ -8,7 +31,7 @@
 ## 0.1.0
 
 - Initial release.
-- `onedev_tools` domain activator with context, login, and attachment-download actions.
+- `onedev_tools` domain activator with context, login, and attachment-download actions (download removed under Unreleased for credential safety).
 - `onedev_issue`, `onedev_pull`, `onedev_build` tools wrapping the TOD CLI.
 - `/od-context` and `/od-health` commands; session status line with the inferred project.
 - `onedev-issue-to-pr` and `onedev-pr-review` skills.

package/README.md

@@ -1,8 +1,8 @@
 # pi-onedev-toolkit
 
-Lightweight [OneDev](https://onedev.io/) integration for [Pi](https://pi.dev/), built on the official [TOD CLI](https://code.onedev.io/onedev/tod): repo-aware issue, pull request, and build tools plus issue-to-PR and PR-review skills.
+Lightweight [OneDev](https://onedev.io/) integration for [Pi](https://pi.dev/), built on the official [TOD CLI](https://code.onedev.io/onedev/tod): repo-aware issue, pull request, build, and one-shot watch tools plus issue-to-PR and PR-review skills.
 
-The agent never shells out to `tod` itself and never sees tokens. The extension resolves the OneDev project from the repository's git remotes once per session, and the tools speak OneDev terms (`123`, `PROJ-123`, `project#123` all resolve server-side).
+The agent never sees tokens. The extension invokes `tod` with structured arguments, resolves the OneDev project from the repository's git remotes, and keeps unavailable domain schemas out of the default prompt. Model-facing multiword parameters use strict `snake_case`; unknown parameters are rejected instead of being silently ignored.
 
 ## Requirements
 
@@ -22,18 +22,26 @@ pi install npm:pi-onedev-toolkit
 pi install git:github.com/alpertarhan/pi-onedev-toolkit
 ```
 
-Then run `/od-health` once. When the current directory is a OneDev repository, the status line shows the active project. Use `/od-settings` to enable or disable it for the current session branch.
+When the current directory is a OneDev repository, the status line shows the active project. `onedev_context` action `setup` explains missing TOD configuration, credentials, or project remotes; `/od-health` performs an authenticated re-check. Use `/od-settings` to enable or disable the footer for the current session branch.
 
 ## Tools
 
 | Tool | Domains | Covers |
 | --- | --- | --- |
-| `onedev_tools` (always active) | — | Activate domains; session context; login name; download issue/PR attachments |
+| `onedev_context` (always active) | — | Readiness, authenticated health, login, and setup guidance |
+| `onedev_tools` (always active) | — | Activate only the issue, pull, build, and watch domains needed now |
 | `onedev_issue` | issue | Query/get/comment issues, change fields/labels/state, log work, issue branches |
-| `onedev_pull` | pull | PR metadata/comments/code comments/labels/builds/patch, create/edit, approve, request changes, guarded merge/discard |
-| `onedev_build` | build | Build queries, logs, code-problem reports, changes since last success, run jobs (incl. uncommitted local changes), build-spec validation |
+| `onedev_pull` | pull | PR metadata/comments/code comments/labels/builds/patch, create/edit, reply/resolve review comments, approve, request changes, merge/discard |
+| `onedev_build` | build | Build queries, logs, code-problem and unit-test reports, changes since success, jobs, build-spec validation/upgrades |
+| `onedev_watch` | watch | One-shot build-result and pull-attention notifications; list/stop active session watches |
 
-Lazy by design: domain tools activate only through `onedev_tools`, keeping the default tool list light. `merge` and `discard` additionally require `confirm: true`.
+Lazy by design: domain tools activate only through `onedev_tools`, keeping the default tool list and system prompt light. Activation performs the first authenticated check and returns the server, project, and login context in the same response.
+
+Remote and local mutations use Pi's real interactive approval UI. An approval can apply once, for the session, or persist for the exact server/project/operation in `~/.pi/agent/onedev-toolkit.json`; remove that file to revoke all saved approvals. Non-interactive sessions reject unapproved mutations. `build run` in local mode uses an isolated temporary Git index so TOD cannot leave the user's index staged; `check_spec` is treated as a mutation because TOD may upgrade `.onedev-buildspec.yml`.
+
+Watches are session-scoped and one-shot. They use one timer, bounded polling, expiration and backoff, and wake the agent with metadata only. The agent retrieves logs, comments, or build details with the corresponding read tool. At most ten watches may be active; session changes and shutdown clear them.
+
+Attachment download is intentionally not exposed: current TOD releases may send the OneDev bearer token to an absolute external Markdown URL and do not provide a safe download-size/overwrite boundary.
 
 ## Commands
 
@@ -41,6 +49,12 @@ Lazy by design: domain tools activate only through `onedev_tools`, keeping the d
 - `/od-health` — re-check tod configuration and server reachability
 - `/od-settings` — enable or disable the OneDev footer status in the TUI
 
+## Compatibility notes
+
+- Update TOD regularly from its upstream install script. `get_unit_test_report` reports an actionable upgrade error when the installed TOD predates that command.
+- Plain references require the current repository to have a OneDev remote from which TOD can infer the project. The toolkit reports `no_project` rather than pretending a qualified reference can bypass TOD's resolver.
+- Tool calls use `snake_case`, for example `for_code_review`, `target_branch`, `report_name`, and `interval_seconds`.
+
 ## Skills
 
 - `onedev-issue-to-pr` — gather issue context, branch, implement, present for review, then push and open the PR
@@ -51,6 +65,7 @@ Lazy by design: domain tools activate only through `onedev_tools`, keeping the d
 ```bash
 bun install
 bun run check   # typecheck + vitest
+bun run scripts/smoke.ts  # optional read-only live smoke; see CONTRIBUTING.md
 ```
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-onedev-toolkit",
-	"version": "0.1.1",
-	"description": "Lightweight OneDev integration for Pi via the TOD CLI: repo-aware issue, pull request, and build tools",
+	"version": "0.2.0",
+	"description": "Lightweight OneDev integration for Pi via TOD: repo-aware issue, pull request, build, and watch tools",
 	"type": "module",
 	"author": {
 		"name": "Alper Tarhan",
@@ -55,13 +55,17 @@
 	"devDependencies": {
 		"@earendil-works/pi-ai": "0.84.1",
 		"@earendil-works/pi-coding-agent": "0.84.1",
-		"@types/node": "^20.17.0",
+		"@types/node": "^22.19.0",
+		"@types/proper-lockfile": "4.1.4",
 		"typebox": "1.3.12",
 		"typescript": "^7.0.2",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=20.3"
+		"node": ">=22.19.0"
 	},
-	"packageManager": "bun@1.3.14"
+	"packageManager": "bun@1.3.14",
+	"dependencies": {
+		"proper-lockfile": "4.1.2"
+	}
 }

package/skills/onedev-issue-to-pr/SKILL.md

@@ -7,7 +7,7 @@ description: Implement a OneDev issue end to end - gather issue context, branch,
 
 ## Prerequisites
 
-- Call `onedev_tools` with domains `["issue", "pull"]` first; note your login name from the returned context.
+- Call `onedev_tools` with domains `["issue", "pull"]` first; note your login name from the returned context. If activation reports a readiness problem, use `onedev_context` `setup` and stop until it is resolved.
 - The current repository belongs to the issue's project (plain refs like `123` resolve against it).
 
 ## Workflow
@@ -24,10 +24,9 @@ description: Implement a OneDev issue end to end - gather issue context, branch,
    - `onedev_issue` `get` (title, description, fields, submitter)
    - `onedev_issue` `get_comments`
    - Match your login name against submitter/comment authors to understand your role.
-   - Download embedded resources (screenshots, logs) with `onedev_tools` action
-     `download`, passing the URL exactly as it appears in the markdown.
    - If a failed build is part of the issue, gather evidence with `onedev_build`
-     (`get`, `get_log`) before planning changes. Follow `Dependency build … failed`
+     after activating the `build` domain (`get`, `get_log`, and a named
+     `get_unit_test_report` when useful) before planning changes. Follow `Dependency build … failed`
      chains: same-commit dependency failures are the real target; different-commit
      ones mean the failure is inherited.
 
@@ -48,8 +47,14 @@ description: Implement a OneDev issue end to end - gather issue context, branch,
      is inferred from the branch; state it in the description if not.
    - Post the drafted comment with `onedev_issue` `add_comment` if one was prepared.
 
+7. **For long-running CI**, activate `watch` and use `onedev_watch` `watch_build`
+   after obtaining a build reference. The notification is one-shot and metadata-only;
+   inspect the build with `onedev_build` when it fires.
+
 ## Notes
 
 - Write comment text in Markdown.
 - Reference entities as `#123` (current project), `project#123`, or `PROJ-123`.
 - If blocked mid-workflow, report the command and error, and stop.
+- Toolkit mutations still open Pi's interactive approval UI. Do not try to bypass
+  it with a confirmation parameter.

package/skills/onedev-pr-review/SKILL.md

@@ -7,7 +7,7 @@ description: Review a OneDev pull request - gather PR context, builds, and fixed
 
 ## Prerequisites
 
-- Call `onedev_tools` with domains `["pull", "issue", "build"]`; note your login name.
+- Call `onedev_tools` with domains `["pull", "issue", "build"]`; note your login name. If activation reports a readiness problem, use `onedev_context` `setup` and stop until it is resolved.
 - The current repository belongs to the PR's source or target project.
 
 ## Gather context (never review from the patch alone)
@@ -27,7 +27,6 @@ description: Review a OneDev pull request - gather PR context, builds, and fixed
      for what the PR should accomplish.
    - `onedev_pull` `get_builds` — investigate every `FAILED` build with
      `onedev_build` `get` / `get_log` before reviewing code.
-   - Download embedded resources via `onedev_tools` `download`.
    - Match your login name against authors to understand your role
      (pending reviewer, prior commenter, outsider).
 
@@ -39,7 +38,8 @@ description: Review a OneDev pull request - gather PR context, builds, and fixed
 
 2. **Triage prior discussion:** resolve addressed code comments, reply where new
    information is needed, leave unrelated unresolved ones alone. Never modify
-   another user's code comments.
+   another user's code comments. Use `reply_code_comment`, `resolve_code_comment`,
+   or `unresolve_code_comment` with the comment `id`.
 
 3. **Draft findings:**
    - Line-anchored findings → `onedev_pull` `add_code_comment` (`file`, `from_line`,
@@ -53,13 +53,19 @@ description: Review a OneDev pull request - gather PR context, builds, and fixed
 
 5. **On explicit request only:**
    - Post findings/comments/review outcome.
-   - Merge: `merge` requires `confirm: true`. For squash merges, compose the commit
-     message from PR title/description + fixed issues, satisfying
-     `commit_message_requirement` for the target project/branch.
+   - Merge: the toolkit asks for real interactive approval. For squash merges,
+     compose the commit message from PR title/description + fixed issues,
+     satisfying `commit_message_requirement` for the target project/branch.
    - Resolving merge conflicts: fetch the target branch, merge with the PR's
      strategy without committing, resolve, verify clean `git status`, commit.
      For rebase-based strategies, ask for direction before rewriting commits.
 
+6. **When waiting on updates**, activate `watch` and use `onedev_watch`
+   `watch_pull_attention`. It wakes once for a head/state/review/comment/build
+   signal change and includes no comment bodies; re-read the PR after it fires.
+
 ## Notes
 
 - Comment text is Markdown; entity refs are `#123`, `project#123`, or `PROJ-123`.
+- Toolkit mutations still open Pi's interactive approval UI. Do not add or invent
+  a confirmation parameter.

package/src/config-storage.ts

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { lock } from "proper-lockfile";
+
+interface StoredConfig {
+	allowedMutations?: string[];
+	[key: string]: unknown;
+}
+
+async function readText(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function parseConfig(text: string | undefined, path: string): StoredConfig {
+	if (text === undefined) return {};
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new Error(
+			`invalid JSON in OneDev toolkit config ${path}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`OneDev toolkit config is not a JSON object: ${path}`);
+	}
+	return parsed as StoredConfig;
+}
+
+function allowedMutations(config: StoredConfig): string[] {
+	if (!Array.isArray(config.allowedMutations)) return [];
+	return config.allowedMutations.filter(
+		(value): value is string => typeof value === "string",
+	);
+}
+
+export async function readAllowedMutationScopes(path: string): Promise<string[]> {
+	return allowedMutations(parseConfig(await readText(path), path));
+}
+
+async function removeIfPresent(path: string): Promise<void> {
+	try {
+		await rm(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+export async function saveAllowedMutationScope(
+	path: string,
+	scope: string,
+): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+	let compromised: Error | undefined;
+	const release = await lock(path, {
+		realpath: false,
+		stale: 10_000,
+		update: 5_000,
+		retries: {
+			retries: 200,
+			factor: 1.1,
+			minTimeout: 10,
+			maxTimeout: 100,
+			randomize: true,
+		},
+		onCompromised: (error) => {
+			compromised = error;
+		},
+	});
+	try {
+		const original = await readText(path);
+		const config = parseConfig(original, path);
+		const allowed = allowedMutations(config);
+		if (!allowed.includes(scope)) allowed.push(scope);
+		config.allowedMutations = allowed;
+
+		const temporary = resolve(
+			dirname(path),
+			`.${basename(path)}.${randomUUID()}.tmp`,
+		);
+		await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 0o600,
+		});
+		try {
+			if (compromised) throw compromised;
+			await rename(temporary, path);
+		} finally {
+			await removeIfPresent(temporary);
+		}
+	} finally {
+		try {
+			await release();
+		} catch {
+			// A compromised lock is handled before rename; cleanup failure must not kill Pi.
+		}
+	}
+}

package/src/context.ts

@@ -1,34 +1,79 @@
 import type { CommandExecutor } from "./tod.js";
 import { runTod } from "./tod.js";
 
+export type OneDevContextStatus =
+	| "ready"
+	| "not_configured"
+	| "no_project"
+	| "auth_failed"
+	| "unavailable";
+
 export interface OneDevSessionContext {
 	readonly cwd: string;
-	readonly status: "ready" | "unavailable";
+	readonly status: OneDevContextStatus;
 	readonly serverUrl?: string;
-	/** Project path inferred from the repository's git remotes (e.g. "group/myproject"). */
+	/** Project path inferred from the repository's git remotes. */
 	readonly project?: string;
 	readonly loginName?: string;
-	/** Human-readable setup guidance when status is "unavailable". */
 	readonly problem?: string;
 }
 
+export interface ContextRefreshOptions {
+	verifyAuth?: boolean;
+	force?: boolean;
+	signal?: AbortSignal;
+}
+
 export const TOD_INSTALL_HINT =
 	"tod is not installed. Install it (curl -fsSL https://code.onedev.io/onedev/tod/~raw/main/install.sh | bash), then run `tod config set`.";
 
-function unavailable(cwd: string, problem: string): OneDevSessionContext {
-	return { cwd, status: "unavailable", problem };
+function failed(
+	cwd: string,
+	status: Exclude<OneDevContextStatus, "ready">,
+	problem: string,
+	serverUrl?: string,
+	project?: string,
+): OneDevSessionContext {
+	return { cwd, status, problem, serverUrl, project };
+}
+
+async function authenticateContext(
+	exec: CommandExecutor,
+	context: OneDevSessionContext,
+	signal?: AbortSignal,
+): Promise<OneDevSessionContext> {
+	if (
+		context.status !== "ready" ||
+		!context.serverUrl ||
+		!context.project
+	) {
+		return context;
+	}
+	try {
+		const login = await runTod(exec, ["get-login-name"], {
+			cwd: context.cwd,
+			timeoutMs: 15_000,
+			signal,
+			maxOutputBytes: 2_000,
+		});
+		return { ...context, loginName: login.text.trim() || undefined };
+	} catch (cause) {
+		return failed(
+			context.cwd,
+			"auth_failed",
+			`OneDev rejected the server or access token (${cause instanceof Error ? cause.message : String(cause)}). Run \`tod config set\` to fix credentials.`,
+			context.serverUrl,
+			context.project,
+		);
+	}
 }
 
-/**
- * Probe the local OneDev setup once per session:
- * 1. `tod config get server-url` — tod present and configured
- * 2. `tod get-login-name` — server reachable and access token accepted
- * 3. `tod project current` — repo-aware project context (optional)
- */
+/** Probe local configuration/project first; authenticate only on explicit use. */
 export async function probeOneDevContext(
 	exec: CommandExecutor,
 	cwd: string,
 	signal?: AbortSignal,
+	verifyAuth = false,
 ): Promise<OneDevSessionContext> {
 	let serverUrl: string;
 	try {
@@ -41,57 +86,178 @@ export async function probeOneDevContext(
 		serverUrl = configured.text.trim();
 	} catch (cause) {
 		const message = cause instanceof Error ? cause.message : String(cause);
-		return unavailable(
+		return failed(
 			cwd,
+			"unavailable",
 			message.startsWith("tod is not usable") ? TOD_INSTALL_HINT : message,
 		);
 	}
 	if (!serverUrl) {
-		return unavailable(
+		return failed(
 			cwd,
-			"tod is installed but not configured. Run `tod config set` (server-url and access-token), or set ONEDEV_SERVER_URL and ONEDEV_ACCESS_TOKEN.",
+			"not_configured",
+			"tod is installed but not configured. Run `tod config set` for server-url and access-token, or set ONEDEV_SERVER_URL and ONEDEV_ACCESS_TOKEN.",
 		);
 	}
 
-	let loginName: string | undefined;
+	let project: string;
 	try {
-		const login = await runTod(exec, ["get-login-name"], {
+		const current = await runTod(exec, ["project", "current"], {
 			cwd,
-			timeoutMs: 15_000,
+			timeoutMs: 10_000,
 			signal,
 			maxOutputBytes: 2_000,
 		});
-		loginName = login.text.trim() || undefined;
+		project = current.text.trim();
 	} catch (cause) {
-		return unavailable(
+		return failed(
 			cwd,
-			`OneDev server or access token rejected (${cause instanceof Error ? cause.message : String(cause)}). Run \`tod config set\` to fix credentials.`,
+			"no_project",
+			`No OneDev project can be inferred from this repository's remotes (${cause instanceof Error ? cause.message : String(cause)}). Run Pi from a OneDev clone or add a OneDev remote.`,
+			serverUrl,
 		);
 	}
-
-	let project: string | undefined;
-	try {
-		const current = await runTod(exec, ["project", "current"], {
+	if (!project) {
+		return failed(
 			cwd,
-			timeoutMs: 15_000,
-			signal,
-			maxOutputBytes: 2_000,
-		});
-		project = current.text.trim() || undefined;
-	} catch {
-		// Not a OneDev repository: fine. Tools accept explicit projects/qualified refs.
+			"no_project",
+			"No OneDev project can be inferred from this repository's remotes. Run Pi from a OneDev clone or add a OneDev remote.",
+			serverUrl,
+		);
+	}
+
+	if (!verifyAuth) return { cwd, status: "ready", serverUrl, project };
+	return authenticateContext(
+		exec,
+		{ cwd, status: "ready", serverUrl, project },
+		signal,
+	);
+}
+
+function waitForCaller<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+	if (!signal) return promise;
+	if (signal.aborted)
+		return Promise.reject(
+			signal.reason instanceof Error ? signal.reason : new Error("cancelled"),
+		);
+	return new Promise<T>((resolve, reject) => {
+		const abort = (): void =>
+			reject(
+				signal.reason instanceof Error ? signal.reason : new Error("cancelled"),
+			);
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(
+			(value) => {
+				signal.removeEventListener("abort", abort);
+				resolve(value);
+			},
+			(error) => {
+				signal.removeEventListener("abort", abort);
+				reject(error);
+			},
+		);
+	});
+}
+
+/** Coalesces probes while isolating individual caller cancellation. */
+export class OneDevContextManager {
+	#cwd: string | undefined;
+	#current: OneDevSessionContext | undefined;
+	#pending:
+		| {
+				controller: AbortController;
+				promise: Promise<OneDevSessionContext>;
+		  }
+		| undefined;
+
+	constructor(readonly exec: CommandExecutor) {}
+
+	current(): OneDevSessionContext {
+		if (!this.#current) throw new Error("OneDev extension is still initializing");
+		return this.#current;
+	}
+
+	reset(cwd: string): void {
+		this.#pending?.controller.abort(new Error("OneDev session context reset"));
+		this.#pending = undefined;
+		this.#current = undefined;
+		this.#cwd = cwd;
 	}
 
-	return { cwd, status: "ready", serverUrl, loginName, project };
+	clear(): void {
+		this.#pending?.controller.abort(new Error("OneDev session ended"));
+		this.#pending = undefined;
+		this.#current = undefined;
+		this.#cwd = undefined;
+	}
+
+	async refresh(
+		options: ContextRefreshOptions = {},
+	): Promise<OneDevSessionContext> {
+		if (!this.#cwd) throw new Error("OneDev extension is still initializing");
+		const verifyAuth = options.verifyAuth === true;
+		if (
+			!options.force &&
+			this.#current &&
+			(!verifyAuth || this.#current.loginName)
+		) {
+			return this.#current;
+		}
+
+		if (this.#pending) {
+			const context = await waitForCaller(this.#pending.promise, options.signal);
+			if (!verifyAuth || context.loginName || context.status !== "ready") {
+				return context;
+			}
+		}
+
+		const controller = new AbortController();
+		const cached = this.#current;
+		const canAuthenticateCached =
+			verifyAuth &&
+			!options.force &&
+			cached?.status === "ready" &&
+			!cached.loginName;
+		const promise = (canAuthenticateCached
+			? authenticateContext(this.exec, cached, controller.signal)
+			: probeOneDevContext(
+					this.exec,
+					this.#cwd,
+					controller.signal,
+					verifyAuth,
+				)).then((context) => {
+			if (!controller.signal.aborted) this.#current = context;
+			return context;
+		});
+		const pending = { controller, promise };
+		this.#pending = pending;
+		const clearPending = (): void => {
+			if (this.#pending === pending) this.#pending = undefined;
+		};
+		void promise.then(clearPending, clearPending);
+		return waitForCaller(promise, options.signal);
+	}
 }
 
 export function formatContext(context: OneDevSessionContext): string {
-	if (context.status === "unavailable") {
-		return `OneDev unavailable: ${context.problem ?? "unknown problem"}`;
+	if (context.status !== "ready") {
+		return `OneDev ${context.status.replace("_", " ")}: ${context.problem ?? "unknown problem"}`;
 	}
-	const parts = [`server ${context.serverUrl}`];
-	if (context.project) parts.push(`project ${context.project}`);
-	else parts.push("no OneDev project inferred from git remotes");
-	if (context.loginName) parts.push(`user ${context.loginName}`);
+	const parts = [`server ${context.serverUrl}`, `project ${context.project}`];
+	parts.push(context.loginName ? `user ${context.loginName}` : "auth not checked yet");
 	return `OneDev ready: ${parts.join(" · ")}`;
 }
+
+export function setupGuidance(context: OneDevSessionContext): string {
+	switch (context.status) {
+		case "ready":
+			return `${formatContext(context)}\nNo setup action is required.`;
+		case "unavailable":
+		case "not_configured":
+		case "no_project":
+		case "auth_failed":
+			return `${formatContext(context)}\n${context.problem ?? TOD_INSTALL_HINT}`;
+		default:
+			throw new Error(`unsupported OneDev context status: ${String(context.status)}`);
+	}
+}