@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/async/job-manager.ts

@@ -6,6 +6,27 @@ const DELIVERY_RETRY_JITTER_MS = 200;
 const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_RUNNING_JOBS = 15;
 
+/**
+ * Adaptive ("smart") `job` poll-wait ladder (ms). A tight poll loop climbs
+ * these rungs so each immediate re-poll backs off and stops spending turns on
+ * "still running" frames; the floor (first rung) is the shortest wait and the
+ * top rung is the longest a smart poll will ever block. Only used when
+ * `async.pollWaitDuration` is set to `smart`; fixed durations wait verbatim.
+ */
+const POLL_WAIT_LADDER_MS = [5_000, 10_000, 30_000, 60_000, 300_000] as const;
+/**
+ * Going at least this long between poll calls means the agent stepped out of
+ * the poll loop to do real work — the next poll drops back to the ladder floor.
+ */
+const POLL_ESCALATION_RESET_MS = 60_000;
+
+interface PollEscalationState {
+	/** Index into POLL_WAIT_LADDER_MS used for the most recent poll wait. */
+	level: number;
+	/** Timestamp (ms) when the most recent poll wait returned. */
+	lastPollEndAt: number;
+}
+
 export interface AsyncJob {
 	id: string;
 	type: "bash" | "task";
@@ -23,6 +44,12 @@ export interface AsyncJob {
 	 * supply an id (e.g. legacy tests, SDK consumers without an agent context).
 	 */
 	ownerId?: string;
+	/**
+	 * Job is registered but parked behind a caller-managed gate (e.g. a task
+	 * batch semaphore). Queued jobs do not count toward the running-job limit
+	 * until the caller invokes `markRunning()` from the run context.
+	 */
+	queued?: boolean;
 }
 
 export interface AsyncJobManagerOptions {
@@ -53,6 +80,8 @@ export interface AsyncJobRegisterOptions {
 	/** Registry id of the agent that owns this job; used to scope cancelAll. */
 	ownerId?: string;
 	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+	/** Register the job in queued state; see {@link AsyncJob.queued}. */
+	queued?: boolean;
 }
 
 /**
@@ -88,6 +117,7 @@ export class AsyncJobManager {
 	readonly #suppressedDeliveries = new Set<string>();
 	readonly #watchedJobs = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #pollEscalation = new Map<string | undefined, PollEscalationState>();
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
 	readonly #retentionMs: number;
@@ -110,6 +140,17 @@ export class AsyncJobManager {
 		this.#retentionMs = Math.max(0, Math.floor(options.retentionMs ?? DEFAULT_RETENTION_MS));
 	}
 
+	/** True when the running-job count has reached the configured cap. */
+	get atCapacity(): boolean {
+		if (this.#disposed) return true;
+		// Mirror register(): queued jobs hold no execution slot.
+		let activeCount = 0;
+		for (const job of this.#jobs.values()) {
+			if (job.status === "running" && !job.queued) activeCount++;
+		}
+		return activeCount >= this.#maxRunningJobs;
+	}
+
 	register(
 		type: "bash" | "task",
 		label: string,
@@ -117,14 +158,21 @@ export class AsyncJobManager {
 			jobId: string;
 			signal: AbortSignal;
 			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+			/** Clear the queued flag once the job actually starts executing. */
+			markRunning: () => void;
 		}) => Promise<string>,
 		options?: AsyncJobRegisterOptions,
 	): string {
 		if (this.#disposed) {
 			throw new Error("Async job manager is disposed");
 		}
-		const runningCount = this.getRunningJobs().length;
-		if (runningCount >= this.#maxRunningJobs) {
+		// Queued jobs hold no execution slot yet — only count jobs that are
+		// actually running so a large parked batch cannot starve registration.
+		let activeCount = 0;
+		for (const existing of this.#jobs.values()) {
+			if (existing.status === "running" && !existing.queued) activeCount++;
+		}
+		if (activeCount >= this.#maxRunningJobs) {
 			throw new Error(
 				`Background job limit reached (${this.#maxRunningJobs}). Wait for running jobs to finish or cancel one.`,
 			);
@@ -144,6 +192,7 @@ export class AsyncJobManager {
 			abortController,
 			promise: Promise.resolve(),
 			ownerId: options?.ownerId,
+			queued: options?.queued === true,
 		};
 
 		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
@@ -159,7 +208,14 @@ export class AsyncJobManager {
 		};
 		job.promise = (async () => {
 			try {
-				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				const text = await run({
+					jobId: id,
+					signal: abortController.signal,
+					reportProgress,
+					markRunning: () => {
+						job.queued = false;
+					},
+				});
 				if (job.status === "cancelled") {
 					job.resultText = text;
 					this.#scheduleEviction(id);
@@ -261,6 +317,32 @@ export class AsyncJobManager {
 		return removed;
 	}
 
+	/**
+	 * Compute the next adaptive ("smart") wait (ms) for a blocking `job` poll by
+	 * the given owner. Consecutive polls — those starting within
+	 * POLL_ESCALATION_RESET_MS of the previous poll returning — climb
+	 * POLL_WAIT_LADDER_MS so a tight wait loop backs off; a longer gap means the
+	 * agent left to do real work, so the wait resets to the floor. Pair each call
+	 * with `recordPollWaitEnd()` once the wait returns.
+	 */
+	nextPollWaitMs(ownerId: string | undefined, now: number = Date.now()): number {
+		const prev = this.#pollEscalation.get(ownerId);
+		const reset = !prev || now - prev.lastPollEndAt >= POLL_ESCALATION_RESET_MS;
+		const level = reset ? 0 : Math.min(prev.level + 1, POLL_WAIT_LADDER_MS.length - 1);
+		this.#pollEscalation.set(ownerId, { level, lastPollEndAt: prev?.lastPollEndAt ?? now });
+		return POLL_WAIT_LADDER_MS[level];
+	}
+
+	/**
+	 * Mark a blocking poll wait as finished so the idle-reset window is measured
+	 * from now. Polling again before POLL_ESCALATION_RESET_MS elapses keeps
+	 * climbing the ladder; waiting longer resets it to the floor.
+	 */
+	recordPollWaitEnd(ownerId: string | undefined, now: number = Date.now()): void {
+		const prev = this.#pollEscalation.get(ownerId);
+		this.#pollEscalation.set(ownerId, { level: prev?.level ?? 0, lastPollEndAt: now });
+	}
+
 	acknowledgeDeliveries(jobIds: string[]): number {
 		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
 		if (uniqueJobIds.length === 0) return 0;
@@ -278,6 +360,26 @@ export class AsyncJobManager {
 		return before - this.#deliveries.length;
 	}
 
+	/**
+	 * Lift a foreground-wait suppression set via `acknowledgeDeliveries`. If the
+	 * job already finished while suppressed (its delivery enqueue was skipped),
+	 * re-enqueue the completion so the result is still delivered exactly once.
+	 */
+	resumeDeliveries(jobIds: string[]): void {
+		for (const rawId of jobIds) {
+			const jobId = rawId.trim();
+			if (!jobId) continue;
+			if (!this.#suppressedDeliveries.delete(jobId)) continue;
+			const job = this.#jobs.get(jobId);
+			if (!job || (job.status !== "completed" && job.status !== "failed")) continue;
+			const queued =
+				this.#deliveries.some(delivery => delivery.jobId === jobId) ||
+				this.#inFlightDeliveries.some(delivery => delivery.jobId === jobId);
+			if (queued) continue;
+			this.#enqueueDelivery(jobId, job.status === "completed" ? (job.resultText ?? "") : (job.errorText ?? ""));
+		}
+	}
+
 	/**
 	 * Cancel running jobs. With `filter.ownerId` set, cancels only jobs the
 	 * matching agent registered; with no filter, cancels every running job
@@ -351,6 +453,7 @@ export class AsyncJobManager {
 		this.#inFlightDeliveries.length = 0;
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
+		this.#pollEscalation.clear();
 		return drained;
 	}
 

package/src/auto-thinking/classifier.ts

@@ -15,6 +15,7 @@
  */
 import { type AssistantMessage, completeSimple, Effort, type Model } from "@prometheus-ai/ai";
 import { prompt } from "@prometheus-ai/utils";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -82,7 +83,7 @@ async function classifyOnline(input: string, deps: ClassifyDifficultyDeps): Prom
 			messages: [{ role: "user", content: input, timestamp: Date.now() }],
 		},
 		{
-			apiKey,
+			apiKey: deps.registry.resolver(model, deps.sessionId),
 			maxTokens,
 			disableReasoning: true,
 			metadata,

package/src/autolearn/controller.ts

@@ -0,0 +1,139 @@
+/**
+ * Auto-learn session controller (experimental).
+ *
+ * Subscribes to the session event stream and, after a substantive turn,
+ * nudges the agent to capture reusable lessons. Default posture is passive
+ * (a hidden reminder rides the next real turn); with `autolearn.autoContinue`
+ * it auto-runs exactly one synthetic capture turn at stop.
+ *
+ * Installed once per top-level session (taskDepth 0). The subscription lives
+ * for the session's lifetime — `newSession` resets the session in place
+ * without re-running startup — so the controller needs no disposal.
+ */
+import { logger } from "@prometheus-ai/utils";
+import type { Settings } from "../config/settings";
+import autolearnGuidance from "../prompts/system/autolearn-guidance.md" with { type: "text" };
+import autolearnGuidanceLearn from "../prompts/system/autolearn-guidance-learn.md" with { type: "text" };
+import autolearnNudge from "../prompts/system/autolearn-nudge.md" with { type: "text" };
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+
+const AUTOLEARN_NUDGE = autolearnNudge.trim();
+const DEFAULT_MIN_TOOL_CALLS = 5;
+
+/**
+ * Build the standing auto-learn guidance for the system prompt from the tools
+ * actually present in the active set, or null when `manage_skill` is absent.
+ *
+ * Driven by tool presence rather than live settings: the `learn`/`manage_skill`
+ * registry is built ONCE at session start (and only for top-level sessions), so
+ * keying the guidance on `autolearn.enabled` would let a mid-session enable — or
+ * a subagent that filtered the tools out — inject guidance pointing at tools the
+ * session never built. The `learn` addendum is included only when the `learn`
+ * tool is present (it requires a memory backend).
+ */
+export function buildAutoLearnInstructions(available: { manageSkill: boolean; learn: boolean }): string | null {
+	if (!available.manageSkill) return null;
+	const parts = [autolearnGuidance.trim()];
+	if (available.learn) parts.push(autolearnGuidanceLearn.trim());
+	return parts.join("\n\n");
+}
+
+export interface AutoLearnControllerOptions {
+	session: AgentSession;
+	settings: Settings;
+}
+
+export class AutoLearnController {
+	readonly #session: AgentSession;
+	readonly #settings: Settings;
+	#toolCalls = 0;
+	/**
+	 * Whether the in-flight turn BEGAN while goal mode was active. Captured at
+	 * agent_start because a `goal` tool can complete or drop the goal mid-turn,
+	 * clearing the live flag before agent_end — so the end-of-turn state alone
+	 * would let a goal-continuation turn slip through and get nudged.
+	 */
+	#turnStartedInGoalMode = false;
+	/** Swallow the agent_end produced by an auto-run capture turn so it cannot re-trigger. */
+	#suppressNext = false;
+
+	constructor(options: AutoLearnControllerOptions) {
+		this.#session = options.session;
+		this.#settings = options.settings;
+		// The listener closure captures `this`, so the session's listener array
+		// keeps the controller alive — no stored unsubscribe needed.
+		this.#session.subscribe(event => this.#onEvent(event));
+	}
+
+	#onEvent(event: AgentSessionEvent): void {
+		if (event.type === "agent_start") {
+			// Capture goal-mode state at the turn boundary, before any tool runs.
+			this.#turnStartedInGoalMode = this.#session.getGoalModeState()?.enabled === true;
+			return;
+		}
+		if (event.type === "tool_execution_end") {
+			this.#toolCalls++;
+			return;
+		}
+		if (event.type === "agent_end") {
+			this.#onAgentEnd();
+		}
+	}
+
+	#onAgentEnd(): void {
+		// Snapshot and reset every turn: the counter describes only the
+		// just-finished turn, so below-threshold, disabled, and plan-mode stops
+		// must not let tool calls accumulate into a later turn.
+		const toolCalls = this.#toolCalls;
+		this.#toolCalls = 0;
+		// Snapshot the turn-start goal flag alongside the counter so a turn that
+		// observed no agent_start can never inherit a stale value.
+		const startedInGoalMode = this.#turnStartedInGoalMode;
+		this.#turnStartedInGoalMode = false;
+
+		if (this.#suppressNext) {
+			this.#suppressNext = false;
+			return;
+		}
+		// Honor a live opt-out: the subscription outlives the setting, so re-check
+		// the current flag rather than trusting install-time state.
+		if (!this.#settings.get("autolearn.enabled")) return;
+		const minToolCalls = this.#settings.get("autolearn.minToolCalls") ?? DEFAULT_MIN_TOOL_CALLS;
+		if (toolCalls < minToolCalls) return;
+		// Never interrupt plan-mode review.
+		if (this.#session.getPlanModeState()?.enabled) return;
+		// Never divert a goal loop. Skip when the turn STARTED in goal mode — a
+		// `goal` tool may have completed/dropped the goal before this stop — or is
+		// still in it: a passive nudge would ride the goal continuation, and
+		// auto-continue would compete with it.
+		if (startedInGoalMode || this.#session.getGoalModeState()?.enabled) return;
+
+		// Auto-run a capture turn only when explicitly enabled; otherwise the
+		// hidden reminder rides the next real turn passively.
+		const autoContinue = this.#settings.get("autolearn.autoContinue") === true;
+		// Arm suppression synchronously: the synthetic capture turn's agent_end
+		// fires inside sendCustomMessage (before it resolves), so the flag must be
+		// set before then. Disarm when no turn actually started — a deferred/queued
+		// dispatch or a failed send produces no agent_end, and a latched flag would
+		// otherwise swallow the next real stop.
+		if (autoContinue) this.#suppressNext = true;
+
+		this.#session
+			.sendCustomMessage(
+				{
+					customType: "autolearn-nudge",
+					content: AUTOLEARN_NUDGE,
+					display: false,
+					attribution: "user",
+				},
+				{ deliverAs: "nextTurn", triggerTurn: autoContinue },
+			)
+			.then(started => {
+				if (!started) this.#suppressNext = false;
+			})
+			.catch(err => {
+				this.#suppressNext = false;
+				logger.warn("auto-learn nudge delivery failed", { err });
+			});
+	}
+}

package/src/autolearn/managed-skills.ts

@@ -0,0 +1,257 @@
+/**
+ * Managed-skills primitives for the experimental auto-learn feature.
+ *
+ * Managed skills are auto-generated/enhanced `SKILL.md` files kept in an
+ * isolated directory (`~/.prometheus/agent/managed-skills`) separate from
+ * user-authored skills (`~/.prometheus/agent/skills`). They are discovered and
+ * surfaced like normal skills, but every write here is confined to
+ * `getManagedSkillsDir()` — auto-management can never touch authored skills.
+ */
+import { constants as fsConstants, type Stats } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@prometheus-ai/utils";
+import { YAML } from "bun";
+import { SOURCE_PATHS } from "../discovery/helpers";
+
+/** Provider id stamped on discovered managed skills (distinguishes them from authored). */
+export const MANAGED_SKILLS_PROVIDER_ID = "prometheus-managed";
+
+/** Hard cap on a managed SKILL.md body to keep generated skills bounded. */
+export const MAX_MANAGED_SKILL_BYTES = 64_000;
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Resolve the isolated managed-skills directory (`~/.prometheus/agent/managed-skills`). */
+export function getManagedSkillsDir(home: string = os.homedir()): string {
+	return path.join(home, SOURCE_PATHS.native.userAgent, "managed-skills");
+}
+
+/**
+ * Validate + normalize a managed-skill name. Throws on anything outside the
+ * strict allowlist so a bad name can never escape `getManagedSkillsDir()`
+ * (blocks `..`, slashes, empty, and uppercase).
+ */
+export function sanitizeSkillName(raw: string): string {
+	const name = raw.trim().toLowerCase();
+	if (!SKILL_NAME_PATTERN.test(name)) {
+		throw new Error(
+			`Invalid skill name "${raw}". Use lowercase letters, digits, and hyphens (1-64 chars, starting with a letter or digit).`,
+		);
+	}
+	return name;
+}
+
+/**
+ * Whether `name` is a safe managed-skill name (the exact post-sanitize shape).
+ * Used to validate names read from disk at discovery time — a managed
+ * `SKILL.md` whose `frontmatter.name` was not produced by `sanitizeSkillName`
+ * (e.g. hand-placed) must not render unescaped into the system prompt.
+ */
+export function isValidManagedSkillName(name: string): boolean {
+	return SKILL_NAME_PATTERN.test(name);
+}
+
+/**
+ * Neutralize a machine-generated managed-skill description so it cannot break
+ * out of the system prompt's `<skills>` listing. Managed descriptions are
+ * generated from prior task content and persist across sessions, so this is a
+ * trust boundary: strip control/format chars, angle brackets (`<system-directive>`
+ * / `</skills>`), and Markdown fence delimiters (backticks, `~~~`), then collapse
+ * to a single line. Applied on BOTH write and read so existing files are safe too.
+ */
+export function sanitizeManagedDescription(raw: string): string {
+	return raw
+		.replace(/[\p{Cc}\p{Cf}]/gu, " ")
+		.replace(/[<>`]/g, "")
+		.replace(/~{2,}/g, "~")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Serialize the minimal `name`/`description` frontmatter block via the repo's
+ * YAML helper (round-trips through `parseFrontmatter`).
+ */
+export function toSkillFrontmatter(name: string, description: string): string {
+	const frontmatter = YAML.stringify(
+		{ name, description: sanitizeManagedDescription(description) },
+		null,
+		2,
+	).trimEnd();
+	return `---\n${frontmatter}\n---\n`;
+}
+
+export interface WriteManagedSkillInput {
+	action: "create" | "update";
+	name: string;
+	description: string;
+	body: string;
+}
+
+/**
+ * Serialize create/update/delete on the same skill name. Both tools are
+ * non-exclusive, so a parallel tool batch in one turn can run two mutations on
+ * the same skill at once (e.g. an update observing the file mid-delete). This
+ * per-name promise chain runs same-skill mutations in submission order while
+ * different names still proceed in parallel. In-process only; cross-process
+ * races are out of scope.
+ */
+const skillMutationChains = new Map<string, Promise<unknown>>();
+function serializeSkillMutation<T>(name: string, op: () => Promise<T>): Promise<T> {
+	const prev = skillMutationChains.get(name) ?? Promise.resolve();
+	const run = prev.then(op, op);
+	const guarded = run.catch(() => {});
+	skillMutationChains.set(name, guarded);
+	void guarded.finally(() => {
+		if (skillMutationChains.get(name) === guarded) skillMutationChains.delete(name);
+	});
+	return run;
+}
+
+/**
+ * Reject when the managed-skills root itself is a symlink. lstat on a child
+ * follows intermediate components, so a symlinked root would let an otherwise
+ * valid name write/delete outside the isolated directory (e.g. onto authored
+ * skills). Checked before composing any child path.
+ */
+async function assertManagedRootSafe(): Promise<void> {
+	const rootStat = await fs.lstat(getManagedSkillsDir()).catch(err => {
+		if (isEnoent(err)) return null;
+		throw err;
+	});
+	if (rootStat?.isSymbolicLink()) {
+		throw new Error("The managed-skills root is a symlink; refusing to operate outside the managed directory.");
+	}
+}
+
+const UPDATE_FILE_OPEN_FLAGS = fsConstants.O_WRONLY | fsConstants.O_NOFOLLOW;
+
+function assertManagedSkillFileSafeForUpdate(name: string, fileStat: Stats): void {
+	if (!fileStat.isFile()) {
+		throw new Error(`Managed skill "${name}" SKILL.md is not a regular file; refusing to overwrite it.`);
+	}
+	if (fileStat.nlink > 1) {
+		throw new Error(
+			`Managed skill "${name}" SKILL.md has ${fileStat.nlink} hard links; refusing to overwrite a file that may be user-authored elsewhere.`,
+		);
+	}
+}
+
+async function openManagedSkillFileForUpdate(name: string, file: string) {
+	try {
+		return await fs.open(file, UPDATE_FILE_OPEN_FLAGS);
+	} catch (err) {
+		if ((err as { code?: string }).code === "ELOOP") {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		throw err;
+	}
+}
+
+/** Create or update a managed `SKILL.md`. Returns the resolved file path. */
+export async function writeManagedSkill(input: WriteManagedSkillInput): Promise<{ path: string }> {
+	const name = sanitizeSkillName(input.name);
+	const description = sanitizeManagedDescription(input.description);
+	const body = input.body.trim();
+	// Reject empty content: an all-whitespace/control description sanitizes to ""
+	// and the `requireDescription` discovery scan then silently drops the skill,
+	// so the tool would report success for a skill that never appears.
+	if (!description) {
+		throw new Error(`Managed skill "${name}" needs a non-empty description.`);
+	}
+	if (!body) {
+		throw new Error(`Managed skill "${name}" needs a non-empty body.`);
+	}
+	const content = `${toSkillFrontmatter(name, description)}\n${body}\n`;
+	// Cap the UTF-8 byte size of the FINAL file (body + description + frontmatter),
+	// not the UTF-16 code-unit length of the body alone.
+	const bytes = Buffer.byteLength(content, "utf8");
+	if (bytes > MAX_MANAGED_SKILL_BYTES) {
+		throw new Error(
+			`Managed skill is ${bytes} bytes; the limit is ${MAX_MANAGED_SKILL_BYTES}. Trim the body or description.`,
+		);
+	}
+	return serializeSkillMutation(name, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), name);
+		const file = path.join(dir, "SKILL.md");
+		// Reject a symlinked skill directory: an intermediate symlink would let the
+		// write escape the isolated managed root. lstat does not follow the final
+		// component, so a symlinked `dir` is caught here.
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(
+				`Managed skill "${name}" resolves through a symlink; refusing to write outside the managed directory.`,
+			);
+		}
+		if (input.action === "create") {
+			await fs.mkdir(dir, { recursive: true });
+			// O_CREAT|O_EXCL ("wx"): atomic create that fails if the file already
+			// exists (closing the check-then-write race) and refuses a symlinked SKILL.md.
+			try {
+				await fs.writeFile(file, content, { flag: "wx" });
+			} catch (err) {
+				if ((err as { code?: string }).code === "EEXIST") {
+					throw new Error(`Managed skill "${name}" already exists. Use action "update" to change it.`);
+				}
+				throw err;
+			}
+			return { path: file };
+		}
+		// update: the file must already exist, be a plain managed file, and must
+		// not share an inode with a user-authored file via hard link. Open the
+		// checked file handle before truncating so a path swap after lstat cannot
+		// redirect the write into a symlink or newly hard-linked target.
+		const fileStat = await fs.lstat(file).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (fileStat === null) {
+			throw new Error(`Managed skill "${name}" does not exist. Use action "create" to add it.`);
+		}
+		if (fileStat.isSymbolicLink()) {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		assertManagedSkillFileSafeForUpdate(name, fileStat);
+		const handle = await openManagedSkillFileForUpdate(name, file);
+		try {
+			const openStat = await handle.stat();
+			assertManagedSkillFileSafeForUpdate(name, openStat);
+			await handle.truncate(0);
+			await handle.writeFile(content);
+		} finally {
+			await handle.close();
+		}
+		return { path: file };
+	});
+}
+
+/** Delete a managed skill directory. Throws when it does not exist. */
+export async function deleteManagedSkill(name: string): Promise<void> {
+	const safe = sanitizeSkillName(name);
+	await serializeSkillMutation(safe, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), safe);
+		// Refuse to follow a symlinked skill directory (rm would delete the target).
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(`Managed skill "${safe}" is a symlink; refusing to delete outside the managed directory.`);
+		}
+		try {
+			await fs.rm(dir, { recursive: true });
+		} catch (err) {
+			if (isEnoent(err)) {
+				throw new Error(`Managed skill "${safe}" does not exist.`);
+			}
+			throw err;
+		}
+	});
+}

package/src/autoresearch/dashboard.ts

@@ -66,7 +66,7 @@ export function createDashboardController(): DashboardController {
 
 					let scrollOffset = 0;
 					return {
-						render(width: number): string[] {
+						render(width: number): readonly string[] {
 							const terminalRows = process.stdout.rows ?? 40;
 							const header = renderExpandedHeader(runtime, width, theme);
 							const body = renderDashboardLines(runtime, width, theme, 0);

package/src/autoresearch/prompt-setup.md

@@ -18,16 +18,16 @@ Working directory: `{{working_dir}}`
 {{baseline_warning}}
 {{/if}}
 
-### What you must produce
+### What you MUST produce
 
-Write `./autoresearch.sh` at the working directory. It is the canonical benchmark entrypoint and must:
+Write `./autoresearch.sh` at the working directory. It is the canonical benchmark entrypoint and MUST:
 
 - exit 0 on success and non-zero on failure;
 - print the primary metric as a single line `METRIC <name>=<value>`;
 - print any secondary metrics as additional `METRIC <name>=<value>` lines;
 - run the same workload deterministically every time (no live network, no time-of-day dependencies, fixed seeds where applicable).
 
-You **may** edit anything else needed to make `autoresearch.sh` work — benchmark binaries, `Cargo.toml`, `package.json`, helper scripts, fixtures. All those edits are part of the harness baseline and will be committed for you when you call `init_experiment` on an autoresearch branch.
+You MAY edit anything else needed to make `autoresearch.sh` work — benchmark binaries, `Cargo.toml`, `package.json`, helper scripts, fixtures. All those edits are part of the harness baseline and will be committed for you when you call `init_experiment` on an autoresearch branch.
 
 ### Steps
 
@@ -38,6 +38,6 @@ You **may** edit anything else needed to make `autoresearch.sh` work — benchma
 
 ### Rules
 
-- Do **not** call `run_experiment`, `log_experiment`, or `update_notes` yet. They will error with "no active autoresearch session" until `init_experiment` runs.
-- Do **not** treat a compile-only check as a benchmark. The harness must actually execute the workload and emit `METRIC`.
-- Do **not** create `autoresearch.md`, `autoresearch.checks.sh`, `autoresearch.program.md`, `autoresearch.ideas.md`, `autoresearch.jsonl`, `.autoresearch/`, or `autoresearch.config.json`. Session state is tracked for you.
+- NEVER call `run_experiment`, `log_experiment`, or `update_notes` yet. They will error with "no active autoresearch session" until `init_experiment` runs.
+- NEVER treat a compile-only check as a benchmark. The harness MUST actually execute the workload and emit `METRIC`.
+- NEVER create `autoresearch.md`, `autoresearch.checks.sh`, `autoresearch.program.md`, `autoresearch.ideas.md`, `autoresearch.jsonl`, `.autoresearch/`, or `autoresearch.config.json`. Session state is tracked for you.

package/src/autoresearch/prompt.md

@@ -11,17 +11,17 @@ Primary goal:
 There is no goal recorded for this session yet. Infer what to optimize from the latest user message and the conversation; capture the goal in your notes (`update_notes`) once it is clear.
 {{/if}}
 
-Session state and run artifacts are managed for you. The benchmark entrypoint is `bash autoresearch.sh` (committed during Phase 1). Do not edit `autoresearch.sh` mid-segment unless you intentionally bump segment via `init_experiment new_segment: true`. Do not create `autoresearch.md` or `.autoresearch/` in this repo.
+Session state and run artifacts are managed for you. The benchmark entrypoint is `bash autoresearch.sh` (committed during Phase 1). NEVER edit `autoresearch.sh` mid-segment unless you intentionally bump segment via `init_experiment new_segment: true`. NEVER create `autoresearch.md` or `.autoresearch/` in this repo.
 
 Working directory: `{{working_dir}}`
 {{#if has_branch}}Active branch: `{{branch}}`{{/if}}
 {{#if has_baseline_commit}}Baseline commit: `{{baseline_commit}}`{{/if}}
 
-You are running an autonomous experiment loop. Keep iterating until the user interrupts you or the configured maximum iteration count is reached.
+You are running an autonomous experiment loop. You MUST keep iterating until the user interrupts you or the configured maximum iteration count is reached.
 
 ### Available tools
 - `init_experiment` — open or reconfigure the session. Pass `new_segment: true` to start a fresh baseline within the current session.
-- `run_experiment` — run the benchmark (`bash autoresearch.sh`). Output is captured automatically and `METRIC name=value` / `ASI key=value` lines printed by the harness are parsed back to you. The command is fixed; if you need a different workload, edit `autoresearch.sh` and bump segment via `init_experiment new_segment: true`.
+- `run_experiment` — run the benchmark (`bash autoresearch.sh`). Output is captured automatically and `METRIC name=value` / `ASI key=value` lines printed by the harness are parsed back to you. The command is fixed.
 - `log_experiment` — record the result. On `keep`, modified files are committed for you; on `discard`/`crash`/`checks_failed`, the worktree is reverted. Pass `flag_runs` to mark earlier runs as suspect; flagged runs are excluded from baseline and best-metric math.
 - `update_notes` — replace the durable session playbook (`body`) or append to the ideas backlog (`append_idea`). The notes are injected into your system prompt every iteration.
 
@@ -97,7 +97,7 @@ Finish the `log_experiment` step before starting another benchmark.
 {{/if}}
 
 ### Guardrails
-- Do not game the benchmark.
-- Do not overfit to synthetic inputs if the real workload is broader.
-- Preserve correctness.
+- NEVER game the benchmark.
+- NEVER overfit to synthetic inputs if the real workload is broader.
+- MUST preserve correctness.
 - If the user sends another message while a run is in progress, finish the current run and logging cycle first, then address the new input in the next iteration.