@oh-my-pi/pi-coding-agent 16.3.3 → 16.3.5

package/dist/types/hindsight/content.d.ts

@@ -64,6 +64,10 @@ export interface RetentionTranscript {
     transcript: string | null;
     messageCount: number;
 }
+/** Remove retention framing lines from a stored coding-agent episode transcript. */
+export declare function stripRetentionProtocolMarkers(content: string): string;
 export declare function prepareRetentionTranscript(messages: HindsightMessage[], retainFullWindow?: boolean): RetentionTranscript;
+/** Format all retention messages without protocol markers for embedding, FTS, and recall display. */
+export declare function prepareEmbeddableRetentionTranscript(messages: HindsightMessage[]): RetentionTranscript;
 /** Format only user-authored messages for memory fact/entity extraction. */
 export declare function prepareUserRetentionTranscript(messages: HindsightMessage[]): RetentionTranscript;

package/dist/types/internal-urls/artifact-protocol.d.ts

@@ -1,4 +1,12 @@
 import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+/** Filesystem location for a session artifact, resolved without materializing its content. */
+export interface ResolvedArtifactFile {
+    id: string;
+    path: string;
+    size: number;
+}
+/** Resolve an `artifact://` URL to its backing file without reading artifact bytes. */
+export declare function resolveArtifactFile(url: InternalUrl, context?: ResolveContext): Promise<ResolvedArtifactFile>;
 export declare class ArtifactProtocolHandler implements ProtocolHandler {
     readonly scheme = "artifact";
     readonly immutable = true;

package/dist/types/internal-urls/types.d.ts

@@ -102,6 +102,16 @@ export interface ResolveContext {
      * reject directory resources, so they never need the listing.
      */
     skipDirectoryListing?: boolean;
+    /**
+     * When set, handlers that would otherwise materialize expensive content
+     * (e.g. reading a multi-MiB artifact into memory just to expose its
+     * `sourcePath`) may return the resource shape without content. Callers
+     * that only need `sourcePath` — search/grep, bash URL expansion — pass
+     * this so a large `artifact://` still resolves to its backing file
+     * without OOM risk. Handlers that cannot separate path from content
+     * ignore the flag.
+     */
+    pathOnly?: boolean;
 }
 /**
  * Caller context for write operations dispatched to host-owned URI handlers.

package/dist/types/lsp/config.d.ts

@@ -8,6 +8,10 @@ export interface LspConfig {
  * Check if any root marker file exists in the directory
  */
 export declare function hasRootMarkers(cwd: string, markers: string[]): boolean;
+/**
+ * Check whether any ancestor directory of a file is an LSP project root.
+ */
+export declare function hasRootMarkerAncestor(filePath: string, markers: string[]): boolean;
 /**
  * Resolve a command to an executable path.
  * Checks project-local bin directories first, then falls back to $PATH.

package/dist/types/lsp/edits.d.ts

@@ -11,6 +11,8 @@ export declare function rangesOverlap(a: Range, b: Range): boolean;
  * Equal start positions tiebreak by original array index descending so that,
  * applied bottom-up, inserts at the same position land in array order
  * (LSP spec: the order of edits in the array defines the order in the result).
+ * Byte-identical non-empty range edits are idempotent, so duplicate server
+ * output is collapsed before overlap validation.
  */
 export declare function sortAndValidateTextEdits(edits: TextEdit[]): TextEdit[];
 /**

package/dist/types/mcp/oauth-discovery.d.ts

@@ -12,9 +12,26 @@ export interface AuthDetectionResult {
     oauth?: OAuthEndpoints;
     authServerUrl?: string;
     resourceMetadataUrl?: string;
+    /**
+     * OAuth scopes advertised by the challenge (RFC 6750 `scope=` on
+     * `WWW-Authenticate`) or by protected-resource metadata. Passed through
+     * `discoverOAuthEndpoints` as `protectedScopes` so the eventual
+     * authorization request carries them even when the auth-server metadata
+     * document itself omits `scopes_supported`.
+     */
+    scopes?: string;
     message?: string;
 }
 export declare function extractMcpAuthServerUrl(error: Error, serverUrl?: string): string | undefined;
