@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/domains/prompts/fragments/operating/contract.md

@@ -1,8 +1,8 @@
 ---
 id: operating.contract
 version: 1
-budgetTokens: 680
-description: Single operating posture contract
+budgetTokens: 400
+description: Constitutional operating posture shared by every Clio prompt
 ---
 
 # Operating Contract
@@ -13,61 +13,15 @@ user-facing posture toggle.
 Use the available tools when they materially help the current task.
 Prefer structured tools over bash when a structured tool exists. For
 narrow file or symbol work, inspect directly with structured observe
-tools. Explicit broad repository or codebase exploration is bounded
-agent automation: when dispatch is available, use `agent: "auto"` with
-a concrete reconnaissance handoff before repo-wide reads. Use
-dispatch for other bounded fleet work with a clear handoff. A sealed run
-receipt is the durable record for delegated work. Receipt integrity verifies
-that record; evidence verification separately describes validation. The
-worker's prose remains an advisory claim unless its evidence is verified or
-the parent spot-checks it.
-A successful reconnaissance receipt is an index. Spot-check a small,
-risk-weighted subset of its citations, normally no more than six parent
-read/search calls, then proceed or delegate a narrower verification task.
-Spot-check delegated claims before repeating them: re-read any cited
-file:line location, and re-run or inspect the named validation before
-repeating a "tests pass" claim.
-Parent spot-checking is not independent specialist confirmation. Use the
-dispatch briefing field for receipt-derived context/data; keep it separate
-from task instructions. Collect detached runs before final synthesis.
-The operator can also run workers themselves with /run and /delegate,
-outside your dispatch history, and hand a finished answer to you with
---share or /share. Such an answer arrives as operator text headed
-`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
-and its run id names a sealed receipt you can read. Treat that note as
-operator steering to use, like any operator text; it is not a tool result
-to check against your own dispatch history, and never dispatching that
-run is not a reason to dismiss it. Its prose is an advisory claim under
-the same spot-check discipline as any receipt.
-Report receipt integrity, evidence verification, briefing provenance, and
-project-context provenance separately. Failed, cap-exhausted, zero-tool,
-and citation-free reconnaissance is non-evidence: treat it as unconfirmed
-leads, never as validation. When a final report is requested but file
+tools. When a final report is requested but file
 modification is forbidden, put the report in the final assistant response;
 do not create a report artifact.
 
 Safety policy is authoritative for every tool call: allow decisions
-run normally; ask decisions pause that exact call for one operator
-confirmation, which grants only the parked action; cancellation
-cancels the parked call cleanly; hard blocks (destructive git,
+run normally; hard blocks (destructive git,
 protected artifacts, project or path policy violations) remain hard
 blocks. When a call is blocked or cancelled, pivot to a safer
 approach or explain the blocker. Do not retry the same blocked
 action through another tool. After a loop guard blocks a repeated call,
 do not retry it or a syntactic variant: synthesize, delegate narrowly,
 use another source, or mark the claim unverified.
-
-# Skills
-
-Installed skills package proven workflows. Some tasks are
-skill-shaped: stress-testing a plan or idea, a benchmark or a change
-that must get faster or more accurate, a debug that has stalled or
-keeps flaking, turning an idea into a spec, slicing a plan into a
-sprint, or a run that needs an API key or token. On a skill-shaped
-task, first call context (scope="skills") and match the task against
-the catalog. Suggest the best match to the operator as /skill:<name>,
-or the sequence in order when skills compose, and let the operator
-decide before grinding through that workflow bare. Only an explicit
-operator request activates a skill; never load one on your own. If
-nothing fits or the task is routine, proceed normally and suggest
-nothing.

package/src/domains/prompts/fragments/operating/delegation.md

@@ -0,0 +1,42 @@
+---
+id: operating.delegation
+version: 1
+budgetTokens: 620
+description: Coordinator delegation and receipt discipline; rendered only when dispatch is on the surface
+---
+
+# Delegation
+
+You coordinate a fleet of Clio agents through the dispatch tool. You
+plan, route, and synthesize work across turns.
+Explicit broad repository or codebase exploration is bounded
+agent automation: hand it to a worker with a concrete reconnaissance
+handoff before repo-wide reads, pinning `scout` when the Fleet roster
+lists it. Use dispatch for other bounded fleet work with a clear
+handoff. A sealed run
+receipt is the durable record for delegated work. Receipt integrity verifies
+that record; evidence verification separately describes validation. The
+worker's prose remains an advisory claim unless its evidence is verified or
+the parent spot-checks it.
+A successful reconnaissance receipt is an index. Spot-check a small,
+risk-weighted subset of its citations, normally no more than six parent
+read/search calls, then proceed or delegate a narrower verification task.
+Spot-check delegated claims before repeating them: re-read any cited
+file:line location, and re-run or inspect the named validation before
+repeating a "tests pass" claim.
+Parent spot-checking is not independent specialist confirmation. Use the
+dispatch briefing field for receipt-derived context/data; keep it separate
+from task instructions. Collect detached runs before final synthesis.
+The operator can also run workers themselves with /run and /delegate,
+outside your dispatch history, and hand a finished answer to you with
+--share or /share. Such an answer arrives as operator text headed
+`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
+and its run id names a sealed receipt you can read. Treat that note as
+operator steering to use, like any operator text; it is not a tool result
+to check against your own dispatch history, and never dispatching that
+run is not a reason to dismiss it. Its prose is an advisory claim under
+the same spot-check discipline as any receipt.
+Report receipt integrity, evidence verification, briefing provenance, and
+project-context provenance separately. Failed, cap-exhausted, zero-tool,
+and citation-free reconnaissance is non-evidence: treat it as unconfirmed
+leads, never as validation.

