jeopi-cli 16.3.0 → 16.4.0

package/src/memories/index.ts

@@ -1342,7 +1342,7 @@ export function getMemoryRoot(agentDir: string, cwd: string): string {
  * consolidation artifacts (`MEMORY.md`, `memory_summary.md`, `skills/`) so a
  * consolidation pass never clobbers manually captured lessons.
  */
-const LEARNED_LESSONS_FILE = "learned.md";
+export const LEARNED_LESSONS_FILE = "learned.md";
 /** Newest-first cap on retained lessons, bounding file growth by entry count. */
 const MAX_LEARNED_LESSONS = 100;
 /** Per-field char caps so a single huge capture can't bloat learned.md. */
@@ -1414,7 +1414,15 @@ export async function saveLearnedLesson(
 		return { backend: "local", stored: 0, message: "Empty lesson; nothing stored." };
 	}
 	const context = input.context ? normalizeLearnedText(input.context, MAX_LEARNED_CONTEXT_CHARS) : "";
-	const line = context ? `- ${content} _(context: ${context})_` : `- ${content}`;
+	const contextSuffix = context ? ` _(context: ${context})_` : "";
+	let line: string;
+	if (input.verified === true) {
+		const evidence = input.evidence ? normalizeLearnedText(input.evidence, MAX_LEARNED_CONTEXT_CHARS) : "";
+		const evidenceSuffix = evidence ? ` _(evidence: ${evidence})_` : "";
+		line = `- [VERIFIED] ${content}${evidenceSuffix}${contextSuffix}`;
+	} else {
+		line = `- [UNVERIFIED] ${content}${contextSuffix}`;
+	}
 	const filePath = path.join(getMemoryRoot(agentDir, cwd), LEARNED_LESSONS_FILE);
 
 	// Serialize the read-modify-write per file: parallel `learn` calls (sibling

package/src/memory-backend/local-backend.ts

@@ -1,8 +1,12 @@
+import * as path from "node:path";
+import { isEnoent } from "jeopi-utils";
 import {
 	buildMemoryToolDeveloperInstructions,
 	clearMemoryData,
 	clearMemoryToolDeveloperInstructionsCache,
 	enqueueMemoryConsolidation,
+	getMemoryRoot,
+	LEARNED_LESSONS_FILE,
 	saveLearnedLesson,
 	startMemoryStartupTask,
 } from "../memories";
@@ -44,4 +48,34 @@ export const localBackend: MemoryBackend = {
 				"Local rollout-summary memory is active; lessons from the `learn` tool are saved to learned.md. Structured search is not available.",
 		};
 	},
+	async stats(agentDir, cwd) {
+		const filePath = path.join(getMemoryRoot(agentDir, cwd), LEARNED_LESSONS_FILE);
+		let raw = "";
+		try {
+			raw = await Bun.file(filePath).text();
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+		}
+		let total = 0;
+		let verified = 0;
+		for (const rawLine of raw.split("\n")) {
+			const line = rawLine.trim();
+			if (!line.startsWith("- ")) continue;
+			total++;
+			if (line.startsWith(VERIFIED_PREFIX)) verified++;
+		}
+		const unverified = total - verified;
+		const coverage = total > 0 ? `${((verified / total) * 100).toFixed(1)}%` : "N/A";
+		return [
+			"# Local Memory Stats",
+			"",
+			`- Lessons: ${total}`,
+			`- Verified: ${verified}`,
+			`- Unverified: ${unverified}`,
+			`- Verification coverage: ${coverage}`,
+		].join("\n");
+	},
 };
+
+/** Line prefix `saveLearnedLesson` writes for verified/unverified lessons in `learned.md`. */
+const VERIFIED_PREFIX = "- [VERIFIED]";

package/src/memory-backend/types.ts

