@gajae-code/coding-agent 0.17.2 → 0.17.5

package/src/tools/fetch.ts

@@ -11,15 +11,20 @@ import { type Theme, theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
 import type { AgentStorage } from "../session/agent-storage";
 import { DEFAULT_MAX_BYTES, type TruncationDirection, truncateContent } from "../session/streaming-output";
-import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
+import { renderStatusLine } from "../tui/status-line";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { parseHtmlLazy } from "../utils/linkedom";
 import { INSANE_NOTES } from "../web/insane/bridge";
 import { validatePublicHttpUrl } from "../web/insane/url-guard";
-import { specialHandlers } from "../web/scrapers";
-import type { RenderResult } from "../web/scrapers/types";
-import { finalizeOutput, loadPage, looksLikeHtml, MAX_OUTPUT_CHARS } from "../web/scrapers/types";
+import {
+	finalizeOutput,
+	loadPage,
+	looksLikeHtml,
+	MAX_OUTPUT_CHARS,
+	type RenderResult,
+	type SpecialHandler,
+} from "../web/scrapers/types";
 import { convertWithMarkit, fetchBinary } from "../web/scrapers/utils";
 import { applyListLimit } from "./list-limit";
 import { formatStyledArtifactReference, type OutputMeta } from "./output-meta";
@@ -30,6 +35,12 @@ import { clampTimeout } from "./tool-timeouts";
 
 type NativeHtmlBindings = { htmlToMarkdown: typeof htmlToMarkdownFn };
 let nativeHtmlBindings: NativeHtmlBindings | undefined;
+let specialHandlersCache: SpecialHandler[] | undefined;
+
+function getSpecialHandlers(): SpecialHandler[] {
+	specialHandlersCache ??= (require("../web/scrapers") as { specialHandlers: SpecialHandler[] }).specialHandlers;
+	return specialHandlersCache;
+}
 
 /**
  * Lazy native access for HTML conversion. The module is cached, never the
@@ -49,6 +60,7 @@ const FETCH_DEFAULT_MAX_LINES = 300;
 // Convertible document types handled by markit.
 const CONVERTIBLE_MIMES = new Set([
 	"application/pdf",
+	"application/x-pdf",
 	"application/msword",
 	"application/vnd.ms-powerpoint",
 	"application/vnd.ms-excel",
@@ -228,17 +240,52 @@ function normalizeMime(contentType: string): string {
 	return contentType.split(";")[0].trim().toLowerCase();
 }
 
+// Bound both parsing work and decoded filename size to a single modest header.
+function getDispositionFilename(header: string): string | undefined {
+	if (header.length > 8192 || /[\x00-\x1f\x7f]/.test(header.replaceAll("\t", ""))) return undefined;
+	const separator = header.indexOf(";");
+	if (separator < 0) return undefined;
+	const parameter = /;[ \t]*([!#$%&'*+.^_`|~\w-]+)[ \t]*=[ \t]*(?:"((?:[^"\\]|\\.)*)"|([!#$%&'*+.^_`|~\w-]+))[ \t]*/y;
+	let offset = separator;
+	let plain: string | undefined;
+	let extended: string | undefined;
+	const seen = new Set<string>();
+	while (offset < header.length) {
+		parameter.lastIndex = offset;
+		const match = parameter.exec(header);
+		if (!match) return undefined;
+		offset = parameter.lastIndex;
+		const name = match[1].toLowerCase();
+		if (name !== "filename" && name !== "filename*") continue;
+		// Duplicate filename parameters are ambiguous, not an ordering override.
+		if (seen.has(name)) return undefined;
+		seen.add(name);
+		const value = match[2] === undefined ? match[3] : match[2].replace(/\\(.)/g, "$1");
+		if (name === "filename") {
+			if (value) plain = value;
+			continue;
+		}
+		// RFC 8187 ext-value: only UTF-8 is supported; quoted ext-values are invalid.
+		const encoded =
+			match[2] === undefined ? /^UTF-8'[A-Za-z0-9-]*'((?:[!#$&+.^_`|~\w-]|%[\da-fA-F]{2})*)$/i.exec(value) : null;
+		if (!encoded) continue;
+		try {
+			const decoded = decodeURIComponent(encoded[1]);
+			if (decoded && !/[\x00-\x1f\x7f]/.test(decoded)) extended = decoded;
+		} catch {
+			// Invalid UTF-8 or percent encoding must not escape classification.
+		}
+	}
+	return extended ?? plain;
+}
+
 /**
  * Get extension from URL or Content-Disposition
  */
 function getExtensionHint(url: string, contentDisposition?: string): string {
-	// Try Content-Disposition filename first
 	if (contentDisposition) {
-		const match = contentDisposition.match(/filename[*]?=["']?([^"';\n]+)/i);
-		if (match) {
-			const ext = path.extname(match[1]).toLowerCase();
-			if (ext) return ext;
-		}
+		const filename = getDispositionFilename(contentDisposition);
+		if (filename !== undefined) return path.extname(filename).toLowerCase();
 	}
 
 	// Fall back to URL path
@@ -251,21 +298,25 @@ function getExtensionHint(url: string, contentDisposition?: string): string {
 	return "";
 }
 
+function isGenericMimeType(mime: string): boolean {
+	return (
+		mime.length === 0 || mime === "application/octet-stream" || mime === "binary/octet-stream" || mime === "unknown"
+	);
+}
+
 /**
  * Check if content type is convertible via markit.
  */
 function isConvertible(mime: string, extensionHint: string): boolean {
-	if (CONVERTIBLE_MIMES.has(mime)) return true;
-	if (mime === "application/octet-stream" && CONVERTIBLE_EXTENSIONS.has(extensionHint)) return true;
-	if (CONVERTIBLE_EXTENSIONS.has(extensionHint)) return true;
-	return false;
+	return (
+		CONVERTIBLE_MIMES.has(mime) ||
+		(CONVERTIBLE_EXTENSIONS.has(extensionHint) && (extensionHint !== ".pdf" || isGenericMimeType(mime)))
+	);
 }
 
 function resolveImageMimeType(mime: string, extensionHint: string): string | null {
 	if (mime.startsWith("image/")) return mime;
-	const shouldUseExtensionHint =
-		mime.length === 0 || mime === "application/octet-stream" || mime === "binary/octet-stream" || mime === "unknown";
-	if (!shouldUseExtensionHint) return null;
+	if (!isGenericMimeType(mime)) return null;
 	return IMAGE_MIME_BY_EXTENSION.get(extensionHint) ?? null;
 }
 
@@ -619,7 +670,7 @@ async function handleSpecialUrls(
 	signal: AbortSignal | undefined,
 	storage: AgentStorage | null,
 ): Promise<FetchRenderResult | null> {
-	for (const handler of specialHandlers) {
+	for (const handler of getSpecialHandlers()) {
 		if (signal?.aborted) {
 			throw new ToolAbortError();
 		}
@@ -629,6 +680,11 @@ async function handleSpecialUrls(
 	return null;
 }
 
+/** Test-only seam for verifying lazy special-handler loading and dispatch. */
+export const fetchSpecialHandlerTestHooks = {
+	dispatch: handleSpecialUrls,
+};
+
 // =============================================================================
 // Main Render Function
 // =============================================================================
@@ -741,15 +797,60 @@ async function renderUrl(
 	const { finalUrl, content: rawContent } = response;
 	const mime = normalizeMime(response.contentType);
 	const extHint = getExtensionHint(finalUrl);
+	let isPdf =
+		mime === "application/pdf" || mime === "application/x-pdf" || (extHint === ".pdf" && isGenericMimeType(mime));
+
+	// Raw PDF inspection is explicit; never substitute PDF bytes for failed text extraction.
+	if (raw && isPdf) {
+		const output = finalizeOutput(rawContent);
+		return {
+			url,
+			finalUrl,
+			contentType: mime,
+			method: "raw",
+			content: output.content,
+			fetchedAt,
+			truncated: output.truncated,
+			notes,
+		};
+	}
 
-	const imageMimeType = resolveImageMimeType(mime, extHint);
+	// Classify generic downloads from the bounded binary response before dispatch.
+	// Both image rendering and document conversion reuse these bytes.
+	const dispositionBinary =
+		!raw && isGenericMimeType(mime)
+			? response.buffer
+				? { ok: true as const, buffer: response.buffer, contentDisposition: response.contentDisposition }
+				: await fetchBinary(finalUrl, timeout, signal)
+			: undefined;
+	if (dispositionBinary && !dispositionBinary.ok) {
+		notes.push(dispositionBinary.error ? `Binary fetch failed: ${dispositionBinary.error}` : "Binary fetch failed");
+		return {
+			url,
+			finalUrl,
+			contentType: mime,
+			method: "failed",
+			content: "",
+			fetchedAt,
+			truncated: false,
+			notes,
+		};
+	}
+	const effectiveExt = dispositionBinary?.ok
+		? getExtensionHint(finalUrl, dispositionBinary.contentDisposition)
+		: extHint;
+	isPdf =
+		mime === "application/pdf" ||
+		mime === "application/x-pdf" ||
+		(effectiveExt === ".pdf" && isGenericMimeType(mime));
+	const imageMimeType = isPdf ? undefined : resolveImageMimeType(mime, effectiveExt);
 	let skipConvertibleBinaryRetry = false;
 	if (imageMimeType) {
 		if (!isInlineImageMimeTypeSupported(imageMimeType)) {
 			notes.push(
 				`Image MIME type ${imageMimeType} is unsupported for inline model serialization; returning text metadata only`,
 			);
-			const shouldTryConvertibleFallback = isConvertible(mime, extHint);
+			const shouldTryConvertibleFallback = isConvertible(mime, effectiveExt);
 			if (shouldTryConvertibleFallback) {
 				notes.push("Attempting binary conversion fallback for unsupported image MIME type");
 			} else {
@@ -757,7 +858,7 @@ async function renderUrl(
 			}
 			skipConvertibleBinaryRetry = !shouldTryConvertibleFallback;
 		} else {
-			const binary = await fetchBinary(finalUrl, timeout, signal);
+			const binary = dispositionBinary ?? (await fetchBinary(finalUrl, timeout, signal));
 			if (binary.ok) {
 				notes.push("Fetched image binary");
 				const conversionExtension = getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
@@ -868,10 +969,10 @@ async function renderUrl(
 	}
 
 	// Step 3: Handle convertible binary files (PDF, DOCX, etc.)
-	if (!skipConvertibleBinaryRetry && isConvertible(mime, extHint)) {
-		const binary = await fetchBinary(finalUrl, timeout, signal);
+	if (!skipConvertibleBinaryRetry && (isPdf || isConvertible(mime, effectiveExt))) {
+		const binary = dispositionBinary ?? (await fetchBinary(finalUrl, timeout, signal));
 		if (binary.ok) {
-			const ext = getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
+			const ext = isPdf ? ".pdf" : getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
 			const converted = await convertWithMarkit(binary.buffer, ext, timeout, signal);
 			if (converted.ok) {
 				// Any non-empty markit conversion is preferable to a raw-bytes
@@ -902,6 +1003,18 @@ async function renderUrl(
 		} else {
 			notes.push("Binary fetch failed");
 		}
+		if (isPdf) {
+			return {
+				url,
+				finalUrl,
+				contentType: mime,
+				method: "failed",
+				content: "",
+				fetchedAt,
+				truncated: false,
+				notes,
+			};
+		}
 	}
 
 	// Step 4: Handle non-HTML text content
@@ -1066,7 +1179,7 @@ async function renderUrl(
 				if (binary.ok) {
 					const ext = getExtensionHint(docUrl, binary.contentDisposition);
 					const converted = await convertWithMarkit(binary.buffer, ext, timeout, signal);
-					if (converted.ok && converted.content.trim().length > htmlResult.content.length) {
+					if (converted.ok && converted.content.trim().length > (ext === ".pdf" ? 0 : htmlResult.content.length)) {
 						notes.push(`Extracted and converted document: ${docUrl}`);
 						const output = finalizeOutput(converted.content);
 						return {
@@ -1082,6 +1195,8 @@ async function renderUrl(
 					}
 					if (!converted.ok && converted.error) {
 						notes.push(`markit conversion failed: ${converted.error}`);
+					} else if (converted.ok && !converted.content.trim()) {
+						notes.push("markit conversion produced no usable output");
 					}
 				} else if (binary.error) {
 					notes.push(`Binary fetch failed: ${binary.error}`);

package/src/tools/job.ts

@@ -7,6 +7,7 @@ import { type AsyncJob, AsyncJobManager, type FoldReason, isBackgroundJobSupport
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import jobDescription from "../prompts/tools/job.md" with { type: "text" };
+import type { FoldAdapter } from "../session/fold-coordinator";
 import { lookupOwnedRegistration, unregisterOwnedRegistration } from "../session/terminal-abort";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from "./index";
@@ -21,6 +22,7 @@ import {
 	type ToolUIColor,
 	type ToolUIStatus,
 } from "./render-utils";
+import { foldAwaitReasonLine, watchSteerForFold } from "./steer-fold";
 import { ToolError } from "./tool-errors";
 
 const jobSchema = z.object({
@@ -47,7 +49,9 @@ function parseWaitDurationMs(value: string | undefined): number {
 interface JobSnapshot {
 	id: string;
 	type: "bash" | "task";
-	status: "running" | "completed" | "failed" | "cancelled";
+	// Mirrors the manager's job statuses, including "paused": a folded subagent
+	// stays listed and resumable, so its snapshot is paused rather than terminal.
+	status: "running" | "paused" | "completed" | "failed" | "cancelled";
 	label: string;
 	durationMs: number;
 	/** Present when the job was folded out of a foreground wait. */
@@ -56,6 +60,11 @@ interface JobSnapshot {
 	errorText?: string;
 }
 
+/** Terminal statuses are the ones a consumer may treat as finished work. */
+function isTerminalJobStatus(status: JobSnapshot["status"]): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled";
+}
+
 type CancelStatus = "cancelled" | "not_found" | "already_completed" | "already_cancelled";
 
 interface CancelOutcome {
@@ -234,6 +243,73 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		const waitMs = parseWaitDurationMs(this.session.settings.get("async.pollWaitDuration"));
 		const { promise: timeoutPromise, resolve: timeoutResolve } = Promise.withResolvers<void>();
 		const timeoutHandle = setTimeout(() => timeoutResolve(), waitMs);
+		// Settled the moment ANY watched wait is released by a fold, so the await
+		// never outlives its own fold. `job-await` adapters are never implicit
+		// chord / SDK-control targets (the jobs are already in the background);
+		// only the steer watcher below folds them, explicitly. `task`/`subagent`
+		// waits are a non-goal, so task-backed jobs are watched but never folded.
+		const foldedAwait = Promise.withResolvers<void>();
+		const foldedJobs = new Map<string, FoldReason>();
+		const foldTargets: Array<{ adapter: FoldAdapter; release: (reason: FoldReason) => boolean }> = [];
+		const unregisterFoldAdapters: Array<() => void> = [];
+		const startedAt = Date.now();
+		for (const job of runningJobs) {
+			if (job.type === "task" || job.metadata?.subagent !== undefined) continue;
+			const generation = job.generation;
+			let detached = false;
+			const release = (reason: FoldReason): boolean => {
+				if (detached) return false;
+				detached = true;
+				manager.markBackgrounded(job.id, generation, reason);
+				foldedJobs.set(job.id, reason);
+				foldedAwait.resolve();
+				return true;
+			};
+			const adapter: FoldAdapter = {
+				kind: "job-await",
+				jobId: job.id,
+				jobGeneration: generation,
+				label: job.label,
+				cwdSensitive: false,
+				signal,
+				originatingTurn: false,
+				outputRef: {
+					jobId: job.id,
+					generation,
+					instruction: `Use the job tool's tail operation for ${job.id} to read this job's output.`,
+				},
+				getJob: () => {
+					const current = manager.getJob(job.id);
+					return current?.generation === generation ? current : undefined;
+				},
+				detachObserver: receipt => (release(receipt.reason) ? "resolved" : "already-settled"),
+				resolveForegroundObserver: () => (detached ? "already-settled" : "resolved"),
+			};
+			foldTargets.push({ adapter, release });
+			unregisterFoldAdapters.push(this.session.registerForegroundFoldParticipant?.(adapter) ?? (() => {}));
+		}
+		// Fold every foldable wait on one steer. A job that an earlier fold already
+		// moved still owns its receipt slot until it completes, so the coordinator
+		// refuses a second fold for it; that receipt already guarantees the wake,
+		// so this await is simply released for it. Every other job folds through
+		// the coordinator, whose `detachObserver` call releases the await with the
+		// recorded reason.
+		const stopSteerWatch =
+			foldTargets.length > 0
+				? watchSteerForFold(this.session, startedAt, async fold => {
+						await Promise.all(
+							foldTargets.map(async ({ adapter, release }) => {
+								const current = adapter.getJob();
+								if (current?.status !== "running") return;
+								if (current.metadata?.foldReason !== undefined) {
+									release("steer");
+									return;
+								}
+								await fold("steer", adapter);
+							}),
+						);
+					})
+				: () => {};
 		racePromises.push(timeoutPromise);
 
 		const watchedJobIds = runningJobs.map(job => job.id);
@@ -277,25 +353,35 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 				signal.addEventListener("abort", onAbort, { once: true });
 				racePromises.push(abortPromise);
 				try {
-					await Promise.race(racePromises);
+					await Promise.race([...racePromises, foldedAwait.promise]);
 				} finally {
 					signal.removeEventListener("abort", onAbort);
 				}
 			} else {
-				await Promise.race(racePromises);
+				await Promise.race([...racePromises, foldedAwait.promise]);
 			}
 		} finally {
+			stopSteerWatch();
+			for (const unregister of unregisterFoldAdapters) unregister();
 			manager.unwatchJobs(watchedJobIds);
 			clearTimeout(timeoutHandle);
 			if (progressTimer) clearInterval(progressTimer);
 		}
 
-		return this.#buildResult(
+		const result = this.#buildResult(
 			manager,
 			allTrackedJobs,
 			cancelOutcomes,
 			this.#readOutputTails(manager, params.tail, ownerFilter),
 		);
+		if (foldedJobs.size > 0) {
+			const existingText = result.content.find(block => block.type === "text")?.text ?? "";
+			return {
+				...result,
+				content: [{ type: "text", text: `${existingText}\n\n${foldAwaitReasonLine(foldedJobs)}`.trim() }],
+			};
+		}
+		return result;
 	}
 
 	/**
@@ -396,9 +482,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		// — otherwise a scope:"owned" abort could find an empty causal set and
 		// report stopped_owned while the job remains visibly paused (review
 		// thread P2).
-		const terminalJobs = jobResults.filter(
-			j => j.status === "completed" || j.status === "failed" || j.status === "cancelled",
-		);
+		const terminalJobs = jobResults.filter(j => isTerminalJobStatus(j.status));
 		manager.acknowledgeDeliveries(terminalJobs.map(j => j.id));
 		// A terminal job whose deliveries were just acknowledged is
 		// synchronously consumed: its owned registration is settled and must
@@ -417,8 +501,11 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			if (registration) unregisterOwnedRegistration(registration);
 		}
 
-		const completed = jobResults.filter(j => j.status !== "running");
-		const running = jobResults.filter(j => j.status === "running");
+		const runningJobs = jobResults.filter(j => j.status === "running");
+		// Paused work (a folded or queued-resume subagent) and any status this build
+		// does not know are non-terminal: reporting them under ## Completed would
+		// tell consumers that resumable work finished.
+		const waitingJobs = jobResults.filter(j => !isTerminalJobStatus(j.status) && j.status !== "running");
 
 		const lines: string[] = [];
 
@@ -428,9 +515,9 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			lines.push("");
 		}
 
-		if (completed.length > 0) {
-			lines.push(`## Completed (${completed.length})\n`);
-			for (const j of completed) {
+		if (terminalJobs.length > 0) {
+			lines.push(`## Completed (${terminalJobs.length})\n`);
+			for (const j of terminalJobs) {
 				lines.push(`### ${j.id} [${j.type}] — ${j.status}`);
 				lines.push(`Label: ${j.label}`);
 				if (j.resultText) {
@@ -443,13 +530,20 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			}
 		}
 
-		if (running.length > 0) {
-			lines.push(`## Still Running (${running.length})\n`);
-			for (const j of running) {
+		if (runningJobs.length > 0) {
+			lines.push(`## Still Running (${runningJobs.length})\n`);
+			for (const j of runningJobs) {
 				lines.push(`- \`${j.id}\` [${j.type}] — ${j.label}`);
 			}
 		}
 
+		if (waitingJobs.length > 0) {
+			lines.push(`## Waiting (${waitingJobs.length})\n`);
+			for (const j of waitingJobs) {
+				lines.push(`- \`${j.id}\` [${j.type}] — ${j.label} (${j.status})`);
+			}
+		}
+
 		if (outputTails.length > 0) {
 			lines.push("", `## Retained Output (${outputTails.length})\n`);
 			for (const tail of outputTails) {
@@ -498,6 +592,12 @@ function statusToIcon(status: JobSnapshot["status"]): ToolUIStatus {
 			return "aborted";
 		case "running":
 			return "running";
+		case "paused":
+			return "pending";
+		// Snapshot details are read back from persisted sessions, so a status this
+		// build does not know must still render instead of dropping the component.
+		default:
+			return "pending";
 	}
 }
 
@@ -511,6 +611,12 @@ function statusToColor(status: JobSnapshot["status"]): ToolUIColor {
 			return "warning";
 		case "running":
 			return "accent";
+		case "paused":
+			return "muted";
+		// Never fall through to undefined: theme.fg() throws on an undefined color
+		// and would take the whole job list render down with it.
+		default:
+			return "muted";
 	}
 }
 
@@ -554,19 +660,36 @@ export const jobToolRenderer = {
 			return new Text([header, formatEmptyMessage(fallback, uiTheme)].join("\n"), 0, 0);
 		}
 
-		const counts = { completed: 0, failed: 0, cancelled: 0, running: 0 };
-		for (const job of jobs) counts[job.status]++;
+		const counts: Record<JobSnapshot["status"], number> = {
+			running: 0,
+			paused: 0,
+			completed: 0,
+			failed: 0,
+			cancelled: 0,
+		};
+		// Snapshots are read back from persisted sessions, so a status this build
+		// does not know must stay out of the typed counts instead of becoming NaN.
+		let unknownStatusCount = 0;
+		for (const job of jobs) {
+			if (job.status in counts) counts[job.status] += 1;
+			else unknownStatusCount += 1;
+		}
 
 		const meta: string[] = [];
 		if (counts.completed > 0) meta.push(uiTheme.fg("success", `${counts.completed} done`));
 		if (counts.failed > 0) meta.push(uiTheme.fg("error", `${counts.failed} failed`));
 		if (counts.cancelled > 0) meta.push(uiTheme.fg("warning", `${counts.cancelled} cancelled`));
+		if (counts.paused > 0) meta.push(uiTheme.fg("muted", `${counts.paused} paused`));
 		if (counts.running > 0) meta.push(uiTheme.fg("accent", `${counts.running} running`));
+		if (unknownStatusCount > 0) meta.push(uiTheme.fg("muted", `${unknownStatusCount} unknown`));
 
-		const headerIcon: ToolUIStatus = counts.failed > 0 ? "warning" : counts.running > 0 ? "info" : "success";
+		// Paused and unknown-status rows are unsettled work: reporting success and a
+		// "settled" description for a resumable snapshot would contradict the rows.
+		const pendingCount = counts.running + counts.paused + unknownStatusCount;
+		const headerIcon: ToolUIStatus = counts.failed > 0 ? "warning" : pendingCount > 0 ? "info" : "success";
 		const description =
-			counts.running > 0
-				? `waiting on ${counts.running} of ${jobs.length}`
+			pendingCount > 0
+				? `waiting on ${pendingCount} of ${jobs.length}`
 				: `${jobs.length} ${jobs.length === 1 ? "job" : "jobs"} settled`;
 
 		const header = renderStatusLine(
@@ -580,15 +703,18 @@ export const jobToolRenderer = {
 			uiTheme,
 		);
 
-		// Sort: running first (so user sees what's still pending), then failed, then completed/cancelled.
+		// Sort: running first (so user sees what's still pending), then paused, then
+		// failed, then completed/cancelled.
 		const statusOrder: Record<JobSnapshot["status"], number> = {
 			running: 0,
-			failed: 1,
-			cancelled: 2,
-			completed: 3,
+			paused: 1,
+			failed: 2,
+			cancelled: 3,
+			completed: 4,
 		};
+		const statusRank = (status: JobSnapshot["status"]): number => statusOrder[status] ?? Number.MAX_SAFE_INTEGER;
 		const sortedJobs = [...jobs].sort((a, b) => {
-			const diff = statusOrder[a.status] - statusOrder[b.status];
+			const diff = statusRank(a.status) - statusRank(b.status);
 			if (diff !== 0) return diff;
 			return b.durationMs - a.durationMs;
 		});

package/src/tools/output-meta.ts

@@ -26,7 +26,7 @@ import {
 } from "../session/streaming-output";
 
 import { formatBytes, wrapBrackets } from "./render-utils";
-import { renderError } from "./tool-errors";
+import { renderError, ToolError } from "./tool-errors";
 
 /**
  * Truncation metadata for the output notice.
@@ -1130,7 +1130,20 @@ async function wrappedExecute(
 		}
 		return result;
 	} catch (e) {
-		// Re-throw with formatted message so agent-loop sets isError flag
+		// Preserve the original Error class and stack so designed tool outcomes can
+		// be classified by the agent telemetry path and genuine failures retain the
+		// frame where they actually occurred. Non-Error throws still need a stable
+		// Error envelope for the agent loop.
+		if (e instanceof ToolError) {
+			const rendered = renderError(e);
+			if (rendered !== e.message) {
+				const renderedError = new ToolError(rendered, e.context);
+				if (e.stack) renderedError.stack = e.stack;
+				throw renderedError;
+			}
+			throw e;
+		}
+		if (e instanceof Error) throw e;
 		throw new Error(renderError(e));
 	}
 }

package/src/tools/path-utils.ts

@@ -48,6 +48,18 @@ function rawSkillPrefixForName(authority: string, skillName: string): string | u
 	return undefined;
 }
 
+function splitSkillPathSel(rawPath: string, authorityEnd: number): { path: string; sel?: string } {
+	const suffix = rawPath.slice(authorityEnd);
+	const suffixQueryOrFragment = suffix.search(/[?#]/);
+	const pathnameEnd = suffixQueryOrFragment === -1 ? rawPath.length : authorityEnd + suffixQueryOrFragment;
+	const pathnameTarget = splitPathAndSel(rawPath.slice(authorityEnd, pathnameEnd));
+	if (pathnameTarget.sel === undefined) return { path: rawPath };
+	return {
+		path: `${rawPath.slice(0, authorityEnd)}${pathnameTarget.path}${rawPath.slice(pathnameEnd)}`,
+		sel: pathnameTarget.sel,
+	};
+}
+
 function tryMacOSScreenshotPath(filePath: string): string {
 	// macOS writes a narrow no-break space before AM/PM, but the model normalizes it
 	// to a plain space. The original name is not always `…PM.png`: attachment paths
@@ -177,6 +189,9 @@ export function splitInternalUrlSel(
 	const schemeMatch = rawPath.match(INTERNAL_URL_SCHEME_RE);
 	if (!schemeMatch) return { path: rawPath };
 	const scheme = schemeMatch[1].toLowerCase();
+	// `embedded://gjc/<path>` identifies a bundled file, so the selector always
+	// trails the path rather than the identifier-shaped authority.
+	if (scheme === "embedded") return splitPathAndSel(rawPath);
 	if (!INTERNAL_SCHEMES_WITH_SELECTORS[scheme]) return { path: rawPath };
 
 	const schemeEnd = schemeMatch[0].length;
@@ -185,7 +200,14 @@ export function splitInternalUrlSel(
 	const authority = rawPath.slice(schemeEnd, authorityEnd);
 	const authoritySuffix = rawPath.slice(authorityEnd);
 	const firstColon = authority.indexOf(":");
-	if (firstColon === -1) return { path: rawPath };
+	if (firstColon === -1) {
+		if (scheme === "skill") {
+			// Skill relative paths carry selectors after the authority (for example,
+			// `skill://foo/docs/reference.md:10-20`).
+			return splitSkillPathSel(rawPath, authorityEnd);
+		}
+		return { path: rawPath };
+	}
 	if (firstColon === 0) return { path: rawPath };
 
 	if (scheme === "skill") {
@@ -197,7 +219,9 @@ export function splitInternalUrlSel(
 			// Let the resolver report malformed URL encoding when no selector boundary
 			// can be established from the raw authority.
 		}
-		if (decodedAuthority !== undefined && activeSkillNames.includes(decodedAuthority)) return { path: rawPath };
+		if (decodedAuthority !== undefined && activeSkillNames.includes(decodedAuthority)) {
+			return splitSkillPathSel(rawPath, authorityEnd);
+		}
 		const rawSkillPrefix = activeSkillNames
 			.map(name => ({ name, prefix: rawSkillPrefixForName(authority, name) }))
 			.filter(item => item.prefix !== undefined)
@@ -217,7 +241,7 @@ export function splitInternalUrlSel(
 			return { path: `${rawPath.slice(0, schemeEnd + firstColon)}${authoritySuffix}`, sel: firstTail };
 		}
 		const selectorColon = authority.indexOf(":", firstColon + 1);
-		if (selectorColon === -1) return { path: rawPath };
+		if (selectorColon === -1) return splitSkillPathSel(rawPath, authorityEnd);
 		return {
 			path: `${rawPath.slice(0, schemeEnd + selectorColon)}${authoritySuffix}`,
 			sel: authority.slice(selectorColon + 1),