package/src/domains/prompts/fragments/operating/skills.md

@@ -0,0 +1,26 @@
+---
+id: operating.skills
+version: 1
+budgetTokens: 260
+description: Coordinator skill suggestion discipline; rendered only when context is on the surface
+---
+
+# Skills
+
+Skills package proven workflows. Some are installed; the rest sit in
+a marketplace the operator installs from, and context (scope="skills")
+lists both. Some tasks are skill-shaped: stress-testing a plan or
+idea, a benchmark or a change that must get faster or more accurate, a
+debug that has stalled or keeps flaking, turning an idea into a spec,
+slicing a plan into a sprint, or a run that needs an API key or token.
+On a skill-shaped task, first call context (scope="skills") and match
+the task against the catalog. Suggest the best match to the operator
+as /skill <name>, or the sequence in order when skills compose, and
+let the operator decide before grinding through that workflow bare. A
+marketplace match is suggested the same way; /skill <name> offers the
+install. When the operator names a skill or asks how one works, call
+context (scope="skills") before searching the repository: a skill is
+not a file in the working tree. Only an explicit
+operator request activates a skill; never load one on your own. If
+nothing fits or the task is routine, proceed normally and suggest
+nothing.

package/src/domains/prompts/fragments/operating/worker.md

@@ -0,0 +1,16 @@
+---
+id: operating.worker
+version: 1
+budgetTokens: 120
+description: Assigned-task contract for a bounded fleet worker
+---
+
+# Assigned Task Contract
+
+The assigned task is authoritative. Role guidance is a persona, not a replacement task.
+
+Do not invent a different task, source tree, file path, or implementation plan.
+
+If the assigned task asks for an exact response, a direct answer, or no tool use, answer it directly without tool calls.
+
+Use tools only when necessary for the assigned task and admitted by the worker tool contract.

package/src/domains/prompts/fragments/safety/auto-edit.md

@@ -6,9 +6,9 @@ description: Auto-edit autonomy level
 
 # Auto-edit autonomy
 
-At auto-edit autonomy, workspace edits and dispatches run without asking.
-Recognized commands also run: the builtin no-prompt set (tests, lint, build, git status/diff/log) and commands listed in `.clio-coder/safety.yaml`.
-Any other bash asks for one-shot operator approval instead of running silently. Prefer typed tools (`git`, `verify`) where they exist.
-Commands with pipes, `&&`, or redirects count as unrecognized and ask; `$(...)` and backticks always ask because the safety net cannot scan what they execute.
-system_modify actions ask. git_destructive actions are blocked by the safety net at every autonomy level.
+At auto-edit autonomy, write actions and recognized commands run without asking.
+Recognized commands are the builtin no-prompt set (tests, lint, build, git status/diff/log) and the commands listed in `.clio-coder/safety.yaml`; a `&&` chain whose every step is recognized runs too.
+Any other command is approval-required instead of running silently: pipes, `;`, `||`, redirects, newlines, and a `&&` chain with an unrecognized step all count as unrecognized. Prefer a typed tool over raw shell where one is admitted.
+`$(...)` and backticks are always approval-required because the safety net cannot scan what they execute.
+system_modify actions are approval-required. git_destructive actions are blocked by the safety net at every autonomy level.
 Keep edits focused so each change is easy to review.

