@kr78/pi-coding-agent 17.2.10

package/src/auto-thinking/classifier.ts

@@ -0,0 +1,220 @@
+/**
+ * Per-prompt difficulty classifier for the `auto` thinking level.
+ *
+ * Picks a coding-difficulty bucket for a user prompt and maps it to a concrete
+ * {@link Effort}, clamped into the active model's supported range (never below
+ * {@link Effort.Low}). Two backends, selected by `providers.autoThinkingModel`:
+ *
+ * - `online` (default): a smol model classifies into `low|medium|high|xhigh`,
+ *   plus `max` when the target model exposes that tier.
+ * - a local key: an on-device memory model classifies into the coarser
+ *   `trivial|moderate|hard` scheme (3-class is more reliable than 4-way ordinal
+ *   on sub-2B models), mapped to `low|high|xhigh`.
+ *
+ * Throws on any failure (no model, no key, unparseable output, abort/timeout);
+ * the caller falls back to a concrete level and continues the turn.
+ */
+import { type AssistantMessage, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
+import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
+import { prompt } from "@oh-my-pi/pi-utils";
+
+import type { ModelRegistry } from "../config/model-registry";
+import { resolveRoleSelection } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import difficultySystemPrompt from "../prompts/system/auto-thinking-difficulty.md" with { type: "text" };
+import difficultyLocalPrompt from "../prompts/system/auto-thinking-difficulty-local.md" with { type: "text" };
+import { clampAutoThinkingEffort } from "../thinking";
+import { preprocessTinyMessage } from "../tiny/message-preproc";
+import {
+	isTinyMemoryLocalModelKey,
+	isTinyMemoryReasoningModelKey,
+	ONLINE_AUTO_THINKING_MODEL_KEY,
+} from "../tiny/models";
+import { tinyModelClient } from "../tiny/title-client";
+
+/**
+ * Rendered classifier prompts, keyed by whether `max` is offered as a label.
+ * Two variants only, so both are memoized on first use.
+ */
+const DIFFICULTY_SYSTEM_PROMPTS: Partial<Record<"max" | "xhigh", string>> = {};
+
+/**
+ * Highest effort this turn's classification may resolve to: the configured
+ * ceiling, further limited by what the target model actually exposes. The
+ * default keeps `auto` one tier below the top, so only an explicit
+ * `ultrathink` reaches {@link Effort.Max}.
+ */
+function autoEffortCeiling(deps: ClassifyDifficultyDeps): Effort {
+	if (deps.settings.get("providers.autoThinkingMaxEffort") !== Effort.Max) return Effort.XHigh;
+	return getSupportedEfforts(deps.model).includes(Effort.Max) ? Effort.Max : Effort.XHigh;
+}
+
+function difficultySystemPromptFor(ceiling: Effort): string {
+	const key = ceiling === Effort.Max ? "max" : "xhigh";
+	const cached = DIFFICULTY_SYSTEM_PROMPTS[key];
+	if (cached !== undefined) return cached;
+	const rendered = prompt.render(difficultySystemPrompt, { allowMax: key === "max" });
+	DIFFICULTY_SYSTEM_PROMPTS[key] = rendered;
+	return rendered;
+}
+
+/** Local classifiers occasionally need more room for chat-template boilerplate. */
+const LOCAL_ANSWER_MAX_TOKENS = 16;
+/**
+ * Online classifier budget. Sized to survive backends that ignore
+ * `disableReasoning` (e.g. Qwen3 via llama.cpp catalogued `reasoning: false`
+ * but still emitting thinking): the classifier keyword needs to land after any
+ * unavoidable thinking preamble. `maxTokens` is a hard cap — non-thinking
+ * completions still return in a handful of tokens (issue #4355).
+ */
+const REASONING_SAFE_MAX_TOKENS = 1024;
+
+export interface ClassifyDifficultyDeps {
+	settings: Settings;
+	registry: ModelRegistry;
+	model: Model;
+	sessionId?: string;
+	signal?: AbortSignal;
+	metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+}
+
+/**
+ * Classify `promptText` and return a concrete effort clamped to `deps.model`,
+ * or `undefined` when the model has no controllable effort surface (auto has
+ * nothing to pick — the caller leaves the prior reasoning level in place).
+ * @throws when the backend cannot produce a usable classification.
+ */
+export async function classifyDifficulty(
+	promptText: string,
+	deps: ClassifyDifficultyDeps,
+): Promise<Effort | undefined> {
+	const backend = deps.settings.get("providers.autoThinkingModel");
+	const input = preprocessTinyMessage(promptText);
+	const online = backend === ONLINE_AUTO_THINKING_MODEL_KEY;
+	// The 3-bucket local classifier cannot select `max`, so its ceiling stays at
+	// XHigh whatever the setting says — otherwise a sparse ladder would snap its
+	// `hard` bucket up to a tier it never chose.
+	const ceiling = online ? autoEffortCeiling(deps) : Effort.XHigh;
+	const effort = online ? await classifyOnline(input, deps, ceiling) : await classifyLocal(input, backend, deps);
+	// The ceiling goes into the clamp itself: capping the request alone is not
+	// enough, because a sparse ladder snaps an excluded request back up.
+	return clampAutoThinkingEffort(deps.model, effort, ceiling);
+}
+
+async function classifyOnline(input: string, deps: ClassifyDifficultyDeps, ceiling: Effort): Promise<Effort> {
+	const resolved = resolveRoleSelection(["tiny", "smol"], deps.settings, deps.registry.getAvailable());
+	const model = resolved?.model;
+	if (!model) {
+		throw new Error("auto-thinking: no tiny/smol model available for classification");
+	}
+	const apiKey = await deps.registry.getApiKey(model, deps.sessionId);
+	if (!apiKey) {
+		throw new Error(`auto-thinking: no API key for ${model.provider}/${model.id}`);
+	}
+	// Resolve metadata after getApiKey so the session-sticky credential is recorded first.
+	const metadata = deps.metadataResolver?.(model.provider);
+	const maxTokens = REASONING_SAFE_MAX_TOKENS;
+
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt: [difficultySystemPromptFor(ceiling)],
+			messages: [{ role: "user", content: input, timestamp: Date.now() }],
+		},
+		{
+			apiKey: deps.registry.resolver(model, deps.sessionId),
+			maxTokens,
+			disableReasoning: true,
+			metadata,
+			signal: deps.signal,
+		},
+	);
+
+	if (response.stopReason === "error") {
+		throw new Error(`auto-thinking: online classification failed: ${response.errorMessage ?? "unknown error"}`);
+	}
+
+	const text = extractText(response.content);
+	const effort = parseDifficultyLevel(text);
+	if (!effort) {
+		throw new Error(`auto-thinking: unparseable online classification: ${JSON.stringify(text)}`);
+	}
+	return effort;
+}
+
+async function classifyLocal(input: string, modelKey: string, deps: ClassifyDifficultyDeps): Promise<Effort> {
+	if (!isTinyMemoryLocalModelKey(modelKey)) {
+		throw new Error(`auto-thinking: unsupported local classifier model: ${modelKey}`);
+	}
+	const maxTokens = isTinyMemoryReasoningModelKey(modelKey)
+		? Math.max(LOCAL_ANSWER_MAX_TOKENS, REASONING_SAFE_MAX_TOKENS)
+		: LOCAL_ANSWER_MAX_TOKENS;
+	const builtPrompt = prompt.render(difficultyLocalPrompt, { prompt: input });
+	const text = await tinyModelClient.complete(modelKey, builtPrompt, {
+		maxTokens,
+		signal: deps.signal,
+	});
+	if (!text) {
+		throw new Error("auto-thinking: local classification returned no output");
+	}
+	const effort = parseDifficultyBucket(text);
+	if (!effort) {
+		throw new Error(`auto-thinking: unparseable local classification: ${JSON.stringify(text)}`);
+	}
+	return effort;
+}
+
+/**
+ * Map an online level keyword to an {@link Effort}; earliest match wins.
+ *
+ * `max` is only offered to the classifier when the target model exposes that
+ * tier, but it is always parsed: an unsupported `max` is snapped back down by
+ * {@link clampAutoThinkingEffort} rather than failing the turn.
+ */
+export function parseDifficultyLevel(text: string): Effort | undefined {
+	const lower = text.toLowerCase();
+	const candidates: Array<[number, Effort]> = [];
+	// `xhigh` must be probed as its own token: `\bhigh\b` cannot match the "high"
+	// inside "xhigh" (no word boundary between `x` and `h`), so the two never collide.
+	const xhigh = lower.search(/x[\s_-]?high/);
+	if (xhigh >= 0) candidates.push([xhigh, Effort.XHigh]);
+	const max = lower.search(/\bmax\b/);
+	if (max >= 0) candidates.push([max, Effort.Max]);
+	const high = lower.search(/\bhigh\b/);
+	if (high >= 0) candidates.push([high, Effort.High]);
+	const medium = lower.search(/\bmed(?:ium)?\b/);
+	if (medium >= 0) candidates.push([medium, Effort.Medium]);
+	const low = lower.search(/\blow\b/);
+	if (low >= 0) candidates.push([low, Effort.Low]);
+	return earliest(candidates);
+}
+
+/** Map the local 3-way bucket keyword to an {@link Effort}; earliest match wins. */
+export function parseDifficultyBucket(text: string): Effort | undefined {
+	const lower = text.toLowerCase();
+	const candidates: Array<[number, Effort]> = [];
+	const trivial = lower.search(/\btrivial\b/);
+	if (trivial >= 0) candidates.push([trivial, Effort.Low]);
+	const moderate = lower.search(/\bmoderate\b/);
+	if (moderate >= 0) candidates.push([moderate, Effort.High]);
+	const hard = lower.search(/\bhard\b/);
+	if (hard >= 0) candidates.push([hard, Effort.XHigh]);
+	return earliest(candidates);
+}
+
+function earliest(candidates: Array<[number, Effort]>): Effort | undefined {
+	if (candidates.length === 0) return undefined;
+	let best = candidates[0];
+	for (const candidate of candidates) {
+		if (candidate[0] < best[0]) best = candidate;
+	}
+	return best[1];
+}
+
+function extractText(content: AssistantMessage["content"]): string {
+	return content
+		.filter((block): block is Extract<AssistantMessage["content"][number], { type: "text" }> => block.type === "text")
+		.map(block => block.text)
+		.join(" ")
+		.trim();
+}