@@ -60,6 +60,17 @@ export interface MemoryBackendSaveInput {
 	context?: string;
 	source?: string;
 	importance?: number;
+	/**
+	 * Marks this lesson as independently re-checked against the repo (a
+	 * command run, a file read, a test executed) rather than merely asserted
+	 * from inference. Mirrors the "verify" stage of the fail → investigate →
+	 * verify → distill → consult self-improvement progression: a lesson that
+	 * skips verification is still worth capturing, but downstream consumers
+	 * (e.g. `stats()`) should be able to tell the two apart.
+	 */
+	verified?: boolean;
+	/** The short check that was run to establish `verified` (a command, a file path, a test name). Ignored when `verified` is not `true`. */
+	evidence?: string;
 }
 
 export interface MemoryBackendSaveResult {

package/src/prompts/agents/designer.md

@@ -20,6 +20,7 @@ Treat the design system as the foundation — UI built without one collapses int
 2. **No coherent system? Build the minimal one first.** Extract what exists, then define a palette, type scale, spacing scale (4px/8px base), radii/shadows/transitions, and primitive components — THEN implement the request against it.
 3. **Compose with the system, never around it.** Colors → tokens/CSS variables, never hardcoded hex; spacing → scale values, never arbitrary px; type → scale steps; components → extend/compose existing primitives, not one-off div soup. Need something outside the system? Add the new token to the system first, then use it — never a one-off override.
 4. **Verify before done.** Every color a token, every spacing on the scale, every component on the existing composition pattern, zero magic numbers — a designer would see consistency across old and new. Any "no" → not done.
+5. **Visually verify the rendered result.** Code-level checks (tokens/spacing) don't catch layout/rendering bugs. After producing a UI change, capture it (`tab.screenshot()` for browser-rendered UI, or the existing screenshot path) and call `vision_verify` with the task's stated goal — pass `baseline` when checking for regression against a known-good prior state.
 </design-system>
 
 <procedure>

package/src/prompts/tools/learn.md

@@ -5,3 +5,5 @@ Use after solving something whose insight will pay off again: a non-obvious fix,
 Provide the optional `skill` object when the lesson is a repeatable *procedure* worth codifying as a `SKILL.md` (not just a fact). Managed skills are written to an isolated directory (`~/.jeopi/agent/managed-skills`) and are surfaced like normal skills next session. They NEVER touch user-authored skills. Frontmatter is generated from `name` and `description`.
 
 Capture sparingly and specifically. One strong, reusable lesson beats several vague ones.
+
+Set `verified: true` when you independently re-checked the claim against the repo — you ran a command, read a file, or ran a test that directly confirmed it — and pass a short `evidence` string naming that check (e.g. "ran `bun test src/foo.test.ts`, all 12 pass" or "read `package.json:12`, confirms dependency pin"). Leave `verified` unset (the default) for a hypothesis or pattern you noticed but did not independently confirm.

package/src/prompts/tools/vision-verify-system.md

@@ -0,0 +1,16 @@
+You are a UI/artifact verification assistant.
+
+Core behavior:
+- Be evidence-first: judge only what is visibly present in the image(s).
+- If something is unclear or partially occluded, treat it as unmet rather than guessing it is fine.
+- NEVER fabricate details that are not visible.
+- When a baseline (prior) screenshot is provided, compare the current screenshot against it and treat any visible divergence as a gap unless the goal explicitly calls for that change.
+
+Output contract — respond with ONLY a single JSON object, no prose before or after it, no markdown code fence, matching exactly:
+{"matches": boolean, "summary": string, "gaps": string[]}
+
+- `matches`: true only if the current screenshot fully satisfies the stated goal (and, when a baseline is given, shows no unintended regression from it).
+- `summary`: one to three sentences describing what you observed.
+- `gaps`: specific, concrete differences between what is observed and what the goal (or baseline) requires. Empty array when `matches` is true.
+
+Return raw JSON only — any other format is a failure to follow instructions.

package/src/prompts/tools/vision-verify.md

@@ -0,0 +1,20 @@
+Verifies a screenshot or UI artifact against a stated goal with a vision-capable model and returns a structured verdict.
+
+<instruction>
+- Use this after producing or modifying a UI to check the result against the task's stated goal
+- Provide `screenshot` as a local image file path, `Image #N` attachment label, or `attachment://N` URI
+- Write a specific `goal`: what the UI/artifact should look like or achieve
+- Pass `baseline` (a path to a prior screenshot of the same view) to check for visual regression against a known-good state
+- Use this tool over `inspect_image` when you need a pass/fail verdict with structured gaps, not free-text description
+</instruction>
+
+<output>
+- Returns a structured verdict: `matches` (boolean), `summary`, and `gaps` (empty when `matches` is true)
+- No image content blocks are returned in tool output
+</output>
+
+<critical>
+- If image submission is blocked by settings, the tool will fail with an actionable error
+- If configured model does not support image input, configure a vision-capable model role before retrying
+- If the model's response cannot be parsed as the expected JSON shape, the tool fails with the raw response included — retry rather than trust an unstructured fallback
+</critical>

package/src/slash-commands/builtin-registry.ts

@@ -43,6 +43,7 @@ import { createMarketplaceManager } from "./helpers/marketplace-manager";
 import { handleMcpAcp } from "./helpers/mcp";
 import { commandConsumed, errorMessage, parseSlashCommand, parseSubcommand, usage } from "./helpers/parse";
 import { describeRedeemOutcome, type ResetUsageAccount, toResetUsageAccounts } from "./helpers/reset-usage";
+import { handleSkillCommand } from "./helpers/skill-verify";
 import { handleSshAcp } from "./helpers/ssh";
 import { launchStatsDashboard, parseStatsDashboardArgs } from "./helpers/stats-dashboard";
 import { handleTodoAcp } from "./helpers/todo";
@@ -1348,6 +1349,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			await runtime.ctx.handleSSHCommand(command.text);
 		},
 	},