+/**
+ * Pull the `scope`/`scopes` parameter out of a `WWW-Authenticate` challenge
+ * embedded in the error message. RFC 6750 lets servers advertise the missing
+ * scopes when they reject a bearer token with `insufficient_scope`, and RFC
+ * 8414-adjacent MCP gateways sometimes list the required scopes there rather
+ * than in `scopes_supported`. Returns the raw space-separated value, or
+ * `undefined` when the challenge does not carry one.
+ */
+export declare function extractOAuthChallengeScopes(error: Error): string | undefined;
 /**
  * Extract OAuth endpoints from error response.
  * Looks for WWW-Authenticate header format or JSON error bodies.
@@ -25,6 +42,18 @@ export declare function extractOAuthEndpoints(error: Error): OAuthEndpoints | nu
  * Returns structured info about what auth is needed.
  */
 export declare function analyzeAuthError(error: Error, serverUrl?: string): AuthDetectionResult;
+/**
+ * Fetch the RFC 9728 protected-resource metadata document at
+ * {@link resourceMetadataUrl} and return any scopes it advertises. Used by
+ * `/mcp add` / `/mcp reauth` on the JSON-error-body path, where the caller
+ * already holds usable OAuth endpoints but the required scopes live only in
+ * the advertised protected-resource metadata — a case `discoverOAuthEndpoints`
+ * normally handles but that path is skipped when the body carried endpoints.
+ * Returns `undefined` on any error or when no scopes are advertised.
+ */
+export declare function fetchResourceMetadataScopes(resourceMetadataUrl: string, opts?: {
+    fetch?: FetchImpl;
+}): Promise<string | undefined>;
 /**
  * Try to discover OAuth endpoints by querying the server's well-known endpoints.
  * This is a fallback when error responses don't include OAuth metadata.
@@ -32,4 +61,5 @@ export declare function analyzeAuthError(error: Error, serverUrl?: string): Auth
 export declare function discoverOAuthEndpoints(serverUrl: string, authServerUrl?: string, resourceMetadataUrl?: string, opts?: {
     fetch?: FetchImpl;
     protectedResource?: string;
+    protectedScopes?: string;
 }): Promise<OAuthEndpoints | null>;

package/dist/types/modes/components/login-dialog.d.ts

@@ -8,9 +8,17 @@ export declare class LoginDialogComponent extends Container {
     constructor(tui: TUI, providerId: string, onComplete: (success: boolean, message?: string) => void);
     get signal(): AbortSignal;
     /**
-     * Called by onAuth callback - show URL and optional instructions
+     * Called by the OAuth `onAuth` callback. Renders the full authorization URL
+     * as the primary copy target — that works from any machine, including
+     * SSH/WSL/headless sessions where the OMP-hosted `launchUrl` would resolve
+     * against the user's local browser and fail. When `launchUrl` is present it
+     * is offered as an additional local shortcut so narrow local terminals still
+     * have a truncation-safe copy target (viewport clipping on a long authorize
+     * URL silently drops trailing OAuth query parameters — e.g.
+     * `code_challenge_method=S256`). The OSC 8 hyperlink carries the full URL
+     * for terminals that support click-through.
      */
-    showAuth(url: string, instructions?: string): void;
+    showAuth(url: string, instructions?: string, launchUrl?: string): void;
     /**
      * Show input for manual code/URL entry (for callback server providers)
      */

package/dist/types/modes/components/transcript-container.d.ts

@@ -31,7 +31,6 @@ export declare class TranscriptContainer extends Container implements NativeScro
     getNativeScrollbackLiveRegionStart(): number | undefined;
     getNativeScrollbackCommitSafeEnd(): number | undefined;
     getNativeScrollbackSnapshotSafeEnd(): number | undefined;