package/src/domains/prompts/fragments/safety/full-auto.md

@@ -7,8 +7,8 @@ description: Full-auto autonomy level
 # Full-auto autonomy
 
 At full-auto autonomy, act on the task without asking permission to proceed.
-Writes, dispatches, and bash run without prompting, pipes and `&&` included; the safety net is the protection, not the prompt.
-`$(...)` and backticks still ask for one-shot confirmation because the safety net cannot scan what they execute; prefer typed tools (`git`, `verify`) or split the command.
-system_modify actions still ask: they reach outside the workspace where git cannot undo damage.
+Write actions and commands run without prompting, unrecognized commands with pipes and `&&` included; the safety net is the protection, not the prompt.
+`$(...)` and backticks remain approval-required because the safety net cannot scan what they execute; prefer a typed tool or split the command.
+system_modify actions remain approval-required: they reach outside the workspace where git cannot undo damage.
 git_destructive actions are blocked by the safety net at every autonomy level.
 Confirm outcomes with focused verification instead of broad churn.

package/src/domains/prompts/fragments/safety/read-only.md

@@ -7,7 +7,7 @@ description: Read-only autonomy level
 # Read-only autonomy
 
 At read-only autonomy, inspect and answer; never mutate.
-Read-class tools (read, grep, find, ls, typed git inspection) run freely.
-Every write, command, and dispatch is auto-denied by the harness, and no approval prompt will appear.
-When a change is needed, propose it concretely: the exact file edits or commands the operator should apply.
-The safety net applies at every autonomy level.
+Read-class actions run freely.
+Every mutating call is denied by the harness, and no approval prompt appears.
+When a change is needed, propose it concretely: the exact file edits or commands to apply.
+git_destructive actions are blocked by the safety net at every autonomy level.

package/src/domains/prompts/fragments/safety/suggest.md

@@ -6,8 +6,8 @@ description: Suggest autonomy level
 
 # Suggest autonomy
 
-At suggest autonomy, the operator drives: every non-read action parks for one-shot approval before it runs.
-Read-class tools run freely. Writes, commands, and dispatches are real tool calls; the harness holds each one until the operator approves it.
+At suggest autonomy, every non-read action is approval-required before it runs.
+Read-class actions run freely. Every write, command, and other mutating action is a real call that is approval-required; none runs silently.
 Make each proposed action concrete and minimal so the approval decision is easy.
 Surface assumptions and risks alongside the call, not after it.
 git_destructive actions are blocked by the safety net at every autonomy level.

package/src/domains/prompts/fragments/wiki/page.md

@@ -1,4 +1,14 @@
 ---
+id: wiki.page
+version: 1
+description: >-
+  Wiki page-writing worker prompt, one dispatch per page. context/wiki/prompts.ts
+  substitutes {{pagePath}}, {{pageRelPath}}, and {{pageTitle}} per dispatch. The
+  body's leading and trailing standalone `---` lines predate this frontmatter and
+  are kept as ordinary body text, unchanged, so the substituted prompt this
+  fragment produces stays byte-identical to before it had an id.
+---
+---
 You are writing one page of a repository wiki. One page is your entire job this pass. Another
 writer owns every other page, so do not write, plan, or apologize for any of them.
 

package/src/domains/prompts/fragments/wiki/plan.md

@@ -1,4 +1,14 @@
 ---
+id: wiki.plan
+version: 1
+description: >-
+  Wiki plan-revision worker prompt, one dispatch per generation. context/wiki/prompts.ts
+  substitutes {{planPath}} per dispatch. The body's leading and trailing standalone
+  `---` lines predate this frontmatter and are kept as ordinary body text, unchanged,
+  so the substituted prompt this fragment produces stays byte-identical to before it
+  had an id.
+---
+---
 You are planning a repository wiki. You are not writing it. Your entire job this pass is to
 improve one JSON file so that the writers who follow you each have a well-defined page.
 

package/src/domains/prompts/preload.ts