+	{
+		name: "verify-skill",
+		description: "Run a skill's `## Eval Cases` and report pass/fail",
+		acpDescription: "Verify a skill's eval cases",
+		inlineHint: "<name>",
+		allowArgs: true,
+		handle: handleSkillCommand,
+	},
 	{
 		name: "new",
 		priority: 96,

package/src/slash-commands/helpers/skill-verify.ts

@@ -0,0 +1,171 @@
+/**
+ * `/verify-skill <name>` — self-verification for a skill's `## Eval Cases`.
+ *
+ * Resolves a skill from the active session, extracts a bulleted `## Eval
+ * Cases` markdown section from its `SKILL.md` body (if present), and spawns
+ * one read-only `critic` subagent per case to verdict whether the claim still
+ * holds against the current repo state. Renders a pass/fail markdown report;
+ * never mutates the skill file.
+ *
+ * Named `verify-skill` (not `skill`) to avoid colliding with the pre-existing
+ * `/skill:<name>` direct-skill-invocation convention (both parse to the
+ * command-name token `skill` under `parseSlashCommand`'s earliest-whitespace-
+ * or-colon splitting rule — see slash-commands/helpers/parse.ts).
+ */
+import { MANAGED_SKILLS_PROVIDER_ID } from "../../autolearn/managed-skills";
+import { runEvalAgent } from "../../eval/agent-bridge";
+import { getBundledAgent } from "../../task/agents";
+import * as taskDiscovery from "../../task/discovery";
+import type { ToolSession } from "../../tools";
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+import { commandConsumed, usage } from "./parse";
+
+const VERIFIER_AGENT_NAME = "critic";
+
+interface EvalCaseVerdict {
+	claim: string;
+	passed: boolean;
+	reason: string;
+}
+
+/** Extract the bulleted list under a `## Eval Cases` heading, if present. */
+export function extractEvalCases(skillBody: string): string[] {
+	const headingMatch = /^##\s+Eval Cases\s*$/m.exec(skillBody);
+	if (!headingMatch) return [];
+	const sectionStart = headingMatch.index + headingMatch[0].length;
+	const rest = skillBody.slice(sectionStart);
+	const nextHeadingMatch = /^#{1,6}\s+\S/m.exec(rest);
+	const sectionBody = nextHeadingMatch ? rest.slice(0, nextHeadingMatch.index) : rest;
+	const cases: string[] = [];
+	for (const line of sectionBody.split("\n")) {
+		const bulletMatch = /^\s*[-*+]\s+(.+)$/.exec(line);
+		if (bulletMatch?.[1]) cases.push(bulletMatch[1].trim());
+	}
+	return cases;
+}
+
+/** Verdict a single eval-case claim against the current repo state via the bundled `critic` agent. */
+async function verifyEvalCase(session: ToolSession, claim: string): Promise<EvalCaseVerdict> {
+	const verifyPrompt =
+		`Verify this claim against the current repository state: ${claim}\n\n` +
+		"Report whether it still holds (yes/no) and why, citing files/commands.";
+	// Explicit schema, not the agent's own frontmatter default: runEvalAgent (the
+	// eval `agent()` bridge) only applies `outputSchema` when the caller supplies
+	// one — it never falls back to the agent's `output` frontmatter on its own
+	// (see goals/verifier.ts for the same pattern). Read the bundled definition's
+	// declared shape so this can't drift from critic.md.
+	const schema = getBundledAgent(VERIFIER_AGENT_NAME)?.output;
+	const args =
+		schema === undefined
+			? { prompt: verifyPrompt, agent: VERIFIER_AGENT_NAME }
+			: { prompt: verifyPrompt, agent: VERIFIER_AGENT_NAME, schema };
+	try {
+		const result = await runEvalAgent(args, { session });
+		let verdict: unknown;
+		try {
+			verdict = JSON.parse(result.text);
+		} catch {
+			// Freeform fallback: no parseable JSON, treat non-empty output as inconclusive-pass with raw text as reason.
+			return { claim, passed: true, reason: result.text.trim().slice(0, 300) || "No structured verdict returned." };
+		}
+		if (verdict && typeof verdict === "object") {
+			const record = verdict as Record<string, unknown>;
+			const rawVerdict = record.verdict;
+			const passed = rawVerdict === "okay";
+			const reason =
+				(typeof record.summary === "string" && record.summary) ||
+				(typeof record.justification === "string" && record.justification) ||
+				"No justification returned.";
+			return { claim, passed, reason: reason.slice(0, 400) };
+		}
+		return { claim, passed: false, reason: "Verifier returned an unparseable verdict." };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { claim, passed: false, reason: `Verification subagent failed: ${message}` };
+	}
+}
+
+function renderReport(skillName: string, isManaged: boolean, verdicts: EvalCaseVerdict[]): string {
+	const lines: string[] = [`## Skill verification: \`${skillName}\``, ""];
+	const failures: EvalCaseVerdict[] = [];
+	for (const verdict of verdicts) {
+		lines.push(`- ${verdict.passed ? "✅ PASS" : "❌ FAIL"} — ${verdict.claim}`);
+		lines.push(`  ${verdict.reason}`);
+		if (!verdict.passed) failures.push(verdict);
+	}
+	const passCount = verdicts.length - failures.length;
+	lines.push("", `${passCount}/${verdicts.length} eval cases passed.`);
+	if (failures.length > 0 && isManaged) {
+		lines.push(
+			"",
+			"This is a managed (auto-learn) skill. To record the failure mode, append a line like this under a `## Known Failure Modes` section (not applied automatically):",
+			"",
+		);
+		for (const failure of failures) {
+			lines.push(`- "${failure.claim}" — ${failure.reason}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/** `/verify-skill <name>` handler — resolves a skill, runs its `## Eval Cases`, reports pass/fail. */
+export async function handleSkillCommand(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const skillName = command.args.trim();
+	if (!skillName) {
+		return usage("Usage: /verify-skill <name>", runtime);
+	}
+	const skill = runtime.session.skills.find(candidate => candidate.name === skillName);
+	if (!skill) {
+		const available = runtime.session.skills.map(candidate => candidate.name).join(", ") || "none";
+		return usage(`Unknown skill "${skillName}". Available: ${available}`, runtime);
+	}
+
+	const body = await Bun.file(skill.filePath).text();
+	const evalCases = extractEvalCases(body);
+	if (evalCases.length === 0) {
+		await runtime.output(
+			`No eval cases defined for this skill — add an \`## Eval Cases\` section with bulleted verifiable claims to enable self-verification`,
+		);
+		return commandConsumed();
+	}
+
+	await runtime.output(`Verifying ${evalCases.length} eval case(s) for \`${skillName}\`…`);
+
+	// Discover once, upfront, to fail fast with a clear message if the critic
+	// agent is unavailable (disabled, or bundled agents failed to load) rather
+	// than surfacing N identical spawn errors.
+	const { agents } = await taskDiscovery.discoverAgents(runtime.cwd);
+	if (!taskDiscovery.getAgent(agents, VERIFIER_AGENT_NAME)) {
+		return usage(
+			`The "${VERIFIER_AGENT_NAME}" agent is unavailable in this session; cannot run eval cases.`,
+			runtime,
+		);
+	}
+
+	const session: ToolSession = {
+		cwd: runtime.cwd,
+		hasUI: false,
+		settings: runtime.settings,
+		skills: [...runtime.session.skills],
+		taskDepth: 0,
+		getSessionFile: () => runtime.session.sessionManager.getSessionFile() ?? null,
+		getSessionSpawns: () => "*",
+		getPlanModeState: () => runtime.session.getPlanModeState(),
+		getActiveModelString: () =>
+			runtime.session.model ? `${runtime.session.model.provider}/${runtime.session.model.id}` : undefined,
+		modelRegistry: runtime.session.modelRegistry,
+		authStorage: runtime.session.modelRegistry.authStorage,
+		getAgentId: () => runtime.session.getAgentId() ?? null,
+	};
+	const verdicts: EvalCaseVerdict[] = [];
+	for (const claim of evalCases) {
+		verdicts.push(await verifyEvalCase(session, claim));
+	}
+
+	const isManaged = skill._source?.provider === MANAGED_SKILLS_PROVIDER_ID;
+	await runtime.output(renderReport(skillName, isManaged, verdicts));
+	return commandConsumed();
+}

package/src/task/index.ts

@@ -67,6 +67,7 @@ import {
 	prepareIsolationContext,
 	runIsolatedSubprocess,
 } from "./isolation-runner";
+import { classifyDefaultTaskModelTier } from "./model-tier-classifier";
 import { generateTaskName } from "./name-generator";
 import { AgentOutputManager } from "./output-manager";
 import { mapWithConcurrencyLimit, normalizeConcurrencyLimit, Semaphore } from "./parallel";
@@ -1202,7 +1203,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const agentModelOverrides = this.session.settings.get("task.agentModelOverrides");
 		const settingsModelOverride = agentModelOverrides[agentName];
 		const parentActiveModelPattern = this.session.getActiveModelString?.();
-		const modelOverride = resolveAgentModelPatterns({
+		let modelOverride = resolveAgentModelPatterns({
 			settingsOverride: settingsModelOverride,
 			agentModel: effectiveAgent.model,
 			settings: this.session.settings,
@@ -1211,6 +1212,30 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		});
 		const thinkingLevelOverride = effectiveAgent.thinkingLevel;
 
+		// Auto-tier the generic default `task` agent to the cheap `smol` model
+		// when the assignment classifies as trivially simple and nothing else
+		// (settings override) already pinned the model. Named specialists carry
+		// their own `model:` frontmatter, so gating on the literal "task" agent
+		// name naturally excludes them without inspecting frontmatter here.
+		const autoModel = this.session.getActiveModel?.();
+		const autoModelRegistry = this.session.modelRegistry;
+		if (
+			agentName === "task" &&
+			settingsModelOverride === undefined &&
+			this.session.settings.get("task.autoModelTier") &&
+			autoModel &&
+			autoModelRegistry
+		) {
+			const tier = await classifyDefaultTaskModelTier(assignment, {
+				settings: this.session.settings,
+				registry: autoModelRegistry,
+				model: autoModel,
+				sessionId: this.session.getSessionId?.() ?? undefined,
+				signal,
+			});
+			if (tier === "smol") modelOverride = ["pi/smol"];
+		}
+
 		// Output schema priority: agent frontmatter > inherited parent session.
 		// The task call itself never carries a schema; workflows needing ad-hoc
 		// structured output go through eval agent(prompt, schema).

package/src/task/model-tier-classifier.ts

@@ -0,0 +1,43 @@
+/**
+ * Default `task`-agent spawn model-tier classifier.
+ *
+ * Reuses the auto-thinking difficulty classifier ({@link classifyDifficulty})
+ * to decide whether a `task()` spawn's assignment is trivially simple enough
+ * to route to the cheap `smol` model tier instead of the default `task`
+ * tier. Only ever suggests a downgrade — never blocks or upgrades — and
+ * fails open (returns `undefined`, meaning "don't override") on any
+ * classification error or timeout, mirroring `AgentSession`'s
+ * `#applyAutoThinkingLevel` fallback behavior.
+ */
+import { Effort } from "jeopi-ai";
+import { logger } from "jeopi-utils";
+import { type ClassifyDifficultyDeps, classifyDifficulty } from "../auto-thinking/classifier";
+
+/** Timeout (ms) for the spawn-time model-tier classification before failing open. */
+const MODEL_TIER_CLASSIFICATION_TIMEOUT_MS = 2000;
+
+/**
+ * Classify `assignment` and return `"smol"` when the work is trivially
+ * simple ({@link Effort.Minimal} or {@link Effort.Low}), or `undefined` when
+ * the caller should leave normal model resolution in place (not-simple
+ * enough, no classifier available, or the classification failed/timed out).
+ */
+export async function classifyDefaultTaskModelTier(
+	assignment: string,
+	deps: ClassifyDifficultyDeps,
+): Promise<"smol" | undefined> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), MODEL_TIER_CLASSIFICATION_TIMEOUT_MS);
+	const signal = deps.signal ? AbortSignal.any([deps.signal, controller.signal]) : controller.signal;
+	try {
+		const effort = await classifyDifficulty(assignment, { ...deps, signal });
+		return effort === Effort.Minimal || effort === Effort.Low ? "smol" : undefined;
+	} catch (error) {
+		logger.debug("task: model-tier classification failed; leaving model resolution unchanged", {
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/src/tools/builtin-names.ts

@@ -13,6 +13,7 @@ export const BUILTIN_TOOL_NAMES = [
 	"grep",
 	"lsp",
 	"inspect_image",
+	"vision_verify",
 	"browser",
 	"checkpoint",
 	"rewind",

package/src/tools/index.ts

@@ -66,6 +66,7 @@ import { SearchToolBm25Tool } from "./search-tool-bm25";
 import { loadSshTool } from "./ssh";
 import { isSubagentToolEnabled, SubagentTool } from "./subagent";
 import { type TodoPhase, TodoTool } from "./todo";
+import { VisionVerifyTool } from "./vision-verify";
 import { WriteTool } from "./write";
 import { YieldTool } from "./yield";
 
@@ -106,6 +107,7 @@ export * from "./ssh";
 export * from "./subagent";
 export * from "./todo";
 export * from "./tts";
+export * from "./vision-verify";
 export * from "./write";
 export * from "./yield";
 
@@ -466,6 +468,7 @@ export const BUILTIN_TOOLS: Record<BuiltinToolName, ToolFactory> = {
 	grep: s => new GrepTool(s),
 	lsp: LspTool.createIf,
 	inspect_image: s => new InspectImageTool(s),
+	vision_verify: s => new VisionVerifyTool(s),
 	browser: s => new BrowserTool(s),
 	checkpoint: CheckpointTool.createIf,
 	rewind: RewindTool.createIf,
@@ -621,6 +624,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "ast_grep") return session.settings.get("astGrep.enabled");
 		if (name === "ast_edit") return session.settings.get("astEdit.enabled");
 		if (name === "inspect_image") return session.settings.get("inspect_image.enabled");
+		if (name === "vision_verify") return session.settings.get("vision_verify.enabled");
 		if (name === "web_search") return session.settings.get("web_search.enabled");
 		// search_tool_bm25 is allowed when either legacy mcp.discoveryMode or new tools.discoveryMode is active.
 		if (name === "search_tool_bm25") return discoveryActive;

package/src/tools/learn.ts

@@ -9,6 +9,12 @@ import type { ToolSession } from ".";
 const learnSchema = type({
 	memory: type("string").describe("the durable, self-contained lesson to remember (what, when, why)"),
 	"context?": type("string").describe("optional source context for the lesson"),
+	"verified?": type("boolean").describe(
+		"true only if you independently re-checked this claim against the repo (ran a command, read a file, ran a test) rather than merely inferring it",
+	),
+	"evidence?": type("string").describe(
+		"the short check that confirmed the claim (a command, a file path, a test name); only meaningful when verified is true",
+	),
 	"skill?": type({
 		action: "'create' | 'update'",
 		name: type("string").describe("kebab-case skill name"),
@@ -65,6 +71,8 @@ export class LearnTool implements AgentTool<typeof learnSchema> {
 					cwd: state.session.sessionManager.getCwd(),
 					context: params.context ?? null,
 					tool: "learn",
+					verified: params.verified ?? false,
+					evidence: params.evidence ?? null,
 				},
 				scope: "bank",
 				extract: true,
@@ -81,7 +89,14 @@ export class LearnTool implements AgentTool<typeof learnSchema> {
 		} else if (backend === "local") {
 			const result = await localBackend.save?.(
 				{ agentDir: this.session.settings.getAgentDir(), cwd: this.session.settings.getCwd() },
-				{ content: params.memory, context: params.context, source: "coding-agent-learn", importance: 0.8 },
+				{
+					content: params.memory,
+					context: params.context,
+					source: "coding-agent-learn",
+					importance: 0.8,
+					verified: params.verified,
+					evidence: params.evidence,
+				},
 			);
 			if (!result || result.stored === 0) {
 				throw new Error("Lesson was empty after sanitization; nothing stored.");

package/src/tools/path-write-lock.ts

@@ -0,0 +1,44 @@
+import type { WritethroughCallback } from "../lsp";
+
+/**
+ * Non-isolated concurrent subagents (`task.isolation.mode="none"`, the
+ * default) share the parent session's cwd with no other collision-avoidance
+ * mechanism: two sibling subagents editing the same file can each perform an
+ * unguarded read-modify-write, and the interleaving of their disk writes can
+ * silently drop one of them. This wrapper does not prevent LOGICAL conflicts
+ * (two agents making incompatible edits to the same file) — it only
+ * serializes the physical writethrough call per destination path, so one
+ * write can no longer be lost mid-flight to another write racing the same
+ * path.
+ */
+
+/** Per-path write chains serializing the writethrough callback for a given destination. */
+const pathWriteChains = new Map<string, Promise<unknown>>();
+
+/**
+ * Wrap a {@link WritethroughCallback} so concurrent writes to the same `dst`
+ * are serialized instead of racing. `dst` is used as-is for the chain key:
+ * every caller (edit's hashline/patch/replace paths, and the write tool)
+ * resolves `dst` to an absolute path via `resolvePlanPath`/`resolveToCwd`
+ * before invoking the writethrough, so the same logical file always arrives
+ * under the same string.
+ */
+export function withPathWriteLock(callback: WritethroughCallback): WritethroughCallback {
+	return async (dst, content, signal, file, batch, getDeferred) => {
+		// Serialize the writethrough per path: parallel edits to the same file
+		// (sibling subagents sharing a cwd, or two shared tool calls in one
+		// turn) would otherwise let concurrent disk writes race and drop one.
+		const run = (pathWriteChains.get(dst) ?? Promise.resolve()).then(() =>
+			callback(dst, content, signal, file, batch, getDeferred),
+		);
+		const guarded = run.catch(() => {});
+		pathWriteChains.set(dst, guarded);
+		try {
+			return await run;
+		} finally {
+			// Drop the entry once this write is the chain tail, so the map does
+			// not retain one promise per distinct path for the process lifetime.
+			if (pathWriteChains.get(dst) === guarded) pathWriteChains.delete(dst);
+		}
+	};
+}