-    getNativeScrollbackOfferSafeEnd(): number | undefined;
     /**
      * Whether `component` sits below a still-mutating block — i.e. inside the
      * live region, where its rows cannot have been committed to native

package/dist/types/modes/controllers/mcp-command-controller.d.ts

@@ -1,11 +1,28 @@
 import { type Component } from "@oh-my-pi/pi-tui";
 import type { InteractiveModeContext } from "../types";
-/** Renders the MCP OAuth fallback URL without hard-wrapping the copy target. */
+/**
+ * Renders the MCP OAuth fallback URL. Always shows the full authorization URL
+ * as the primary `Copy URL:` target — that works from any machine, including
+ * SSH/WSL/headless sessions where the OMP-hosted `/launch` loopback URL would
+ * resolve against the user's local browser and fail.
+ *
+ * The render is `width`-aware: on any viewport narrower than the composed row
+ * ({@link TUI#prepareLine} truncates anything wider with `Ellipsis.Omit`, no
+ * marker), the URL is hard-wrapped into width-fitted rows so the primary copy
+ * target can never silently lose trailing OAuth parameters — the failure mode
+ * that motivated #4418 in the first place. Browsers strip whitespace when a
+ * multi-row selection is pasted into the address bar, so the reassembled URL
+ * is byte-identical to what we rendered.
+ *
+ * When the flow's callback server hosts a short `launchUrl`, it is offered
+ * as an additional local shortcut for wide-terminal local users. The OSC 8
+ * hyperlink continues to carry the full URL for terminals that support it.
+ */
 export declare class MCPAuthorizationLinkPrompt implements Component {
     #private;
-    constructor(url: string);
+    constructor(url: string, launchUrl?: string);
     invalidate(): void;
-    render(_width: number): readonly string[];
+    render(width: number): readonly string[];
 }
 /**
  * Thrown by {@link MCPCommandController}'s OAuth handler when the user (or a

package/dist/types/modes/rpc/rpc-client.d.ts

@@ -271,11 +271,15 @@ export declare class RpcClient {
      * The server will emit an `open_url` extension_ui_request for the auth URL.
      * Resolves when login completes or rejects on failure.
      *
-     * @param onOpenUrl Called when the server emits the auth URL. The host must open
-     *   it in a browser for the callback-server OAuth flow to complete.
+     * @param onOpenUrl Called when the server emits the auth URL. The host must
+     *   open `url` in a browser for the callback-server OAuth flow to complete.
+     *   When the flow's callback server hosts a `/launch` redirect, `launchUrl`
+     *   is a short loopback URL that 302s to `url` — hosts SHOULD surface it as
+     *   the truncation-safe copy target so terminal viewport clipping cannot
+     *   corrupt trailing OAuth query parameters (e.g. `code_challenge_method=S256`).
      */
     login(providerId: string, options?: {
-        onOpenUrl?: (url: string, instructions?: string) => void;
+        onOpenUrl?: (url: string, instructions?: string, launchUrl?: string) => void;
     }): Promise<{
         providerId: string;
     }>;

package/dist/types/modes/rpc/rpc-types.d.ts

