@quireco/cli 0.0.9 → 0.0.10

package/dist/{cli-C2HyQykL.mjs → cli-CqxFgCaa.mjs}

@@ -1,7 +1,7 @@
 import { n as __require, r as __toESM, t as __commonJSMin } from "./chunk-e9Ob2GDo.mjs";
 import { createRequire } from "node:module";
 import { createMain, defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
-import { isCancel, log, note, spinner, text } from "@clack/prompts";
+import { isCancel, log, multiselect, note, spinner, text } from "@clack/prompts";
 import { loginGitHubCopilot, loginOpenAICodex } from "@earendil-works/pi-ai/oauth";
 import { AuthStorage, DefaultResourceLoader, ModelRegistry, SessionManager, SettingsManager, createAgentSession, defineTool, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { exec, execFile, execFileSync, spawn } from "node:child_process";
@@ -722,7 +722,7 @@ function createQuireCreditsStream(options) {
 			const output = createEmptyAssistantMessage(model);
 			try {
 				const accessToken = streamOptions?.apiKey;
-				if (!accessToken) throw new CliError$1("Not logged in. Run `quire login` before `quire investigate` so Quire Credits can be checked.", ExitCode.AuthFailure);
+				if (!accessToken) throw new CliError$1("Not logged in. Run `quire login` before `quire run` so Quire Credits can be checked.", ExitCode.AuthFailure);
 				stream.push({
 					type: "start",
 					partial: output
@@ -753,7 +753,7 @@ function createQuireCreditsStream(options) {
 }
 async function readValidatedQuireCredentials(options) {
 	const credentials = await resolveAuthCredentials({ store: options.store });
-	if (!credentials) throw new CliError$1("Not logged in. Run `quire login` or set QUIRE_API_TOKEN before `quire investigate` so Quire Credits can be checked.", ExitCode.AuthFailure);
+	if (!credentials) throw new CliError$1("Not logged in. Run `quire login` or set QUIRE_API_TOKEN before `quire run` so Quire Credits can be checked.", ExitCode.AuthFailure);
 	if (credentials.tokenType === "QuireApiKey") return credentials;
 	const sessionLookup = await fetchCurrentSession({
 		apiBaseUrl: credentials.apiBaseUrl,
@@ -1410,6 +1410,9 @@ function runStatusPath(runPath) {
 function runProgressPath(runPath) {
 	return join(resolve(runPath), "progress.jsonl");
 }
+function runPlanPath(runPath) {
+	return join(resolve(runPath), "plan.md");
+}
 function runHandoffPath(runPath) {
 	return join(resolve(runPath), "handoff.md");
 }
@@ -1418,6 +1421,7 @@ function runDirPaths(root) {
 	return {
 		status: runStatusPath(root),
 		progress: runProgressPath(root),
+		plan: runPlanPath(root),
 		handoff: runHandoffPath(root),
 		evidence,
 		screenshots: join(evidence, "screenshots"),
@@ -1466,6 +1470,7 @@ function appendRunProgressEvent(runDir, event) {
 			seq
 		};
 		appendLineAtomically(runDir.paths.progress, `${stableJson(progressEvent)}\n`);
+		if (progressEvent.kind === "plan" && progressEvent.plan !== void 0) writeRunPlan(runDir, progressEvent);
 		return progressEvent;
 	});
 }
@@ -1499,6 +1504,45 @@ function patchRunStatusJson(runDir, patch) {
 function runProgressEventId(seq) {
 	return `progress-${seq.toString().padStart(6, "0")}`;
 }
+function writeRunPlan(runDir, event) {
+	const plan = event.plan;
+	if (plan === void 0) return;
+	const lines = [
+		"# Evidence plan",
+		"",
+		`Run: ${runDir.runId}`,
+		`Plan: ${plan.id}`,
+		`Recorded: ${event.ts}`,
+		...plan.supersedes === void 0 ? [] : [`Supersedes: ${plan.supersedes}`],
+		...plan.reason === void 0 ? [] : [`Reason: ${plan.reason}`],
+		"",
+		event.summary === void 0 ? void 0 : `## Summary\n\n${event.summary}\n`,
+		"## Steps",
+		"",
+		...plan.steps.flatMap((step, index) => [
+			`${index + 1}. **${step.title}** (${step.purpose})`,
+			...step.expectedOutcome === void 0 ? [] : [`   - Expected: ${step.expectedOutcome}`],
+			...step.assertionIds === void 0 || step.assertionIds.length === 0 ? [] : [`   - Assertions: ${step.assertionIds.join(", ")}`]
+		]),
+		""
+	].filter((line) => line !== void 0);
+	writeFileAtomically(runDir.paths.plan, `${lines.join("\n").trimEnd()}\n`, 384);
+	patchRunStatusJson(runDir, {
+		files: {
+			status: "status.json",
+			progress: "progress.jsonl",
+			plan: "plan.md",
+			handoff: "handoff.md",
+			evidence: "evidence"
+		},
+		plan: {
+			path: "plan.md",
+			progressEventId: event.id,
+			planId: plan.id,
+			updatedAt: event.ts
+		}
+	});
+}
 function readRepoSha(repoPath) {
 	try {
 		return execFileSync("git", [
@@ -1555,6 +1599,21 @@ function appendLineAtomically(filePath, line) {
 		closeSync(file);
 	}
 }
+function writeFileAtomically(filePath, contents, mode) {
+	mkdirSync(dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	const tempPath = join(dirname(filePath), `.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.${basename(filePath)}.tmp`);
+	const file = openSync(tempPath, constants$1.O_CREAT | constants$1.O_EXCL | constants$1.O_WRONLY, mode);
+	try {
+		writeFileSync(file, contents, "utf8");
+		fsyncSync(file);
+	} finally {
+		closeSync(file);
+	}
+	renameSync(tempPath, filePath);
+}
 function nextJsonlSequence(filePath) {
 	try {
 		const file = openSync(filePath, constants$1.O_RDONLY);
@@ -1618,6 +1677,7 @@ function createRunStatus(runDir, input) {
 		files: {
 			status: "status.json",
 			progress: "progress.jsonl",
+			plan: "plan.md",
 			handoff: "handoff.md",
 			evidence: "evidence"
 		},
@@ -1625,6 +1685,7 @@ function createRunStatus(runDir, input) {
 		status: input.status,
 		createdAt: timestamp,
 		updatedAt: timestamp,
+		lastActivityAt: timestamp,
 		...input.status === "running" ? { startedAt: timestamp } : {},
 		...input.pid === void 0 ? {} : { pid: input.pid },
 		...input.error === void 0 ? {} : { error: input.error }
@@ -1648,6 +1709,22 @@ function updateRunStatus(runPath, patch) {
 	writeStatus(runStatusPath(runPath), status);
 	return status;
 }
+function touchRunActivity(runPath, options = {}) {
+	const existing = readRunStatus(runPath);
+	if (existing === void 0) throw new CliError$1(`Run status not found: ${runPath}`, ExitCode.InvalidInput);
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const minIntervalMs = options.minIntervalMs ?? 5e3;
+	const previous = existing.lastActivityAt ?? existing.updatedAt;
+	const previousTime = Date.parse(previous);
+	if (Number.isFinite(previousTime) && now.getTime() - previousTime < minIntervalMs) return existing;
+	const timestamp = now.toISOString();
+	const status = {
+		...existing,
+		lastActivityAt: timestamp
+	};
+	writeStatus(runStatusPath(runPath), status);
+	return status;
+}
 function readRunStatus(runPath) {
 	const filePath = runStatusPath(runPath);
 	if (!existsSync(filePath)) return;
@@ -1765,6 +1842,7 @@ function parseRunStatus(value) {
 		status: value.status,
 		createdAt: value.createdAt,
 		updatedAt: value.updatedAt,
+		...typeof value.lastActivityAt === "string" ? { lastActivityAt: value.lastActivityAt } : {},
 		...typeof value.pid === "number" ? { pid: value.pid } : {},
 		...typeof value.startedAt === "string" ? { startedAt: value.startedAt } : {},
 		...typeof value.completedAt === "string" ? { completedAt: value.completedAt } : {},
@@ -1772,6 +1850,7 @@ function parseRunStatus(value) {
 		...value.agent === void 0 ? {} : { agent: value.agent },
 		...value.request === void 0 ? {} : { request: value.request },
 		...value.metadata === void 0 ? {} : { metadata: value.metadata },
+		...value.plan === void 0 ? {} : { plan: value.plan },
 		...value.harnessSession === void 0 ? {} : { harnessSession: value.harnessSession },
 		...value.finalHandoff === void 0 ? {} : { finalHandoff: value.finalHandoff },
 		...value.finalResult === void 0 ? {} : { finalResult: value.finalResult },
@@ -1783,12 +1862,14 @@ function parseRunStatusFiles(value) {
 	if (isRecord$14(value) && typeof value.status === "string" && typeof value.progress === "string" && typeof value.handoff === "string" && typeof value.evidence === "string") return {
 		status: value.status,
 		progress: value.progress,
+		...typeof value.plan === "string" ? { plan: value.plan } : {},
 		handoff: value.handoff,
 		evidence: value.evidence
 	};
 	return {
 		status: "status.json",
 		progress: "progress.jsonl",
+		plan: "plan.md",
 		handoff: "handoff.md",
 		evidence: "evidence"
 	};
@@ -2288,7 +2369,7 @@ const BrowserToolInputSchema = Type.Object({
 	argv: Type.Array(Type.String(), { minItems: 1 }),
 	cwd: Type.Optional(Type.String({ minLength: 1 }))
 }, { additionalProperties: false });
-function makeBrowserTool({ runDir, sessionId, cwd: defaultCwd, headed = false, agentBrowserExecutableResolver = resolveAgentBrowserExecutable }) {
+function makeBrowserTool({ runDir, sessionId, cwd: defaultCwd, headed = false, onProgressEvent, agentBrowserExecutableResolver = resolveAgentBrowserExecutable }) {
 	const captureState = { videoStarted: false };
 	return createAgentCliTool({
 		name: "agent-browser",
@@ -2302,6 +2383,7 @@ function makeBrowserTool({ runDir, sessionId, cwd: defaultCwd, headed = false, a
 				defaultCwd,
 				headed,
 				captureState,
+				onProgressEvent,
 				agentBrowserExecutableResolver,
 				input,
 				signal
@@ -2376,7 +2458,7 @@ async function runBestEffortBrowserCommand({ executable, args, cwd, timeoutMs })
 function parseBrowserToolInput(input) {
 	return parseAgentCliToolInput(BrowserToolInputSchema, input, "agent-browser");
 }
-async function runBrowserCommand({ runDir, sessionId, defaultCwd, headed, captureState, agentBrowserExecutableResolver, input, signal }) {
+async function runBrowserCommand({ runDir, sessionId, defaultCwd, headed, captureState, onProgressEvent, agentBrowserExecutableResolver, input, signal }) {
 	const [executable, ...args] = input.argv;
 	if (executable !== "agent-browser") throw new Error(`Refusing to spawn non-agent-browser executable: ${executable}`);
 	const cwd = input.cwd ?? defaultCwd ?? process.cwd();
@@ -2394,6 +2476,7 @@ async function runBrowserCommand({ runDir, sessionId, defaultCwd, headed, captur
 		cwd,
 		headed,
 		captureState,
+		onProgressEvent,
 		agentBrowserExecutableResolver,
 		signal
 	});
@@ -2463,11 +2546,20 @@ function spawnAgentBrowser({ args, sessionId, cwd, agentBrowserExecutableResolve
 		});
 	});
 }
-async function runPlannedBrowserCommands({ commands, runDir, sessionId, cwd, headed, captureState, agentBrowserExecutableResolver, signal }) {
+async function runPlannedBrowserCommands({ commands, runDir, sessionId, cwd, headed, captureState, onProgressEvent, agentBrowserExecutableResolver, signal }) {
 	const stdout = [];
 	const stderr = [];
 	for (const command of commands) {
 		const args = applyBrowserLaunchArgs(applyRunDefaults(applyHeadedMode(command.args, headed), runDir));
+		const commandLabel = browserCommandLabel(args);
+		emitBrowserProgress(runDir, onProgressEvent, {
+			kind: "action",
+			status: "running",
+			title: `Browser: ${commandLabel}`,
+			summary: "agent-browser is acting on the target application.",
+			importance: "normal",
+			source: "runtime"
+		});
 		const result = await spawnAgentBrowser({
 			args,
 			sessionId,
@@ -2496,12 +2588,30 @@ async function runPlannedBrowserCommands({ commands, runDir, sessionId, cwd, hea
 			signal
 		}));
 		stderr.push(result.stderr);
-		if (!result.ok) return {
-			ok: false,
-			exitCode: result.exitCode,
-			stdout: stdout.join(""),
-			stderr: stderr.join("")
-		};
+		if (!result.ok) {
+			emitBrowserProgress(runDir, onProgressEvent, {
+				kind: "action",
+				status: "failed",
+				title: `Browser: ${commandLabel}`,
+				summary: oneLine(result.stderr || result.stdout || "agent-browser command failed"),
+				importance: "normal",
+				source: "runtime"
+			});
+			return {
+				ok: false,
+				exitCode: result.exitCode,
+				stdout: stdout.join(""),
+				stderr: stderr.join("")
+			};
+		}
+		emitBrowserProgress(runDir, onProgressEvent, {
+			kind: "action",
+			status: "passed",
+			title: `Browser: ${commandLabel}`,
+			summary: "agent-browser completed this target step.",
+			importance: "normal",
+			source: "runtime"
+		});
 	}
 	return {
 		ok: true,
@@ -2510,6 +2620,24 @@ async function runPlannedBrowserCommands({ commands, runDir, sessionId, cwd, hea
 		stderr: stderr.join("")
 	};
 }
+function emitBrowserProgress(runDir, onProgressEvent, event) {
+	const logged = appendRunProgressEvent(runDir, event);
+	onProgressEvent?.(logged);
+}
+function browserCommandLabel(args) {
+	const command = args[0] ?? "command";
+	if (command === "open") return `open ${redactBrowserArg(args[1] ?? "URL")}`;
+	if (command === "batch") return "batch";
+	return command;
+}
+function redactBrowserArg(value) {
+	try {
+		const url = new URL(value);
+		return `${url.origin}${url.pathname}`;
+	} catch {
+		return value.length > 80 ? `${value.slice(0, 77)}…` : value;
+	}
+}
 function augmentBrowserArtifactOutput({ runDir, sessionId, cwd, args, result, agentBrowserExecutableResolver, signal }) {
 	if (!result.ok) return Promise.resolve(result.stdout);
 	const output = [result.stdout];
@@ -2605,27 +2733,35 @@ function hasOption$1(args, option) {
 	return args.some((arg) => arg === option || arg.startsWith(`${option}=`));
 }
 function shouldStartRecordingForCommand(args) {
-	return args[0] === "open";
+	const command = args[0];
+	return command !== void 0 && RECORDING_START_COMMANDS.has(command);
 }
 function shouldCaptureScreenshotAfterCommand$1(args) {
 	const command = args[0];
-	return command !== void 0 && ![
-		"close",
-		"console",
-		"cookies",
-		"diff",
-		"errors",
-		"network",
-		"pdf",
-		"profiler",
-		"record",
-		"screenshot",
-		"set",
-		"skills",
-		"storage",
-		"trace"
-	].includes(command);
+	return command !== void 0 && AUTO_SCREENSHOT_COMMANDS.has(command);
 }
+const RECORDING_START_COMMANDS = new Set([
+	"back",
+	"check",
+	"click",
+	"dblclick",
+	"drag",
+	"fill",
+	"forward",
+	"open",
+	"press",
+	"reload",
+	"select",
+	"type",
+	"uncheck",
+	"upload"
+]);
+const AUTO_SCREENSHOT_COMMANDS = new Set([
+	"back",
+	"forward",
+	"open",
+	"reload"
+]);
 //#endregion
 //#region src/run-artifacts.ts
 function relativeRunPath(runDir, path) {
@@ -2670,14 +2806,19 @@ function publicRunProgressEvent(runDir, event) {
 //#region src/pipeline/handoff-materializer.ts
 function materializeHandoff({ handoff, runDir, continuation, modelUsage, metadata, harness }) {
 	const result = toInvestigationResult(handoff, runDir, continuation, modelUsage);
-	const nextMetadata = updateMetadataWithHandoff(runDir, metadata, handoff, result, harness);
+	const materializedHandoff = materializeHandoffMarkdown(handoff, result.evidence);
+	const materializedResult = {
+		...result,
+		handoffMarkdown: materializedHandoff.handoffMarkdown
+	};
+	const nextMetadata = updateMetadataWithHandoff(runDir, metadata, materializedHandoff, materializedResult, harness);
 	writeRunFinalHandoff(runDir, {
-		handoff,
-		result
+		handoff: materializedHandoff,
+		result: materializedResult
 	});
-	writeHandoffArtifact(runDir, handoff);
+	writeHandoffArtifact(runDir, materializedHandoff);
 	return {
-		result,
+		result: materializedResult,
 		metadata: nextMetadata
 	};
 }
@@ -2714,13 +2855,20 @@ function toInvestigationResult(handoff, runDir, continuation, modelUsage) {
 }
 function appendAutoCapturedEvidence(evidence, runDir) {
 	const seenPaths = new Set(evidence.flatMap((item) => item.path === void 0 ? [] : [item.path]));
-	const autoEvidence = [...readAutoCapturedFiles(runDir.paths.screenshots, runDir, "screenshot"), ...readAutoCapturedFiles(runDir.paths.video, runDir, "recording")].filter((item) => {
+	const autoEvidence = [...selectAutoScreenshotEvidence(evidence, readAutoCapturedFiles(runDir.paths.screenshots, runDir, "screenshot")), ...readAutoCapturedFiles(runDir.paths.video, runDir, "recording")].filter((item) => {
 		if (item.path === void 0 || seenPaths.has(item.path)) return false;
 		seenPaths.add(item.path);
 		return true;
 	});
 	return [...evidence, ...autoEvidence];
 }
+function selectAutoScreenshotEvidence(handoffEvidence, autoScreenshots) {
+	if (handoffEvidence.some((item) => item.kind === "screenshot")) return [];
+	if (autoScreenshots.length <= 2) return autoScreenshots;
+	const first = autoScreenshots[0];
+	const last = autoScreenshots[autoScreenshots.length - 1];
+	return first === void 0 || last === void 0 || first.path === last.path ? autoScreenshots.slice(0, 1) : [first, last];
+}
 function readAutoCapturedFiles(directory, runDir, kind) {
 	if (!existsSync(directory)) return [];
 	try {
@@ -2806,6 +2954,86 @@ function confidenceFor(handoff, evidence) {
 	if (handoff.status !== "reproduced" || evidence.length === 0) return "low";
 	return evidence.length >= 2 ? "high" : "medium";
 }
+const EVIDENCE_SECTION_START = "<!-- quire:evidence-start -->";
+const EVIDENCE_SECTION_END = "<!-- quire:evidence-end -->";
+function materializeHandoffMarkdown(handoff, evidence) {
+	const evidenceSection = renderEvidenceSection(evidence);
+	const handoffMarkdown = withGeneratedEvidenceSection(handoff.handoffMarkdown, evidenceSection);
+	return {
+		...handoff,
+		handoffMarkdown,
+		evidenceRefs: evidence.map((item) => ({
+			kind: item.kind,
+			note: item.note,
+			...item.path === void 0 ? {} : { path: item.path },
+			...item.url === void 0 ? {} : { url: item.url }
+		}))
+	};
+}
+function withGeneratedEvidenceSection(markdown, evidenceSection) {
+	const withoutExisting = markdown.trimEnd().replace(new RegExp(`\\n*${escapeRegExp$1(EVIDENCE_SECTION_START)}[\\s\\S]*?${escapeRegExp$1(EVIDENCE_SECTION_END)}\\s*$`), "");
+	return evidenceSection.length === 0 ? withoutExisting : `${withoutExisting}\n\n${evidenceSection}`;
+}
+function renderEvidenceSection(evidence) {
+	const publicEvidence = evidence.filter((item) => item.path !== void 0 || item.url !== void 0);
+	if (publicEvidence.length === 0) return "";
+	return [
+		EVIDENCE_SECTION_START,
+		"## Evidence artifacts",
+		"",
+		...publicEvidence.flatMap(renderEvidenceItem),
+		EVIDENCE_SECTION_END
+	].join("\n");
+}
+function renderEvidenceItem(item) {
+	const label = `${evidenceDisplayKind(item)} — ${item.note}`;
+	const target = evidenceTarget(item);
+	if (target === void 0) return [];
+	if (isImageEvidence(item)) return [
+		`- ${label}`,
+		`  ![${escapeMarkdownAlt(item.note)}](${target})`,
+		""
+	];
+	if (isVideoEvidence(item)) return [
+		`- ${label}`,
+		`  <video controls src="${escapeHtmlAttribute(target)}"></video>`,
+		`  [Open recording](${target})`,
+		""
+	];
+	return [
+		`- ${label}`,
+		`  [Open artifact](${target})`,
+		""
+	];
+}
+function evidenceDisplayKind(item) {
+	const kind = item.kind.replaceAll("_", " ").trim();
+	return kind.length === 0 ? "Evidence" : `${kind[0]?.toUpperCase() ?? "E"}${kind.slice(1)}`;
+}
+function evidenceTarget(item) {
+	if (item.url !== void 0) return item.url;
+	if (item.path === void 0) return;
+	return `./${item.path.replace(/^\.\//, "")}`;
+}
+function isImageEvidence(item) {
+	const path = item.path?.toLowerCase() ?? "";
+	const kind = item.kind.toLowerCase();
+	return kind.includes("screenshot") || kind.includes("image") || path.endsWith(".png") || path.endsWith(".jpg") || path.endsWith(".jpeg") || path.endsWith(".webp") || path.endsWith(".gif");
+}
+function isVideoEvidence(item) {
+	const path = item.path?.toLowerCase() ?? "";
+	const kind = item.kind.toLowerCase();
+	return kind.includes("recording") || kind.includes("video") || path.endsWith(".webm") || path.endsWith(".mp4");
+}
+function escapeMarkdownAlt(value) {
+	return value.replace(/[[\]\\]/g, " ").replace(/\s+/g, " ").trim();
+}
+function escapeHtmlAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function escapeRegExp$1(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function updateMetadataWithHandoff(runDir, metadata, handoff, result, harness) {
 	const sessionState = readRunSessionState(runDir);
 	return writeRunMetadata(runDir, {
@@ -41110,11 +41338,11 @@ function errorMessage$2(error) {
 }
 //#endregion
 //#region ../../packages/agent-mobile/src/wait/android.ts
-const DEFAULT_TIMEOUT_MS$1 = 1e4;
+const DEFAULT_TIMEOUT_MS$2 = 1e4;
 const POLL_INTERVAL_MS$1 = 400;
 async function waitAndroid(request) {
 	const waitFor = request.waitFor ?? { kind: "settle" };
-	const timeoutMs = waitFor.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
+	const timeoutMs = waitFor.timeoutMs ?? DEFAULT_TIMEOUT_MS$2;
 	if (waitFor.kind === "settle") {
 		await waitForSettle$1(request, waitFor, timeoutMs);
 		return;
@@ -41192,11 +41420,11 @@ function sleep$1(ms) {
 }
 //#endregion
 //#region ../../packages/agent-mobile/src/wait/ios.ts
-const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_TIMEOUT_MS$1 = 1e4;
 const POLL_INTERVAL_MS = 400;
 async function waitIos(request) {
 	const waitFor = request.waitFor ?? { kind: "settle" };
-	const timeoutMs = waitFor.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const timeoutMs = waitFor.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
 	if (waitFor.kind === "settle") {
 		await waitForSettle(request, waitFor, timeoutMs);
 		return;
@@ -44646,48 +44874,293 @@ function shouldCaptureScreenshotAfterCommand(command) {
 	return command !== void 0 && !["install", "screenshot"].includes(command);
 }
 //#endregion
+//#region src/tools/shell-check.ts
+const DEFAULT_TIMEOUT_MS = 12e4;
+const MAX_OUTPUT_CHARS = 6e4;
+const ShellCheckToolInputSchema = Type.Object({
+	command: Type.String({ minLength: 1 }),
+	cwd: Type.Optional(Type.String({ minLength: 1 })),
+	timeoutMs: Type.Optional(Type.Number({
+		minimum: 1e3,
+		maximum: 6e5
+	})),
+	reason: Type.String({ minLength: 1 })
+}, { additionalProperties: false });
+function makeShellCheckTool({ runDir, cwd: defaultCwd, env = process.env }) {
+	return createAgentCliTool({
+		name: "run_shell_check",
+		description: "Run a project shell command for evidence collection, local app startup checks, tests, typechecks, builds, lint/check commands, or source inspection. Clearly dangerous, destructive, deploy, install, database mutation, and external write commands are blocked.",
+		parameters: ShellCheckToolInputSchema,
+		parseInput: parseShellCheckToolInput,
+		runCommand(input, signal) {
+			return runShellCheckCommand({
+				runDir,
+				defaultCwd,
+				env,
+				input,
+				signal
+			});
+		}
+	});
+}
+function parseShellCheckToolInput(input) {
+	return parseAgentCliToolInput(ShellCheckToolInputSchema, input, "run_shell_check");
+}
+async function runShellCheckCommand({ runDir, defaultCwd, env, input, signal }) {
+	const command = input.command.trim();
+	const policy = classifyShellCheckCommand(command);
+	if (!policy.allowed) return {
+		ok: false,
+		exitCode: null,
+		stdout: "",
+		stderr: `Blocked by Quire shell safety policy: ${policy.reason}`,
+		blocked: true,
+		reason: policy.reason
+	};
+	const cwd = input.cwd ?? defaultCwd ?? process.cwd();
+	const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const result = await spawnShell(command, {
+		cwd,
+		env,
+		timeoutMs,
+		signal
+	});
+	const artifactPath = writeShellArtifact(runDir, {
+		command,
+		cwd,
+		reason: input.reason,
+		timeoutMs,
+		...result
+	});
+	const output = {
+		exitCode: result.exitCode,
+		stdout: truncateOutput(redactSecrets(result.stdout)),
+		stderr: `${truncateOutput(redactSecrets(result.stderr))}\n[quire:artifact] shell_check saved to ${artifactPath}\n`.trimStart(),
+		artifactPath
+	};
+	return result.exitCode === 0 ? {
+		ok: true,
+		...output,
+		exitCode: 0
+	} : {
+		ok: false,
+		...output
+	};
+}
+function classifyShellCheckCommand(command) {
+	const trimmed = command.trim();
+	if (trimmed.length === 0) return {
+		allowed: false,
+		reason: "command is empty"
+	};
+	if (/[;&|`$<>]/.test(trimmed)) return {
+		allowed: false,
+		reason: "shell operators, pipes, redirects, and command substitution are not allowed"
+	};
+	const words = splitSimpleCommand(trimmed);
+	if (words === void 0 || words.length === 0) return {
+		allowed: false,
+		reason: "command could not be parsed as a simple command"
+	};
+	const dangerous = firstDangerousToken(words.map((word) => word.toLowerCase()));
+	if (dangerous !== void 0) return {
+		allowed: false,
+		reason: `contains unsafe token ${JSON.stringify(dangerous)}`
+	};
+	return { allowed: true };
+}
+function splitSimpleCommand(command) {
+	const words = [];
+	const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^']*)'|(\S+)/g;
+	let match;
+	let consumed = "";
+	while ((match = pattern.exec(command)) !== null) {
+		consumed += match[0];
+		words.push(match[1] ?? match[2] ?? match[3] ?? "");
+	}
+	if (words.length === 0 || consumed.replace(/\s+/g, "") !== command.replace(/\s+/g, "")) return;
+	return words;
+}
+const DANGEROUS_TOKENS = new Set([
+	"rm",
+	"rmdir",
+	"mv",
+	"cp",
+	"sudo",
+	"chmod",
+	"chown",
+	"kill",
+	"pkill",
+	"reset",
+	"restore",
+	"clean",
+	"checkout",
+	"commit",
+	"push",
+	"publish",
+	"deploy",
+	"release",
+	"install",
+	"add",
+	"remove",
+	"unlink",
+	"migrate",
+	"seed",
+	"drop",
+	"truncate",
+	"delete",
+	"insert",
+	"update",
+	"create",
+	"curl",
+	"wget",
+	"ssh",
+	"scp",
+	"rsync"
+]);
+function firstDangerousToken(words) {
+	return words.find((word) => DANGEROUS_TOKENS.has(word));
+}
+async function spawnShell(command, { cwd, env, timeoutMs, signal }) {
+	return await new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const child = spawn("/bin/sh", ["-lc", command], {
+			cwd,
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const settle = (exitCode, extraStderr = "") => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			resolve({
+				exitCode,
+				stdout,
+				stderr: `${stderr}${extraStderr}`
+			});
+		};
+		const abort = () => {
+			child.kill("SIGTERM");
+			settle(null, "\nCommand aborted.\n");
+		};
+		const timer = setTimeout(() => {
+			child.kill("SIGTERM");
+			settle(null, `\nCommand timed out after ${timeoutMs}ms.\n`);
+		}, timeoutMs);
+		signal?.addEventListener("abort", abort);
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString("utf8");
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString("utf8");
+		});
+		child.on("error", (error) => settle(null, `\n${errorMessage$5(error)}\n`));
+		child.on("close", (code) => settle(code));
+	});
+}
+function writeShellArtifact(runDir, result) {
+	mkdirSync(runDir.paths.trace, {
+		recursive: true,
+		mode: 448
+	});
+	const artifactPath = join(runDir.paths.trace, `shell-check-${Date.now().toString(36)}-${safeArtifactName(result.command.split(/\s+/)[0] ?? "command")}.txt`);
+	writeFileSync(artifactPath, [
+		`$ ${result.command}`,
+		`cwd: ${result.cwd}`,
+		`reason: ${result.reason}`,
+		`timeoutMs: ${result.timeoutMs}`,
+		`exitCode: ${result.exitCode ?? "null"}`,
+		"",
+		"--- stdout ---",
+		redactSecrets(result.stdout),
+		"",
+		"--- stderr ---",
+		redactSecrets(result.stderr)
+	].join("\n"), { mode: 384 });
+	return artifactPath;
+}
+function truncateOutput(value) {
+	if (value.length <= MAX_OUTPUT_CHARS) return value;
+	return `${value.slice(0, MAX_OUTPUT_CHARS)}\n[quire:truncated] output truncated to ${MAX_OUTPUT_CHARS} characters\n`;
+}
+function redactSecrets(value) {
+	return value.replace(/([A-Za-z_][A-Za-z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY)[A-Za-z0-9_]*=)([^\s]+)/gi, "$1[REDACTED]").replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[REDACTED]");
+}
+//#endregion
+//#region src/pipeline/prompts/local-run-safety-contract.ts
+const localRunSafetyContractPrompt = `Local Quire runtime contract:
+
+- Obey the enabled tool list exactly; do not invent unavailable tools or capabilities.
+- Code inspection tools are read-only. Do not edit files, install dependencies, start app servers, reset repositories, or mutate user data.
+- Do not expose hidden reasoning, raw prompts, raw completions, provider credentials, API tokens, or secrets.
+- record_progress writes the user-visible progress.jsonl timeline. write_handoff is the required final action. The durable public product artifacts are progress.jsonl, handoff.md, and referenced evidence. Private harness sessions under .harness-sessions are diagnostic implementation state.`;
+//#endregion
+//#region src/pipeline/prompts/system-instructions.ts
+const systemInstructionsPrompt = `You are Quire, a read-only software run agent for investigation, verification, triage, explanation, and project-specific procedures.
+
+Interpret the run brief first. Infer the user's intent naturally; do not require the user to choose a mode.
+
+Resolve the target, procedure, and blockers from the user request, caller context, project runbook, available tools, and loaded skills.
+
+Do not assume the run is web, mobile, or code-only before reading the brief. Use browser or mobile tools only when they are available and relevant.
+
+When a tool provides its own skills, workflows, or usage guides, load the relevant guidance before using that tool for substantive work. For example, load the relevant \`agent-browser skills get ...\` content before browser-backed QA, exploration, or interaction.
+
+Use read, grep, find, and ls for read-only repository inspection when code can clarify routes, screens, feature names, state requirements, verification commands, or likely causes.
+
+Code inspection can guide exploration, but product behavior claims need direct evidence from the requested surface when the run requires browser or mobile observation.
+
+Before broad exploration or target interaction, call record_progress with kind plan and a concise grounded plan.
+
+Call write_handoff exactly once when the run is complete or blocked.`;
+//#endregion
 //#region src/pipeline/run-instructions.ts
-const DEFAULT_RUN_INSTRUCTIONS_ID = "local-run-2026-06-02";
+const DEFAULT_RUN_INSTRUCTIONS_ID = "local-run-2026-06-06";
 const DEFAULT_REMOTE_RUN_ADDONS_ID = "local-none";
-const LOCAL_RUN_SAFETY_CONTRACT = [
-	"Local Quire runtime contract:",
-	"- Obey the enabled tool list exactly; do not invent unavailable tools or capabilities.",
-	"- Code inspection tools are read-only. Do not edit files, install dependencies, start app servers, reset repositories, or mutate user data.",
-	"- Do not expose hidden reasoning, raw prompts, raw completions, provider credentials, API tokens, or secrets.",
-	"- record_progress writes the user-visible progress.jsonl timeline. write_handoff is the required final action. The durable public product artifacts are progress.jsonl, handoff.md, and referenced evidence. Private harness sessions under .harness-sessions are diagnostic implementation state."
-].join("\n");
-const SYSTEM_INSTRUCTIONS = [
-	"You are Quire, a read-only software run agent for investigation, verification, triage, explanation, and project-specific procedures.",
-	"Interpret the run brief first. Infer the user's intent naturally; do not require the user to choose a mode.",
-	"Resolve the target, procedure, and blockers from the user request, caller context, project runbook, available tools, and loaded skills.",
-	"Do not assume the run is web, mobile, or code-only before reading the brief. Use browser or mobile tools only when they are available and relevant.",
-	"Use read, grep, find, and ls for read-only repository inspection when code can clarify routes, screens, feature names, state requirements, verification commands, or likely causes.",
-	"Code inspection can guide exploration, but product behavior claims need direct evidence from the requested surface when the run requires browser or mobile observation.",
-	"Before broad exploration or target interaction, call record_progress with kind plan and a concise grounded plan.",
-	"Call write_handoff exactly once when the run is complete or blocked."
-].join("\n");
+const LOCAL_RUN_SAFETY_CONTRACT = localRunSafetyContractPrompt.trim();
+const SYSTEM_INSTRUCTIONS = systemInstructionsPrompt.trim();
 const COMMON_GUIDANCE = [
 	"Start by understanding the user request, inferred intent, caller context, runtime capabilities, and project runbook status.",
 	"Read .quire/runbook.md when target context, verification procedures, deployments, local URLs, devices, accounts, or safety conventions are needed.",
 	"If the runbook is missing or insufficient, report the smallest missing context instead of guessing ports, app IDs, accounts, or deployment names.",
 	"Prefer deterministic setup scripts or skills from the runbook over manually repeating login, seed-data, runner, or browser-state setup.",
+	"Use loaded skills as optional QA lenses, not mandatory modes. Select the lenses relevant to the request, target, and available evidence.",
+	"Verification can target browser apps, CLI tools, APIs, mobile apps, docs, static sites, or code paths. Choose the relevant lenses and tools for the target rather than forcing every run through browser UI checks.",
+	"When claiming accessibility, design, responsive, link/form, workflow, CLI, API, mobile, command, or smoke verification, state the evidence boundary. If the boundary was not exercised, mark the check untested or blocked instead of passing it.",
 	"For direct product tasks, perform the requested workflow and report what happened rather than reframing it as a bug.",
 	"For bug reports, reproduce or rule out the reported behavior honestly with concrete evidence.",
+	"When the target is a localhost or dev-server URL, classify framework toolbars, debug panels, dev-only overlays, hot-reload artifacts, and transient local dependency noise as local-dev caveats unless they block the requested check or clearly affect the built/preview/production surface.",
+	"Separate product findings from environment caveats: a broken CTA, inaccessible interaction, or weak visual hierarchy is a product finding; an Astro/Vite/dev toolbar covering a screenshot, a DEV-gated tuning panel, or a local-only dependency fetch warning is an environment caveat unless it reproduces outside dev.",
+	"If local dev caveats obstruct visual evidence or runtime confidence and the request needs production-like assurance, recommend or perform a preview/production-build check when safe and available. Otherwise report the caveat without treating it as a user-facing failure.",
 	"Stay within the target product, URLs, devices, commands, and systems named by the request, caller context, or runbook."
 ];
 const PLANNING_GUIDANCE = [
 	"For any non-trivial run, record a plan before taking broad exploratory actions or interacting with browser/mobile targets.",
+	"The latest structured plan is materialized to plan.md in the run directory for humans and caller agents. Make it useful as an evidence plan: name the claims, boundaries, and evidence sources you expect to gather.",
 	"Ground the plan in the user request, caller context, project runbook, and source/config inspection. Do not invent app paths, ports, setup state, accounts, or device IDs.",
 	"Match each planned assertion to the scope it claims. A file-level or code-only assertion can be supported by file, command, or test evidence; an end-to-end, integration, sync, API, persistence, auth, billing, storage, deployment, browser, or mobile assertion needs evidence from the relevant boundary that makes the claim true.",
 	"If a required boundary cannot be inspected or exercised with available tools, narrow the assertion to what was actually verified or mark the broader assertion as untested or blocked.",
 	"For verification-like requests, name the assertions you will check and later record each assertion as passed, failed, untested, or blocked.",
+	"For verification requests, plan the relevant evidence paths early across available tools: shell checks for builds/tests/typechecks/CLI behavior, browser evidence for web product behavior, mobile evidence for app/device behavior, source/config inspection for implementation boundaries, and MCP/API evidence when configured.",
+	"For post-fix verification, include relevant deterministic project checks from .quire/runbook.md, package scripts, or explicit caller instructions when they are safe and applicable. Use run_shell_check so the command evidence lands in Quire artifacts instead of leaving caller agents to duplicate those checks.",
+	"For web or mobile product verification, capture representative viewport/device evidence and exercise the important interactions, safe links/forms/CTAs, and accessibility basics needed to support the requested claims. Do not stop early while named high-value assertions remain feasible.",
 	"For triage-like requests, name the severity, impact, ownership, reproducibility, and next-action signals you will inspect.",
 	"For investigation-like requests, name the hypotheses, surfaces, code paths, logs, or product states you will examine.",
 	"Record expected behavior before executing the action that tests it; this makes unexpected observations harder to rationalize as success."
 ];
 const TOOL_GUIDANCE = [
+	"Use run_shell_check for non-dangerous project commands that produce useful evidence: local app startup checks, typechecks, builds, tests, lint/check commands, CLI smoke checks, custom project scripts, and read-only git/source inspection. Include the command artifact path in evidenceRefs when it supports an assertion.",
+	"Do not use run_shell_check for installs, deploys, publishing, git mutation, destructive filesystem operations, database writes, seed/migrate commands, or external write requests. If such a command is required, mark it blocked or ask the caller to approve/add a safe runbook procedure.",
 	"Use agent-browser only when the runtime capabilities say browser automation is available.",
 	"Before browser exploration, run agent-browser skills get core once when that skill is available so browser guidance matches the installed CLI.",
+	"For verification-like browser runs, especially QA, dogfooding, design review, accessibility, responsive, link, interaction, or form checks, run agent-browser skills get dogfood once before substantive browser actions when that skill is available. Use core plus dogfood; core alone is insufficient for product QA unless the run is only a tiny page-load smoke test.",
 	"Every agent-browser invocation is recorded as evidence. Do not call non-investigation browser commands such as install, upgrade, doctor, profile, or dashboard during exploration.",
 	"Use agent-mobile only when runtime capabilities say the mobile tool is registered. Treat device, simulator, app, and provider readiness as unknown until the tool or runbook proves them.",
 	"Every agent-mobile invocation is recorded as evidence. Do not call non-replayable commands such as help, doctor, serve, or close during exploration.",
@@ -44722,8 +45195,13 @@ const DEFAULT_HANDOFF_GUIDANCE = [
 	"Use needs_info when the report lacks necessary route, account, data, state, device, runner, or expected-behavior details after reasonable discovery.",
 	"Use environment_blocked when the endpoint, app install/launch, auth, data, network, runner, or browser/mobile tooling prevents reaching the needed state.",
 	"Write handoffMarkdown so a human can understand the verdict without reading raw logs and a coding agent can continue from handoff.md without rerunning the whole exploration.",
+	"Include every artifact that supports the final verdict in write_handoff.evidenceRefs. Use artifactPath for [quire:artifact] paths returned by browser, mobile, or run_shell_check tools.",
+	"Do not rely on prose-only evidence mentions. Quire will append a renderable Evidence artifacts section to handoff.md from public evidenceRefs and auto-captured artifacts.",
+	"Do not include .harness-sessions paths, raw model transcripts, secrets, or private diagnostic state in evidenceRefs or handoffMarkdown.",
+	"For markdown evidence links you write manually, prefer run-relative ./evidence/... paths over absolute local paths.",
 	"Treat progress.jsonl as the canonical structured ledger. handoff.md is the human-readable report view, not the machine-readable source of truth.",
 	"For verification-like requests or runs with structured assertions, use a Verification Report shape with Target, Request, Run, Summary, Results, Pre-existing Issues / Non-regressions when relevant, and Evidence sections.",
+	"For post-fix or regression verification, make the requested claim verdict easy to find, then summarize product evidence, deterministic command evidence, blockers/untested checks, and unrelated or follow-up findings. Use natural prose and concise tables where helpful; do not force boilerplate if a simpler report is clearer.",
 	"For verification-like requests, include a decisive first paragraph with pass, fail, untested, blocked, and unresolved counts plus the strongest supported conclusion.",
 	"For verification-like requests, include a results table with assertion id, check title, verdict, expected, and actual. Include unresolved planned assertions explicitly; unresolved means no assertion record exists, not that the check passed or was untested.",
 	"Keep pre-existing, not-regression, and out-of-scope findings separate from the requested verification verdict.",
@@ -45507,6 +45985,11 @@ function resolveRuntimeCapabilities(input) {
 				available: true,
 				names: [...READ_ONLY_RUN_CODE_TOOL_NAMES]
 			},
+			shellCheck: {
+				available: true,
+				toolName: "run_shell_check",
+				safety: "dangerous_commands_blocked"
+			},
 			browser: browserCapability(input.headed),
 			mobile: mobileCapability(),
 			mcp: {
@@ -45545,6 +46028,7 @@ function composeRunBrief(input) {
 		"## Run Artifacts",
 		`Run directory: ${toJsonPath(input.runDir.root)}`,
 		`Narrated progress file: ${toJsonPath(input.runDir.paths.progress)}`,
+		`Evidence plan file: ${toJsonPath(input.runDir.paths.plan)}`,
 		`Final handoff path: ${toJsonPath(input.runDir.paths.handoff)}`,
 		`Evidence directory: ${toJsonPath(input.runDir.paths.evidence)}`,
 		`Private diagnostic harness session directory: ${toJsonPath(input.runDir.paths.harnessSessions)}`,
@@ -45558,6 +46042,7 @@ function composeRunBrief(input) {
 		"## Planning Requirement",
 		[
 			"Before broad exploration or browser/mobile interaction, record a concise plan with record_progress kind plan.",
+			"The latest structured plan is materialized to plan.md in the run directory so caller agents can see what evidence Quire intends to gather while the run is active.",
 			"For verification-like work, state assertions before checking them and later record each as passed, failed, untested, or blocked.",
 			"For triage-like work, state the severity, impact, ownership, and next-action signals to inspect.",
 			"For investigation-like work, state the hypotheses, surfaces, or evidence paths to examine."
@@ -45643,6 +46128,7 @@ function capabilityLines(capabilities) {
 		`Runner: ${capabilities.runnerKind} on ${capabilities.platform}/${capabilities.arch}`,
 		`Repository cwd: ${toJsonPath(capabilities.cwd)}`,
 		`Read-only code tools: ${capabilities.tools.readOnlyCode.names.join(", ")}`,
+		`Shell checks: ${capabilities.tools.shellCheck.toolName} available for non-dangerous project commands, local app startup checks, and verification evidence`,
 		`Browser automation: ${browser.available ? `${browser.toolName}${browser.headed === true ? " (headed)" : ""}` : `unavailable (${browser.unavailableReason ?? "unknown"})`}`,
 		`Mobile automation: ${mobile.available ? `${mobile.toolName} tool registered; device/app readiness unknown until checked` : `unavailable (${mobile.unavailableReason ?? "unknown"})`}`,
 		`MCP gateway: ${mcp.available ? `available (${mcp.toolNames.length === 0 ? "no tools listed" : mcp.toolNames.join(", ")})` : "unavailable"}`
@@ -45660,15 +46146,16 @@ function followupLines(context) {
 function orderedListOrNone(values) {
 	return values.length === 0 ? "(none provided)" : values.map((value, index) => `${index + 1}. ${value}`).join("\n");
 }
+//#endregion
+//#region src/pipeline/quire-agent.ts
+const RUN_ACTIVITY_HEARTBEAT_INTERVAL_MS = 5e3;
 const QUIRE_AGENT_THINKING_LEVEL = INVESTIGATION_THINKING_LEVEL;
 async function runQuireAgent({ intent, runBrief, runInstructions, remoteAddons, runtimeCapabilities, runDir, sessionId, headed = false, progress, onProgressEvent, followup, skillPack, mcpGateway, onResolvedModel }) {
 	const codebasePath = readRunMetadata(runDir)?.repoPath ?? runDir.root;
 	let emittedHandoff;
 	let observedToolAttempts = 0;
-	let diagnosisSteered = false;
 	const observedTargetToolCallIds = /* @__PURE__ */ new Set();
 	const targetToolCallArgs = /* @__PURE__ */ new Map();
-	const pendingSessionActions = [];
 	const runtime = await createQuireAgentRuntime({
 		runDir,
 		codebasePath,
@@ -45691,23 +46178,16 @@ async function runQuireAgent({ intent, runBrief, runInstructions, remoteAddons,
 		modelId: runtime.model.id
 	});
 	const unsubscribe = session.subscribe((event) => {
+		touchRunActivity(runDir.root, { minIntervalMs: RUN_ACTIVITY_HEARTBEAT_INTERVAL_MS });
 		logAgentProgress(event);
 		emittedHandoff ??= extractWriteHandoff(event);
 		rememberTargetToolCallArgs(event, registeredTargetTools, targetToolCallArgs);
 		const attemptsObserved = countNewTargetAttempts(event, registeredTargetTools, observedTargetToolCallIds, targetToolCallArgs);
-		if (attemptsObserved > 0) {
-			observedToolAttempts += attemptsObserved;
-			if (observedToolAttempts >= 6 && !diagnosisSteered && emittedHandoff === void 0) {
-				diagnosisSteered = true;
-				pendingSessionActions.push(session.steer(buildRunSteeringPrompt(observedToolAttempts, registeredTargetTools)));
-			}
-		}
+		if (attemptsObserved > 0) observedToolAttempts += attemptsObserved;
 	});
 	try {
 		await session.prompt(runBrief, { expandPromptTemplates: false });
-		await Promise.all(pendingSessionActions);
 		if (emittedHandoff === void 0) await session.prompt(buildMissingRunHandoffPrompt(observedToolAttempts), { expandPromptTemplates: false });
-		await Promise.all(pendingSessionActions);
 	} finally {
 		runtime.writeSessionState();
 		unsubscribe();
@@ -45733,12 +46213,17 @@ async function createQuireAgentRuntime({ runDir, codebasePath, sessionId, headed
 		runDir,
 		sessionId,
 		cwd: codebasePath,
-		headed
+		headed,
+		onProgressEvent
 	}) : void 0;
 	const mobileTool = runtimeCapabilities.tools.mobile.available === true ? makeMobileTool({
 		runDir,
 		cwd: codebasePath
 	}) : void 0;
+	const shellCheckTool = makeShellCheckTool({
+		runDir,
+		cwd: codebasePath
+	});
 	const mcpGatewayTool = mcpGateway === void 0 ? void 0 : makeQuireMcpGatewayTool({
 		gateway: mcpGateway,
 		runId: runDir.runId
@@ -45781,6 +46266,7 @@ async function createQuireAgentRuntime({ runDir, codebasePath, sessionId, headed
 		customTools: [
 			...browserTool === void 0 ? [] : [browserTool],
 			...mobileTool === void 0 ? [] : [mobileTool],
+			shellCheckTool,
 			withPromptGuidelines(createRecordProgressTool({
 				runDir,
 				onProgressEvent
@@ -45792,6 +46278,7 @@ async function createQuireAgentRuntime({ runDir, codebasePath, sessionId, headed
 			...READ_ONLY_RUN_CODE_TOOL_NAMES,
 			...browserTool === void 0 ? [] : [browserTool.name],
 			...mobileTool === void 0 ? [] : [mobileTool.name],
+			shellCheckTool.name,
 			"record_progress",
 			writeHandoffTool.name,
 			...mcpGatewayTool === void 0 ? [] : [mcpGatewayTool.name]
@@ -45834,13 +46321,6 @@ function modelSourceProgressMessage(source, model) {
 		case "quire_credits": return `Using Quire Credits via brokered model source (${model.provider}/${model.id}).`;
 	}
 }
-function buildRunSteeringPrompt(attempts, targetTools) {
-	return [
-		`${attempts} browser/mobile-backed attempts have been observed through ${targetTools.map((tool) => tool.toolName).join(", ") || "target tools"}.`,
-		"Stop blind retries. Decide whether the run has enough evidence, needs narrower target context, is blocked by runtime/tooling/account/data, or requires one different action.",
-		"If the run is complete or blocked, call write_handoff now. If more evidence is needed, take the next action that directly tests the diagnosis."
-	].join("\n");
-}
 function buildMissingRunHandoffPrompt(targetActions) {
 	return [
 		"The previous run ended without calling write_handoff.",
@@ -45883,10 +46363,13 @@ function isTargetReproductionAttempt(args, target) {
 	if (args === void 0) return true;
 	if (target === "mobile") {
 		const command = findMobileCommand(args);
-		return command !== "open" && command !== "install";
+		return command !== "open" && command !== "install" && command !== "screenshot";
 	}
-	if (args[0] === "open") return false;
-	if (args[0] === "set" && args[1] === "viewport") return false;
+	const command = args[0];
+	if (command === "open") return false;
+	if (command === "set" && args[1] === "viewport") return false;
+	if (command === "skills") return false;
+	if (command === "snapshot" || command === "screenshot" || command === "get" || command === "eval") return false;
 	return true;
 }
 function rememberToolCallId(toolCallId, observedToolCallIds) {
@@ -48279,8 +48762,8 @@ function defaultSleep$1(ms) {
 const ARTIFACT_MODE = "evidence";
 const investigationCommandSchema = {
 	version: 1,
-	command: "quire investigate",
-	description: "Starts a durable Quire investigation for a natural-language question or piped brief.",
+	command: "quire run",
+	description: "Starts a durable Quire run for a natural-language request or piped brief. Bare `quire \"<prompt>\"` is equivalent to `quire run \"<prompt>\"`.",
 	defaultMode: "attached",
 	input: {
 		pipedStdin: true,
@@ -48290,7 +48773,7 @@ const investigationCommandSchema = {
 	stdout: {
 		human: "Without --json, stdout shows a short start summary and attaches to the live run log unless --detach is passed.",
 		json: "With --json, stdout contains exactly one newline-terminated JSON start handle and does not attach to the live log.",
-		schema: "With --schema, stdout contains this newline-terminated JSON schema and no investigation starts."
+		schema: "With --schema, stdout contains this newline-terminated JSON schema and no run starts."
 	},
 	stderr: { progress: "Machine-readable errors are written to stderr. Human attached runs stream live run logs after the start summary." },
 	arguments: [
@@ -48299,7 +48782,7 @@ const investigationCommandSchema = {
 			type: "string",
 			positional: true,
 			requiredUnless: "piped stdin",
-			description: "Natural-language investigation query or instruction."
+			description: "Natural-language run request or instruction."
 		},
 		{
 			name: "--json",
@@ -48382,21 +48865,20 @@ const investigationCommandSchema = {
 	safety: ["Raw model thinking, prompts, completions, provider credentials, API tokens, and local absolute repo paths are not synced to the web case.", "Sync failures are non-fatal for local investigations; local artifacts and retry state remain in the run directory."],
 	examples: [
 		"quire \"verify checkout before I approve this PR\"",
-		"printf 'why is CI failing?\\nRelevant log: ...' | quire investigate --json",
+		"printf 'why is CI failing?\\nRelevant log: ...' | quire run --json",
 		"quire status run_9x4mdq7p2h8kc6nv4apz --json",
 		"quire watch run_9x4mdq7p2h8kc6nv4apz"
 	]
 };
-const investigateCommand = defineCommand({
+const quireRunCommand = defineCommand({
 	meta: {
-		name: "investigate",
-		alias: "ask",
-		description: "Investigate a question against the current workspace."
+		name: "run",
+		description: "Run evidence-backed QA, verification, triage, or investigation work."
 	},
 	args: {
 		prompt: {
 			type: "positional",
-			description: "Natural-language investigation query.",
+			description: "Natural-language run request.",
 			required: false
 		},
 		url: {
@@ -48419,11 +48901,11 @@ const investigateCommand = defineCommand({
 		},
 		headed: {
 			type: "boolean",
-			description: "Show the browser window while the investigation agent runs."
+			description: "Show the browser window while the Quire agent runs."
 		},
 		schema: {
 			type: "boolean",
-			description: "Emit the machine-readable investigation invocation schema and exit."
+			description: "Emit the machine-readable run invocation schema and exit."
 		}
 	},
 	async run({ args }) {
@@ -48466,7 +48948,7 @@ async function runInvestigate(options) {
 	});
 	if (options.json === true) writeJson(stdout, handle);
 	else {
-		log.success(`Started investigation ${color.value(handle.runId)}.`, {
+		log.success(`Started run ${color.value(handle.runId)}.`, {
 			output: stdout,
 			spacing: 0
 		});
@@ -48480,7 +48962,12 @@ async function runInvestigate(options) {
 			spacing: 0,
 			withGuide: true
 		});
-		else log.message(`${color.label("Run")}: ${color.path(handle.runPath)}`, {
+		else log.message([
+			`${color.label("Run")}: ${color.path(handle.runPath)}`,
+			`${color.label("Status")}: ${color.command(handle.statusCommand)}`,
+			`${color.label("Watch")}: ${color.command(handle.watchCommand)}`,
+			`This run continues in the background. You can safely exit; use ${color.command(handle.statusCommand)} for the current state or ${color.command(handle.watchCommand)} to follow progress logs.`
+		], {
 			output: stdout,
 			spacing: 0,
 			withGuide: true
@@ -48631,6 +49118,7 @@ function createDoctorContext(overrides = {}) {
 		cwd: resolve(overrides.cwd ?? process.cwd()),
 		runsRoot: resolve(overrides.runsRoot ?? defaultRunsRoot()),
 		authStore: overrides.authStore ?? authStore,
+		env: overrides.env ?? process.env,
 		fetchFn: overrides.fetchFn ?? fetch,
 		execFn: overrides.execFn ?? defaultExecFn,
 		probeTimeoutMs: overrides.probeTimeoutMs ?? 2e3
@@ -48647,25 +49135,30 @@ async function defaultExecFn(file, args, options) {
 	};
 }
 async function checkAuthPresent(context) {
-	const credentials = await resolveAuthCredentials({ store: context.authStore });
+	const source = context.env["QUIRE_API_TOKEN"]?.trim() ? "env_api_token" : "stored_login";
+	const credentials = await resolveAuthCredentials({
+		store: context.authStore,
+		env: context.env
+	});
 	if (credentials === null) return { result: {
 		id: "auth.present",
 		section: "identity",
 		severity: "fail",
-		message: "No Quire credentials on this machine.",
-		fix: { command: "quire login" }
+		message: "No Quire credentials found. Authenticate with an API token or interactive login.",
+		fix: { command: "Set QUIRE_API_TOKEN or run `quire login`" }
 	} };
 	return {
 		result: {
 			id: "auth.present",
 			section: "identity",
 			severity: "pass",
-			message: "Credentials present."
+			message: `Credentials present (${authSourceLabel(source)}; API ${credentials.apiBaseUrl}).`
 		},
 		auth: {
 			apiBaseUrl: credentials.apiBaseUrl,
 			accessToken: credentials.accessToken,
 			tokenType: credentials.tokenType,
+			source,
 			...credentials.user === void 0 ? {} : { user: credentials.user }
 		}
 	};
@@ -48688,8 +49181,8 @@ async function checkAuthValid(context, auth) {
 			id: "auth.valid",
 			section: "identity",
 			severity: "fail",
-			message: `Could not validate Quire API token: ${toMessage(error)}`,
-			fix: { command: "Set QUIRE_API_TOKEN to an active token from Quire settings" }
+			message: `Could not validate API token against ${auth.apiBaseUrl}: ${toMessage(error)}`,
+			fix: { command: apiTokenFixCommand(auth.apiBaseUrl) }
 		} };
 	}
 	try {
@@ -48703,8 +49196,8 @@ async function checkAuthValid(context, auth) {
 			id: "auth.valid",
 			section: "identity",
 			severity: "fail",
-			message: "Stored credentials were rejected by Quire.",
-			fix: { command: "quire login" }
+			message: `Stored login was rejected by ${auth.apiBaseUrl}.`,
+			fix: { command: loginFixCommand(auth.apiBaseUrl) }
 		} };
 		const user = lookup.data.user;
 		return {
@@ -48721,8 +49214,8 @@ async function checkAuthValid(context, auth) {
 			id: "auth.valid",
 			section: "identity",
 			severity: "fail",
-			message: `Could not validate Quire session: ${toMessage(error)}`,
-			fix: { command: "quire login" }
+			message: `Could not validate stored login against ${auth.apiBaseUrl}: ${toMessage(error)}`,
+			fix: { command: loginFixCommand(auth.apiBaseUrl) }
 		} };
 	}
 }
@@ -48764,6 +49257,15 @@ function brokerToCheckResult(status) {
 		message: `Model broker available (${status.selectedProviderMode ?? "default"}).`
 	};
 }
+function authSourceLabel(source) {
+	return source === "env_api_token" ? `${QUIRE_API_TOKEN_ENV} API token` : "stored login";
+}
+function apiTokenFixCommand(apiBaseUrl) {
+	return `Set QUIRE_API_TOKEN to an active token for ${apiBaseUrl}; set QUIRE_API_URL if that API URL is wrong; or run \`quire login --api-url ${apiBaseUrl}\``;
+}
+function loginFixCommand(apiBaseUrl) {
+	return `Run \`quire login --api-url ${apiBaseUrl}\`, or set QUIRE_API_TOKEN and QUIRE_API_URL for API-token auth`;
+}
 async function checkRunbook(context) {
 	const runbook = await inspectProjectRunbookStatus(context.cwd);
 	if (!runbook.exists) return {
@@ -49176,22 +49678,78 @@ async function runLogout(options) {
 //#endregion
 //#region src/commands/setup.ts
 const SETUP_URL = "https://quire.sh/agent-setup";
+const VERIFICATION_SKILL_URL = "https://quire.sh/agent-verification";
 const AGENT_SETUP_PROMPT = `Set up this repository for Quire investigations.
 
 Please load and follow the Quire agent setup instructions from ${SETUP_URL}.
 
-Inspect the project, create the smallest useful .quire/runbook.md with target-resolution, verification, and safety instructions, update AGENTS.md with concise run and verification notes for future agents, then run quire doctor if available and report anything still blocked.`;
+Inspect the project, ask focused questions for important missing runbook facts instead of writing placeholder unknowns, then create a .quire/runbook.md that encodes the best-practices verification loop for this specific project. Capture how Quire should self-verify work in this domain: target/environment choice, local startup, browser/API/CLI/mobile checks, console/runtime signals, core flows, verification commands, design/reference surfaces, auth/data setup, performance/accessibility expectations, and mutation-safety rules. Update AGENTS.md with concise Quire notes, then run Quire doctor using the available Quire command, e.g. \`quire doctor\` or \`npx @quireco/cli doctor\`, and report anything still blocked.`;
+const QUIRE_SKILL_MARKDOWN = `---
+name: quire
+description: Runs Quire CLI evidence-backed QA, verification, triage, and investigation work. Use after implementing UI or workflow changes, when testing local/preview/prod URLs, or when claims need screenshots, command output, observations, and a trustworthy handoff.
+---
+
+# Quire verification
+
+Load and follow the current Quire verification skill from ${VERIFICATION_SKILL_URL}.
+
+Use Quire when a task needs evidence-backed verification, QA, product dogfooding, bug reproduction, or triage. Prefer \`quire run\` for new work.
+`;
+const SKILL_INSTALL_TARGETS = [{
+	id: "agents",
+	label: "Universal",
+	targetPath: ".agents/skills/quire/SKILL.md",
+	hint: "~/.agents/skills/quire/SKILL.md · Pi, OpenCode, Amp, Codex-style agents",
+	aliases: [
+		"agents",
+		"agent-skills",
+		"pi",
+		"opencode",
+		"amp",
+		"codex",
+		"other"
+	]
+}, {
+	id: "claude",
+	label: "Claude Code",
+	targetPath: ".claude/skills/quire/SKILL.md",
+	hint: "~/.claude/skills/quire/SKILL.md",
+	aliases: ["claude", "claude-code"]
+}];
 const setupCommand = defineCommand({
 	meta: {
 		name: "setup",
 		description: "Prepare this workspace for Quire investigations."
 	},
-	async run() {
-		await runSetup();
+	args: {
+		skill: {
+			type: "string",
+			description: "Comma-separated local agent skill targets to install: agents, claude, all, none.",
+			valueHint: "targets"
+		},
+		"no-skill": {
+			type: "boolean",
+			description: "Skip installing local Quire agent skills."
+		},
+		"no-interactive": {
+			type: "boolean",
+			description: "Do not prompt; use default setup choices."
+		}
+	},
+	async run({ args }) {
+		await runSetup({
+			skill: args["no-skill"] === true ? false : args.skill,
+			interactive: args["no-interactive"] !== true
+		});
 	}
 });
 async function runSetup(options = {}) {
 	const stdout = options.io?.stdout ?? process.stdout;
+	const selectedTargets = await selectSkillInstallTargets({
+		skill: options.skill,
+		interactive: options.interactive ?? (options.io?.stdout === void 0 && process.stdout.isTTY === true)
+	});
+	const installedSkills = await installQuireSkill(options.homeDir ?? homedir(), selectedTargets);
 	log.step("Set up Quire for this workspace", {
 		output: stdout,
 		spacing: 0
@@ -49205,6 +49763,51 @@ async function runSetup(options = {}) {
 	writeLine(stdout, color.label("--- copy prompt ---"));
 	writeLine(stdout, AGENT_SETUP_PROMPT);
 	writeLine(stdout, color.label("--- end prompt ---"));
+	if (installedSkills.length > 0) {
+		writeLine(stdout);
+		writeLine(stdout, color.label("Installed local Quire skill:"));
+		for (const path of installedSkills) writeLine(stdout, `  ${color.success("✓")} ${path}`);
+	}
+}
+async function selectSkillInstallTargets(options) {
+	if (options.skill === false || options.skill === "none") return [];
+	if (options.skill !== void 0) return resolveSkillTargets(options.skill);
+	if (!options.interactive) return [...SKILL_INSTALL_TARGETS];
+	const selected = await multiselect({
+		message: "Which local agent skill directories should Quire install into?",
+		options: SKILL_INSTALL_TARGETS.map((target) => ({
+			label: target.label,
+			value: target.id,
+			hint: target.hint
+		})),
+		initialValues: ["agents", "claude"],
+		required: false
+	});
+	if (isCancel(selected) || selected.length === 0) return [];
+	return resolveSkillTargets(selected.join(","));
+}
+function resolveSkillTargets(value) {
+	const parts = value.split(",").map((part) => part.trim().toLowerCase()).filter((part) => part.length > 0);
+	if (parts.includes("all")) return [...SKILL_INSTALL_TARGETS];
+	const selected = /* @__PURE__ */ new Map();
+	for (const part of parts) {
+		const target = SKILL_INSTALL_TARGETS.find((candidate) => candidate.id === part || candidate.aliases.includes(part));
+		if (target !== void 0) selected.set(target.id, target);
+	}
+	return [...selected.values()];
+}
+async function installQuireSkill(homeDir, targets) {
+	const installed = [];
+	await Promise.all(targets.map(async (target) => {
+		const path = join(homeDir, target.targetPath);
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(path, QUIRE_SKILL_MARKDOWN, { mode: 384 });
+		installed.push(path);
+	}));
+	return installed.sort();
 }
 //#endregion
 //#region src/commands/whoami.ts
@@ -49356,7 +49959,7 @@ function formatWalletBalance(value) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.0.9";
+var version$1 = "0.0.10";
 //#endregion
 //#region src/cli.ts
 const subCommands = {
@@ -49382,18 +49985,14 @@ const subCommands = {
 	continue: continueCommand,
 	doctor: doctorCommand,
 	env: envCommand,
-	investigate: investigateCommand,
+	run: quireRunCommand,
 	runs: runsCommand,
 	setup: setupCommand,
 	status: statusCommand,
 	sync: syncCommand,
 	watch: watchCommand
 };
-const subCommandAliases = new Set([
-	"ask",
-	"me",
-	"resume"
-]);
+const subCommandAliases = new Set(["me", "resume"]);
 const cli = defineCommand({
 	meta: {
 		name: "quire",
@@ -49427,7 +50026,7 @@ function isVersionRequest(rawArgs) {
 function normalizeRawArgs(rawArgs) {
 	const first = rawArgs[0];
 	if (first === void 0 || isTopLevelFlag(first) || isSubCommandName(first)) return rawArgs;
-	return ["investigate", ...rawArgs];
+	return ["run", ...rawArgs];
 }
 function isTopLevelFlag(arg) {
 	return arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v";