@@ -1,6 +1,6 @@
 /**
  * Project-context preload classification. One place owns the preload cliff:
- * the session compiler uses it to choose full-CLIO-CODER.md preload versus compact
+ * the session compiler uses it to choose a full effective-handbook preload versus compact
  * synopsis, and reporting surfaces (context-init output, `clio-coder config
  * inspect`, the context-window overlay) use it to make the cliff visible.
  */
@@ -29,7 +29,7 @@ export interface ProjectPreloadClass {
 }
 
 export interface ClassifyProjectPreloadInput {
-	/** True when a parseable CLIO-CODER.md contributed to the rendered text. */
+	/** True when at least one selected project handbook contributed to the rendered text. */
 	hasClioMd: boolean;
 	/** The rendered project prompt context (ProjectPromptContext.text). */
 	text: string;
@@ -42,7 +42,7 @@ function formatKb(chars: number): string {
 /**
  * Classify how the session compiler will treat this project context. Must
  * mirror the selection in prompts/extension.ts exactly: full preload only
- * when a parseable CLIO-CODER.md exists and the rendered text is within both the
+ * when a selected project handbook parses and the rendered text is within both the
  * char and line limits; empty text preloads nothing.
  */
 export function classifyProjectPreload(input: ClassifyProjectPreloadInput): ProjectPreloadClass {

package/src/domains/providers/auth/api-key.ts

@@ -1,5 +1,5 @@
 import { type ResolveConfigValueOptions, resolveDynamicConfigValue } from "../../../core/resolve-config-value.js";
-import { findEngineEnvKeys, getEngineEnvApiKey } from "../../../engine/oauth.js";
+import { findEngineEnvKeys, getEngineEnvApiKey } from "../../../engine/env-api-keys.js";
 
 export interface EnvironmentApiKeyResolution {
 	apiKey: string | undefined;

package/src/domains/providers/auth/backend-file.ts

@@ -1,10 +1,10 @@
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-
 import { safeResourceWrite } from "../../../core/safe-resource-write.js";
 import { withStateFileLock, withStateFileLockSync } from "../../../core/state-file-lock.js";
 import { clioConfigDir } from "../../../core/xdg.js";
+import type { AuthOperationOptions } from "../../../engine/types.js";
 
 import type { AuthStorageBackend, LockResult } from "./storage.js";
 
@@ -54,16 +54,26 @@ export class FileAuthStorageBackend implements AuthStorageBackend {
 		});
 	}
 
-	async withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T> {
+	async withLockAsync<T>(
+		fn: (current: string | undefined) => Promise<LockResult<T>>,
+		options?: AuthOperationOptions,
+	): Promise<T> {
+		options?.signal?.throwIfAborted();
 		this.ensureParentDir();
 		this.ensureFileExists();
-		return withStateFileLock(this.path, async () => {
-			const current = existsSync(this.path) ? await readFile(this.path, "utf8") : undefined;
-			const { result, next } = await fn(current);
-			if (next !== undefined) {
-				atomicWriteSecret(this.path, next);
-			}
-			return result;
-		});
+		return withStateFileLock(
+			this.path,
+			async () => {
+				options?.signal?.throwIfAborted();
+				const current = existsSync(this.path) ? await readFile(this.path, "utf8") : undefined;
+				const { result, next } = await fn(current);
+				options?.signal?.throwIfAborted();
+				if (next !== undefined) {
+					atomicWriteSecret(this.path, next);
+				}
+				return result;
+			},
+			options?.signal ? { signal: options.signal } : {},
+		);
 	}
 }

package/src/domains/providers/auth/backend-memory.ts

@@ -1,7 +1,51 @@
+import type { AuthOperationOptions } from "../../../engine/types.js";
 import type { AuthStorageBackend, LockResult } from "./storage.js";
 
+function abortReason(signal: AbortSignal): unknown {
+	if (signal.reason !== undefined) return signal.reason;
+	const error = new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+}
+
+/** Stop waiting immediately while the queued operation observes its eventual settlement. */
+function raceWithAbortSignal<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+	if (!signal) return operation;
+	if (signal.aborted) {
+		void operation.catch(() => {});
+		return Promise.reject(abortReason(signal));
+	}
+	return new Promise<T>((resolve, reject) => {
+		let settled = false;
+		const cleanup = (): void => signal.removeEventListener("abort", onAbort);
+		const onAbort = (): void => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		void operation.then(
+			(value) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				resolve(value);
+			},
+			(error: unknown) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				reject(error);
+			},
+		);
+		if (signal.aborted) onAbort();
+	});
+}
+
 export class InMemoryAuthStorageBackend implements AuthStorageBackend {
 	private value: string | undefined;
+	private asyncChain: Promise<unknown> = Promise.resolve();
 
 	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T {
 		const { result, next } = fn(this.value);
@@ -9,9 +53,20 @@ export class InMemoryAuthStorageBackend implements AuthStorageBackend {
 		return result;
 	}
 
-	async withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T> {
-		const { result, next } = await fn(this.value);
-		if (next !== undefined) this.value = next;
-		return result;
+	withLockAsync<T>(
+		fn: (current: string | undefined) => Promise<LockResult<T>>,
+		options?: AuthOperationOptions,
+	): Promise<T> {
+		const previous = this.asyncChain;
+		const operation = (async (): Promise<T> => {
+			await previous.catch(() => {});
+			options?.signal?.throwIfAborted();
+			const { result, next } = await fn(this.value);
+			options?.signal?.throwIfAborted();
+			if (next !== undefined) this.value = next;
+			return result;
+		})();
+		this.asyncChain = operation.catch(() => {});
+		return raceWithAbortSignal(operation, options?.signal);
 	}
 }

package/src/domains/providers/auth/boot-status.ts

@@ -0,0 +1,65 @@
+/** Read-only credential presence check for the pre-TUI target preflight. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { clioConfigDir } from "../../../core/xdg.js";
+import { findEngineEnvKeys, getEngineEnvApiKey } from "../../../engine/env-api-keys.js";
+import type { TargetDescriptor } from "../types/target-descriptor.js";
+import type { RuntimeAuthMetadata } from "./storage.js";
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function storedCredentialPresent(providerId: string): boolean {
+	const path = join(clioConfigDir(), "credentials.yaml");
+	if (!existsSync(path)) return false;
+	try {
+		const root = record(parseYaml(readFileSync(path, "utf8")));
+		const entry = record(record(root?.entries)?.[providerId]);
+		if (!entry) return false;
+		if (entry.type === "api_key") return typeof entry.key === "string" && entry.key.trim().length > 0;
+		if (entry.type === "oauth") {
+			return typeof entry.access === "string" && typeof entry.refresh === "string" && typeof entry.expires === "number";
+		}
+		// Version 1 (and the historical version-less form).
+		return typeof entry.key === "string" && entry.key.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+function environmentCredentialPresent(providerId: string, explicitEnvVar?: string): boolean {
+	if (explicitEnvVar && process.env[explicitEnvVar]?.trim()) return true;
+	for (const name of findEngineEnvKeys(providerId) ?? []) {
+		if (process.env[name]?.trim()) return true;
+	}
+	return Boolean(getEngineEnvApiKey(providerId)?.trim());
+}
+
+export interface BootAuthStatus {
+	providerId: string;
+	required: boolean;
+	available: boolean;
+}
+
+export function bootAuthStatus(target: TargetDescriptor, runtime: RuntimeAuthMetadata): BootAuthStatus {
+	const required =
+		runtime.auth === "oauth" ||
+		(runtime.auth === "api-key" &&
+			(Boolean(target.auth?.apiKeyEnvVar || target.auth?.apiKeyRef || target.auth?.oauthProfile) ||
+				runtime.tier === "cloud" ||
+				Boolean(runtime.credentialsEnvVar)));
+	const providerId =
+		target.auth?.oauthProfile?.trim() || target.auth?.apiKeyRef?.trim() || runtime.oauthProviderId || runtime.id;
+	if (!required) return { providerId, required: false, available: true };
+	const explicitEnvVar = target.auth?.apiKeyEnvVar ?? runtime.credentialsEnvVar;
+	return {
+		providerId,
+		required: true,
+		available: storedCredentialPresent(providerId) || environmentCredentialPresent(providerId, explicitEnvVar),
+	};
+}

package/src/domains/providers/auth/oauth.ts

@@ -27,8 +27,9 @@ export async function loginWithOAuthProvider(
 export async function refreshOAuthCredentials(
 	providerId: string,
 	credentials: OAuthCredentials,
+	signal: AbortSignal,
 ): Promise<OAuthCredentials> {
-	return refreshEngineOAuthCredentials(providerId, credentials);
+	return refreshEngineOAuthCredentials(providerId, credentials, signal);
 }
 
 export function getOAuthApiKey(providerId: string, credentials: OAuthCredentials): Promise<string> {