package/src/autolearn/controller.ts

@@ -0,0 +1,152 @@
+/**
+ * Auto-learn session controller (experimental).
+ *
+ * Subscribes to the session event stream and, after a substantive turn,
+ * optionally auto-runs a synthetic capture turn. Passive mode is intentionally
+ * prompt-cache neutral: the standing system guidance remains available, but no
+ * hidden mid-session reminder is inserted into the conversation.
+ *
+ * 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 "@oh-my-pi/pi-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 autolearnNudgeAutoContinue from "../prompts/system/autolearn-nudge-autocontinue.md" with { type: "text" };
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+
+const AUTOLEARN_NUDGE_AUTOCONTINUE = autolearnNudgeAutoContinue.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;
+	capture: (content: string) => Promise<void>;
+}
+
+export class AutoLearnController {
+	readonly #session: AgentSession;
+	readonly #settings: Settings;
+	readonly #capture: (content: string) => Promise<void>;
+	#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;
+	/** Prevent overlapping private capture runs while real primary turns continue. */
+	#captureInFlight = false;
+	/** One newer eligible primary stop arrived while capture was running. */
+	#capturePending = false;
+
+	constructor(options: AutoLearnControllerOptions) {
+		this.#session = options.session;
+		this.#settings = options.settings;
+		this.#capture = options.capture;
+		// 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(event);
+		}
+	}
+
+	#onAgentEnd(event: Extract<AgentSessionEvent, { type: "agent_end" }>): 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;
+
+		// Never nudge a turn that ended in an abort (ESC, cancel, etc.). The
+		// abort flag on the session is unreliable by the time agent_end is
+		// deferred to subscribers; read stopReason from the event messages.
+		for (let i = event.messages.length - 1; i >= 0; i--) {
+			const message = event.messages[i];
+			if (message && typeof message === "object" && "role" in message && message.role === "assistant") {
+				if ("stopReason" in message && message.stopReason === "aborted") {
+					return;
+				}
+				break;
+			}
+		}
+		// 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. Passive mode used to
+		// queue a hidden custom message for the next real turn, but that mutates the
+		// persisted conversation prefix after providers have cached it. The standing
+		// auto-learn system guidance is stable; keep passive mode to that guidance
+		// so Anthropic prompt-cache prefixes survive long sessions.
+		const autoContinue = this.#settings.get("autolearn.autoContinue") === true;
+		if (!autoContinue) return;
+
+		if (this.#captureInFlight) {
+			this.#capturePending = true;
+			return;
+		}
+		this.#startCapture();
+	}
+
+	#startCapture(): void {
+		this.#captureInFlight = true;
+		void this.#capture(AUTOLEARN_NUDGE_AUTOCONTINUE)
+			.catch(err => {
+				logger.warn("auto-learn capture failed", { err });
+			})
+			.finally(() => {
+				this.#captureInFlight = false;
+				if (!this.#capturePending) return;
+				this.#capturePending = false;
+				this.#startCapture();
+			});
+	}
+}

package/src/autolearn/managed-skills.ts

@@ -0,0 +1,255 @@
+/**
+ * Managed-skills primitives for the experimental auto-learn feature.
+ *
+ * Managed skills are auto-generated/enhanced `SKILL.md` files kept in an
+ * isolated directory (`~/.omp/agent/managed-skills`) separate from
+ * user-authored skills (`~/.omp/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 path from "node:path";
+import { getAgentDir, isEnoent } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+
+/** Provider id stamped on discovered managed skills (distinguishes them from authored). */
+export const MANAGED_SKILLS_PROVIDER_ID = "omp-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 (`~/.omp/agent/managed-skills`). */
+export function getManagedSkillsDir(agentDir: string = getAgentDir()): string {
+	return path.join(agentDir, "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/command-resume.md

@@ -0,0 +1,14 @@
+Resume autoresearch on the active session.
+
+{{branch_status_line}}
+{{#if has_resume_context}}
+
+Additional context from the user:
+
+{{resume_context}}
+{{/if}}
+
+- Use the active session context above as the source of truth for goal, scope, constraints, and run history.
+- Inspect recent git history for context.
+- Continue the most promising unfinished direction.
+- Keep iterating until interrupted or until the configured iteration cap is reached.