@@ -599,6 +599,12 @@ export type RpcExtensionUIRequest = {
     id: string;
     method: "open_url";
     url: string;
+    /**
+     * Short loopback URL that 302-redirects to {@link url}. When present,
+     * hosts SHOULD surface it as the copy target so terminal viewport
+     * truncation cannot corrupt OAuth query parameters on the full URL.
+     */
+    launchUrl?: string;
     instructions?: string;
 };
 export interface RpcHostToolDefinition {

package/dist/types/subprocess/worker-runtime.d.ts

@@ -69,6 +69,11 @@ export declare function replayCachedReady<K, M>(cache: Map<K, Promise<M>>, model
  * runtime's `node_modules` directory.
  */
 export declare function installSharpStubResolver(runtimeDir: string): Promise<string>;
+/**
+ * Repairs the compiled Transformers side runtime when CUDA was requested and
+ * Bun skipped `onnxruntime-node`'s NuGet sidecar install.
+ */
+export declare function ensureOnnxRuntimeCudaProviders(runtimeDir: string, device?: string | undefined): Promise<void>;
 /**
  * Lazily resolve (and memoize) the transformers version spec. In the `catalog:`
  * case {@link resolveTransformersVersionSpec} `require`s the installed
@@ -88,6 +93,12 @@ interface ConfigurableTransformers {
         ERROR: unknown;
     };
 }
+export interface TransformersRuntimeMetadata {
+    __ompRuntimeNodeModules?: string;
+    __ompTransformersEntry?: string;
+    __ompCudaRepairError?: string;
+}
+export declare function formatOnnxRuntimeCudaDiagnostics(metadata: TransformersRuntimeMetadata, requestedDevice: string, error: unknown): Promise<string | null>;
 /**
  * Memoize an async runtime load so it runs at most once per process, clearing
  * the cache on failure so a later call can retry. Each worker holds one

package/dist/types/tools/bash-skill-urls.d.ts

@@ -1,9 +1,9 @@
 import type { Skill } from "../extensibility/skills";
 import { type LocalProtocolOptions } from "../internal-urls";
-import type { InternalResource } from "../internal-urls/types";
+import type { InternalResource, ResolveContext } from "../internal-urls/types";
 interface InternalUrlResolver {
     canHandle(input: string): boolean;
-    resolve(input: string): Promise<InternalResource>;
+    resolve(input: string, context?: ResolveContext): Promise<InternalResource>;
 }
 export interface InternalUrlExpansionOptions {
     skills: readonly Skill[];

package/dist/types/utils/git.d.ts

@@ -324,6 +324,22 @@ export declare const patch: {
 };
 export declare const cherryPick: ((cwd: string, revision: string, signal?: AbortSignal) => Promise<void>) & {
     abort(cwd: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Skip the current commit of an in-progress cherry-pick sequence and
+     * continue with the rest of the range. Use after {@link isEmptyError}
+     * reports the current attempt collapsed to a no-op — the alternative,
+     * `--abort`, throws away every remaining commit in the range.
+     */
+    skip(cwd: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * True when a cherry-pick failure was caused by the current commit
+     * being empty against HEAD — either redundant with an already-applied
+     * change, or auto-resolved to HEAD by a 3-way merge. Callers should
+     * `--skip` in this case to advance the sequencer rather than aborting
+     * the whole range: an empty commit is not a merge conflict, and any
+     * later commits in the range still deserve to land.
+     */
+    isEmptyError(err: unknown): boolean;
 };
 export declare const stash: {
     /** Stash working tree + index changes. Returns true when git created a new stash entry. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.3.3",
+	"version": "16.3.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -56,17 +56,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.3.3",
-		"@oh-my-pi/omp-stats": "16.3.3",
-		"@oh-my-pi/pi-agent-core": "16.3.3",
-		"@oh-my-pi/pi-ai": "16.3.3",
-		"@oh-my-pi/pi-catalog": "16.3.3",
-		"@oh-my-pi/pi-mnemopi": "16.3.3",
-		"@oh-my-pi/pi-natives": "16.3.3",
-		"@oh-my-pi/pi-tui": "16.3.3",
-		"@oh-my-pi/pi-utils": "16.3.3",
-		"@oh-my-pi/pi-wire": "16.3.3",
-		"@oh-my-pi/snapcompact": "16.3.3",
+		"@oh-my-pi/hashline": "16.3.5",
+		"@oh-my-pi/omp-stats": "16.3.5",
+		"@oh-my-pi/pi-agent-core": "16.3.5",
+		"@oh-my-pi/pi-ai": "16.3.5",
+		"@oh-my-pi/pi-catalog": "16.3.5",
+		"@oh-my-pi/pi-mnemopi": "16.3.5",
+		"@oh-my-pi/pi-natives": "16.3.5",
+		"@oh-my-pi/pi-tui": "16.3.5",
+		"@oh-my-pi/pi-utils": "16.3.5",
+		"@oh-my-pi/pi-wire": "16.3.5",
+		"@oh-my-pi/snapcompact": "16.3.5",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/cli/auth-broker-cli.ts

@@ -222,8 +222,19 @@ async function runLocalLogin(provider: OAuthProvider): Promise<void> {
 		// for non-paste-code providers, so this is defense-in-depth on the same gate.
 		const usesManualInput = PASTE_CODE_LOGIN_PROVIDERS.has(provider);
 		await storage.login(provider, {
-			onAuth({ url, instructions }) {
-				process.stdout.write(`\nOpen this URL in your browser:\n${url}\n`);
+			onAuth({ url, launchUrl, instructions }) {
+				process.stdout.write("\nOpen this URL in your browser:\n");
+				// Full URL first so the CLI works from any machine, including SSH
+				// sessions where a `launchUrl` (loopback `/launch` on the OMP
+				// host) would resolve against the caller's browser and fail.
+				// Headless capture is unaffected: it reads the first URL line.
+				process.stdout.write(`${url}\n`);
+				if (launchUrl && launchUrl !== url) {
+					// Local shortcut for the machine running OMP. Terminals or
+					// screen-scrapers narrower than the full URL still get an
+					// unbroken copy target here.
+					process.stdout.write(`Local shortcut (this machine only): ${launchUrl}\n`);
+				}
 				if (instructions) process.stdout.write(`${instructions}\n`);
 				process.stdout.write("\n");
 			},

package/src/cli/tiny-models-cli.ts

@@ -35,12 +35,19 @@ function writeLine(text = ""): void {
 	process.stdout.write(`${text}\n`);
 }
 
+const ACTIONABLE_DOWNLOAD_ERROR_LINE = /PI_TINY_|CUDA|cuDNN|cudnn|libcudnn|tiny-title-runtime|onnxruntime-node/i;
+
 function downloadErrorSummary(error: string | undefined): string | undefined {
-	return error
-		?.split(/\r?\n/)
-		.map(line => line.trim())
-		.find(line => line.length > 0)
-		?.replace(/^Error:\s*/, "");
+	const lines =
+		error
+			?.split(/\r?\n/)
+			.map(line => line.trim().replace(/^Error:\s*/, ""))
+			.filter(line => line.length > 0) ?? [];
+	const first = lines[0];
+	if (!first) return undefined;
+	const details = lines.slice(1).filter(line => ACTIONABLE_DOWNLOAD_ERROR_LINE.test(line));
+	if (details.length === 0) return first;
+	return [first, ...details].join("\n");
 }
 
 export function resolveModels(model: string | undefined): TinyLocalModelKey[] {

package/src/cli/usage-cli.ts

@@ -370,6 +370,29 @@ function formatLimitLine(limit: UsageLimit, labelWidth: number, nowMs: number):
 	return lines;
 }
 
+interface ProviderLimitTemplate {
+	id: string;
+	title: string;
+}
+
+function collectProviderLimitTemplates(reports: UsageReport[]): ProviderLimitTemplate[] {
+	const seen = new Set<string>();
+	const templates: ProviderLimitTemplate[] = [];
+	for (const report of reports) {
+		for (const limit of report.limits) {
+			if (seen.has(limit.id)) continue;
+			seen.add(limit.id);
+			templates.push({ id: limit.id, title: limitTitle(limit) });
+		}
+	}
+	return templates;
+}
+
+function formatMissingLimitLine(template: ProviderLimitTemplate, labelWidth: number): string {
+	const padded = template.title.padEnd(labelWidth);
+	return `      ${chalk.dim("○")} ${padded}  ${chalk.dim("·".repeat(BAR_WIDTH))}  ${chalk.dim("not reported")}`;
+}
+
 /** Per-window capacity stat: how much account quota is burned and left. */
 export interface ProviderWindowStat {
 	/** Compact window label, e.g. "5h", "7d". */
@@ -474,9 +497,8 @@ export function formatUsageBreakdown(
 		for (const note of providerNotes)
 			lines.push(`  ${chalk.dim(sanitizeText(note.replace(/[\r\n]+/g, " ").replace(/\t/g, "  ")))}`);
 
-		const labelWidth = providerReports
-			.flatMap(report => report.limits)
-			.reduce((max, limit) => Math.max(max, limitTitle(limit).length), 0);
+		const providerLimitTemplates = collectProviderLimitTemplates(providerReports);
+		const labelWidth = providerLimitTemplates.reduce((max, template) => Math.max(max, template.title.length), 0);
 
 		providerReports.forEach((report, index) => {
 			lines.push(`  ${formatAccountHeader(report, index, nowMs, redaction)}`);
@@ -484,8 +506,15 @@ export function formatUsageBreakdown(
 				lines.push(`      ${chalk.dim("no limits reported")}`);
 				return;
 			}
-			for (const limit of report.limits) {
-				lines.push(...formatLimitLine(limit, labelWidth, nowMs));
+			const limitsById = new Map<string, UsageLimit>();
+			for (const limit of report.limits) limitsById.set(limit.id, limit);
+			for (const template of providerLimitTemplates) {
+				const limit = limitsById.get(template.id);
+				if (limit) {
+					lines.push(...formatLimitLine(limit, labelWidth, nowMs));
+				} else {
+					lines.push(formatMissingLimitLine(template, labelWidth));
+				}
 			}
 		});
 

package/src/hindsight/content.ts

@@ -25,6 +25,7 @@ const LEGACY_HINDSIGHT_MEMORIES_REGEX = /<hindsight_memories>[\s\S]*?<\/hindsigh
 const LEGACY_RELEVANT_MEMORIES_REGEX = /<relevant_memories>[\s\S]*?<\/relevant_memories>/g;
 const MENTAL_MODELS_REGEX = /<mental_models>[\s\S]*?<\/mental_models>/g;
 
+const RETENTION_PROTOCOL_MARKER_REGEX = /^\[(?:role:\s*[-_a-zA-Z0-9]+|[-_a-zA-Z0-9]+:end)\]$/;
 /**
  * Strip `<memories>`, `<mental_models>`, and legacy memory blocks.
  *
@@ -205,6 +206,32 @@ function formatRetentionMessages(messages: HindsightMessage[]): RetentionTranscr
 	return { transcript, messageCount: parts.length };
 }
 
+function formatEmbeddableRetentionMessages(messages: HindsightMessage[]): RetentionTranscript {
+	const parts: string[] = [];
+	for (const msg of messages) {
+		const content = stripRetentionProtocolMarkers(stripMemoryTags(msg.content)).trim();
+		if (!hasSubstantiveContent(content)) continue;
+		parts.push(content);
+	}
+
+	if (parts.length === 0) return { transcript: null, messageCount: 0 };
+
+	const transcript = parts.join("\n\n");
+	if (transcript.trim().length < 10) return { transcript: null, messageCount: 0 };
+
+	return { transcript, messageCount: parts.length };
+}
+
+/** Remove retention framing lines from a stored coding-agent episode transcript. */
+export function stripRetentionProtocolMarkers(content: string): string {
+	return content
+		.split(/\r?\n/)
+		.filter(line => !RETENTION_PROTOCOL_MARKER_REGEX.test(line.trim()))
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
 export function prepareRetentionTranscript(
 	messages: HindsightMessage[],
 	retainFullWindow = false,
@@ -229,6 +256,10 @@ export function prepareRetentionTranscript(
 	return formatRetentionMessages(targetMessages);
 }
 
+/** Format all retention messages without protocol markers for embedding, FTS, and recall display. */
+export function prepareEmbeddableRetentionTranscript(messages: HindsightMessage[]): RetentionTranscript {
+	return formatEmbeddableRetentionMessages(messages);
+}
 /** Format only user-authored messages for memory fact/entity extraction. */
 export function prepareUserRetentionTranscript(messages: HindsightMessage[]): RetentionTranscript {
 	return formatRetentionMessages(messages.filter(message => message.role === "user"));

package/src/internal-urls/artifact-protocol.ts

@@ -15,75 +15,119 @@ import { isEnoent } from "@oh-my-pi/pi-utils";
 import { artifactsDirsFromRegistry } from "./registry-helpers";
 import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
 
-export class ArtifactProtocolHandler implements ProtocolHandler {
-	readonly scheme = "artifact";
-	readonly immutable = true;
+const MAX_INLINE_ARTIFACT_BYTES = 8 * 1024 * 1024;
 
-	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
-		const id = url.rawHost || url.hostname;
-		if (!id) {
-			throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+/** Filesystem location for a session artifact, resolved without materializing its content. */
+export interface ResolvedArtifactFile {
+	id: string;
+	path: string;
+	size: number;
+}
+
+function parseArtifactId(url: InternalUrl): string {
+	const id = url.rawHost || url.hostname;
+	if (!id) {
+		throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+	}
+	if (!/^\d+$/.test(id)) {
+		throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+	}
+	return id;
+}
+
+/** Resolve an `artifact://` URL to its backing file without reading artifact bytes. */
+export async function resolveArtifactFile(url: InternalUrl, context?: ResolveContext): Promise<ResolvedArtifactFile> {
+	const id = parseArtifactId(url);
+
+	// Artifact ids are per-session counters; in multi-session hosts the same
+	// id exists in several dirs. Pin resolution to the calling session's
+	// artifacts dir first so `artifact://3` means *this* session's #3.
+	const dirs = artifactsDirsFromRegistry();
+	const pinnedDir = context?.localProtocolOptions?.getArtifactsDir?.() ?? null;
+	if (pinnedDir) {
+		const pinnedIndex = dirs.indexOf(pinnedDir);
+		if (pinnedIndex >= 0) dirs.splice(pinnedIndex, 1);
+		dirs.unshift(pinnedDir);
+	}
+
+	if (dirs.length === 0) {
+		throw new Error("No session - artifacts unavailable");
+	}
+
+	let foundPath: string | undefined;
+	let anyDirExists = false;
+	const availableIds = new Set<string>();
+
+	for (const dir of dirs) {
+		let files: string[];
+		try {
+			files = await fs.readdir(dir);
+			anyDirExists = true;
+		} catch (err) {
+			if (isEnoent(err)) continue;
+			throw err;
 		}
-		if (!/^\d+$/.test(id)) {
-			throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+		const match = files.find(f => f.startsWith(`${id}.`));
+		if (match) {
+			foundPath = path.join(dir, match);
+			break;
 		}
-
-		// Artifact ids are per-session counters; in multi-session hosts the same
-		// id exists in several dirs. Pin resolution to the calling session's
-		// artifacts dir first so `artifact://3` means *this* session's #3.
-		const dirs = artifactsDirsFromRegistry();
-		const pinnedDir = context?.localProtocolOptions?.getArtifactsDir?.() ?? null;
-		if (pinnedDir) {
-			const pinnedIndex = dirs.indexOf(pinnedDir);
-			if (pinnedIndex >= 0) dirs.splice(pinnedIndex, 1);
-			dirs.unshift(pinnedDir);
+		for (const f of files) {
+			const m = f.match(/^(\d+)\./);
+			if (m) availableIds.add(m[1]);
 		}
+	}
 
-		if (dirs.length === 0) {
-			throw new Error("No session - artifacts unavailable");
-		}
+	if (!anyDirExists) {
+		throw new Error("No artifacts directory found");
+	}
 
-		let foundPath: string | undefined;
-		let anyDirExists = false;
-		const availableIds = new Set<string>();
+	if (!foundPath) {
+		const sorted = [...availableIds].sort((a, b) => Number(a) - Number(b));
+		const availableStr = sorted.length > 0 ? sorted.join(", ") : "none";
+		throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+	}
 
-		for (const dir of dirs) {
-			let files: string[];
-			try {
-				files = await fs.readdir(dir);
-				anyDirExists = true;
-			} catch (err) {
-				if (isEnoent(err)) continue;
-				throw err;
-			}
-			const match = files.find(f => f.startsWith(`${id}.`));
-			if (match) {
-				foundPath = path.join(dir, match);
-				break;
-			}
-			for (const f of files) {
-				const m = f.match(/^(\d+)\./);
-				if (m) availableIds.add(m[1]);
-			}
-		}
+	const stat = await Bun.file(foundPath).stat();
+	if (stat.isDirectory()) {
+		throw new Error(`Artifact ${id} resolved to a directory, not a file`);
+	}
+	return { id, path: foundPath, size: stat.size };
+}
+
+export class ArtifactProtocolHandler implements ProtocolHandler {
+	readonly scheme = "artifact";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const artifact = await resolveArtifactFile(url, context);
 
-		if (!anyDirExists) {
-			throw new Error("No artifacts directory found");
+		// Path-only callers (search/grep, bash URL expansion) never touch the
+		// artifact bytes. Return the resource shape so those flows keep working
+		// on artifacts of any size — only content materialization is gated.
+		if (context?.pathOnly) {
+			return {
+				url: url.href,
+				content: "",
+				contentType: "text/plain",
+				size: artifact.size,
+				sourcePath: artifact.path,
+			};
 		}
 
-		if (!foundPath) {
-			const sorted = [...availableIds].sort((a, b) => Number(a) - Number(b));
-			const availableStr = sorted.length > 0 ? sorted.join(", ") : "none";
-			throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+		if (artifact.size > MAX_INLINE_ARTIFACT_BYTES) {
+			throw new Error(
+				`Artifact ${artifact.id} is ${artifact.size} bytes; full internal resolution is blocked. Use read selectors such as artifact://${artifact.id}:1-3000 or artifact://${artifact.id}:raw:1-3000, and use the artifact file path for search/copy workflows: ${artifact.path}`,
+			);
 		}
 
-		const content = await Bun.file(foundPath).text();
+		const content = await Bun.file(artifact.path).text();
 		return {
 			url: url.href,
 			content,
 			contentType: "text/plain",
-			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: foundPath,
+			size: artifact.size,
+			sourcePath: artifact.path,
 		};
 	}