@roj-ai/sdk 0.1.36 → 0.2.1

package/src/core/events/file.ts

@@ -1,8 +1,9 @@
 import { dirname, join } from 'node:path'
 import z from 'zod/v4'
 import type { DomainEvent } from '~/core/events/types.js'
-import type { FileSystem } from '~/platform/fs.js'
-import { domainEventSchema, SessionId, sessionMetadataSchema } from '~/core/sessions/schema.js'
+import { silentLogger, type Logger } from '~/lib/logger/logger.js'
+import type { Dirent, FileSystem } from '~/platform/fs.js'
+import { domainEventSchema, isValidSessionId, SessionId, sessionMetadataSchema } from '~/core/sessions/schema.js'
 import type { SessionMetadata } from '~/core/sessions/schema.js'
 import { BaseEventStore } from './base-event-store.js'
 import type { LoadRangeOptions, LoadRangeResult } from './event-store.js'
@@ -99,6 +100,40 @@ async function readLastLines(fs: FileSystem, filePath: string, lineCount: number
 	}
 }
 
+/** Identity of the meta.json bytes a cached verdict was taken from. */
+interface MetadataSource {
+	mtimeMs: number
+	size: number
+}
+
+/** A parsed record, or the verdict that the bytes it was read from do not parse. */
+type MetadataCacheEntry =
+	| { kind: 'record'; record: SessionMetadata }
+	| { kind: 'invalid'; source: MetadataSource }
+
+function isSameSource(a: MetadataSource, b: MetadataSource): boolean {
+	return a.mtimeMs === b.mtimeMs && a.size === b.size
+}
+
+function errorCode(error: unknown): string | undefined {
+	return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined
+}
+
+function isNotFound(error: unknown): boolean {
+	return errorCode(error) === 'ENOENT'
+}
+
+/** Before the cache every read parsed fresh JSON — keep that, so a mutating caller cannot corrupt it. */
+function copyMetadata(metadata: SessionMetadata | null): SessionMetadata | null {
+	if (!metadata) return null
+
+	const copy: SessionMetadata = { ...metadata }
+	if (metadata.metrics) copy.metrics = { ...metadata.metrics }
+	if (metadata.tags) copy.tags = [...metadata.tags]
+	if (metadata.custom) copy.custom = { ...metadata.custom }
+	return copy
+}
+
 /**
  * FileEventStore - Persists domain events to JSONL files.
  *
@@ -121,7 +156,28 @@ async function readLastLines(fs: FileSystem, filePath: string, lineCount: number
 export class FileEventStore extends BaseEventStore {
 	private readonly sessionLocks = new Map<SessionId, AsyncMutex>()
 
-	constructor(private readonly basePath: string, private readonly fs: FileSystem) {
+	/**
+	 * Parsed meta.json per session, so a `/status` poll costs one readdir instead of
+	 * one readFile per session directory that ever existed. An `invalid` entry records
+	 * bytes that exist but do not parse, so a corrupt record is reported once rather
+	 * than once per poll, and is re-read as soon as those bytes change.
+	 *
+	 * Coherence rule: writes win. writeMetadata is the only writer, and a read stores
+	 * its result only if the entry did not move while the read was in flight — a read
+	 * is a snapshot of older bytes, so it must never overwrite a newer write. A full
+	 * listing prunes the map to the readdir set, which keeps deletion and out-of-band
+	 * creation self-healing.
+	 */
+	private readonly metadataCache = new Map<SessionId, MetadataCacheEntry>()
+
+	/** Last reported read failure per session, so a permanent EACCES is not logged on every poll. */
+	private readonly reportedReadFailures = new Map<SessionId, string>()
+
+	constructor(
+		private readonly basePath: string,
+		private readonly fs: FileSystem,
+		private readonly logger: Logger = silentLogger,
+	) {
 		super()
 	}
 
@@ -242,11 +298,12 @@ export class FileEventStore extends BaseEventStore {
 
 		try {
 			const entries = await this.fs.readdir(sessionsDir, { withFileTypes: true })
+			// A directory whose name is not a valid id is not a session — the metadata listing drops it too.
 			return entries
-				.filter((entry) => entry.isDirectory())
-				.map((entry) => entry.name as SessionId)
+				.filter((entry) => entry.isDirectory() && isValidSessionId(entry.name))
+				.map((entry) => SessionId(entry.name))
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+			if (isNotFound(error)) {
 				return []
 			}
 			throw error
@@ -326,47 +383,166 @@ export class FileEventStore extends BaseEventStore {
 	// =========================================================================
 
 	protected async readMetadata(sessionId: SessionId): Promise<SessionMetadata | null> {
+		const cached = this.metadataCache.get(sessionId)
+		if (cached?.kind === 'record') return copyMetadata(cached.record)
+
 		const path = this.getMetaPath(sessionId)
 
 		try {
+			// Stat before the read, so a verdict is never keyed to bytes newer than the ones it judged.
+			const source = await this.readMetadataSource(path)
+			// A rejected record stays rejected only for the bytes that were rejected, so a repair is picked up.
+			if (cached && isSameSource(cached.source, source)) return null
+
 			const content = await this.fs.readFile(path, 'utf-8')
-			const parsed = JSON.parse(content)
-			const validated = sessionMetadataSchema.parse(parsed)
-			return validated as SessionMetadata
+			const record = this.parseMetadata(sessionId, content)
+			this.reportedReadFailures.delete(sessionId)
+
+			return copyMetadata(
+				this.commitRead(sessionId, cached, record ? { kind: 'record', record } : { kind: 'invalid', source }),
+			)
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+			if (isNotFound(error)) {
+				// A missing file is never cached — unknown ids must not be able to grow the map.
 				return null
 			}
+			this.reportReadFailure(sessionId, error)
 			throw error
 		}
 	}
 
+	/**
+	 * Cache what the read found, unless a write landed while it was in flight.
+	 *
+	 * A read only ever sees the bytes it started from, so the concurrent writer holds the
+	 * newer record and the reader reports that one instead of overwriting it with its own.
+	 */
+	private commitRead(
+		sessionId: SessionId,
+		before: MetadataCacheEntry | undefined,
+		entry: MetadataCacheEntry,
+	): SessionMetadata | null {
+		const current = this.metadataCache.get(sessionId)
+		if (current !== before) return current?.kind === 'record' ? current.record : null
+
+		this.metadataCache.set(sessionId, entry)
+		return entry.kind === 'record' ? entry.record : null
+	}
+
+	private async readMetadataSource(path: string): Promise<MetadataSource> {
+		const stats = await this.fs.stat(path)
+		return { mtimeMs: stats.mtimeMs, size: stats.size }
+	}
+
+	/** Reports a read that failed for anything but a missing file, once per failure kind. */
+	private reportReadFailure(sessionId: SessionId, error: unknown): void {
+		const code = errorCode(error) ?? 'unknown'
+		if (this.reportedReadFailures.get(sessionId) === code) return
+
+		this.reportedReadFailures.set(sessionId, code)
+		this.logger.error(
+			'Failed to read session metadata',
+			error instanceof Error ? error : new Error(String(error)),
+			{ sessionId },
+		)
+	}
+
+	/**
+	 * Strict on write, tolerant on read.
+	 *
+	 * meta.json is written non-atomically and its schema tightened over time, so a
+	 * single truncated or legacy record must not take the whole listing down with it.
+	 */
+	private parseMetadata(sessionId: SessionId, content: string): SessionMetadata | null {
+		let raw: unknown
+		try {
+			raw = JSON.parse(content)
+		} catch (error) {
+			this.logger.warn('Skipping unreadable session metadata', { sessionId, reason: String(error) })
+			return null
+		}
+
+		const parsed = sessionMetadataSchema.safeParse(raw)
+		if (!parsed.success) {
+			this.logger.warn('Skipping invalid session metadata', { sessionId, reason: parsed.error.message })
+			return null
+		}
+
+		return parsed.data
+	}
+
 	protected async writeMetadata(sessionId: SessionId, metadata: SessionMetadata): Promise<void> {
 		const path = this.getMetaPath(sessionId)
 		await this.fs.mkdir(dirname(path), { recursive: true })
 		await this.fs.writeFile(path, JSON.stringify(metadata, null, 2))
+
+		// The cache may only hold what a read would return, so the record goes in through the same schema.
+		const parsed = sessionMetadataSchema.safeParse(metadata)
+		if (!parsed.success) {
+			this.logger.warn('Not caching invalid session metadata', { sessionId, reason: parsed.error.message })
+			this.metadataCache.delete(sessionId)
+			return
+		}
+
+		// Cached only once the write lands, so a failed write leaves no phantom value.
+		this.metadataCache.set(sessionId, { kind: 'record', record: parsed.data })
+		this.reportedReadFailures.delete(sessionId)
 	}
 
 	protected async getAllSessionMetadata(): Promise<SessionMetadata[]> {
 		const sessionsDir = join(this.basePath, 'sessions')
 
+		let entries: Dirent[]
 		try {
-			const entries = await this.fs.readdir(sessionsDir, { withFileTypes: true })
-			const sessions: SessionMetadata[] = []
-
-			for (const entry of entries) {
-				if (!entry.isDirectory()) continue
-
-				const metadata = await this.readMetadata(entry.name as SessionId)
-				if (metadata) sessions.push(metadata)
-			}
-
-			return sessions
+			entries = await this.fs.readdir(sessionsDir, { withFileTypes: true })
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+			if (isNotFound(error)) {
+				// The data root is gone, so every session cached from it is gone with it.
+				this.forgetAll()
 				return []
 			}
 			throw error
 		}
+
+		const sessions: SessionMetadata[] = []
+		const present = new Set<SessionId>()
+
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue
+
+			const sessionId = SessionId(entry.name)
+			present.add(sessionId)
+
+			const metadata = await this.readMetadataOrSkip(sessionId)
+			if (metadata) sessions.push(metadata)
+		}
+
+		// The directory listing is the only thing that can remove a session, so prune here.
+		this.forgetMissing(present)
+
+		return sessions
+	}
+
+	/** One unreadable session must not take the listing down for every other one. */
+	private async readMetadataOrSkip(sessionId: SessionId): Promise<SessionMetadata | null> {
+		try {
+			return await this.readMetadata(sessionId)
+		} catch {
+			return null // already reported by readMetadata
+		}
+	}
+
+	private forgetMissing(present: Set<SessionId>): void {
+		for (const sessionId of this.metadataCache.keys()) {
+			if (!present.has(sessionId)) this.metadataCache.delete(sessionId)
+		}
+		for (const sessionId of this.reportedReadFailures.keys()) {
+			if (!present.has(sessionId)) this.reportedReadFailures.delete(sessionId)
+		}
+	}
+
+	private forgetAll(): void {
+		this.metadataCache.clear()
+		this.reportedReadFailures.clear()
 	}
 }

package/src/core/file-store/containment.ts

@@ -0,0 +1,75 @@
+/**
+ * Containment check for paths that are about to be handed to the filesystem.
+ *
+ * A lexical check (`resolve()` then a prefix compare) only sees the path string,
+ * so a link inside a root can still point anywhere the process can reach. Both
+ * ends are canonicalized here instead. Links are not banned — one whose target
+ * lands back inside a root stays usable.
+ */
+
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
+import type { FileSystem } from '~/platform/fs.js'
+
+/**
+ * Where a path's real target sits.
+ *
+ * `unresolvable` is a path that exists but cannot be canonicalized — a link with
+ * no target, a link loop. Only an operation that would create through it has to
+ * refuse; the ones that merely follow it fail on their own.
+ */
+export type Containment = 'inside' | 'outside' | 'unresolvable'
+
+export async function containmentOf(
+	fs: FileSystem,
+	roots: readonly string[],
+	path: string,
+): Promise<Containment> {
+	// A path that is one of its own roots is inside it whatever it resolves to.
+	if (roots.includes(path)) return 'inside'
+
+	const target = await canonicalize(fs, path)
+	if (target === null) return 'unresolvable'
+
+	for (const root of roots) {
+		const canonicalRoot = await canonicalize(fs, root)
+		if (canonicalRoot !== null && isUnder(canonicalRoot, target)) return 'inside'
+	}
+	return 'outside'
+}
+
+function isUnder(root: string, target: string): boolean {
+	const rel = relative(root, target)
+	return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`))
+}
+
+/**
+ * Canonical form of `path`, resolving through its deepest existing ancestor so
+ * a not-yet-created file is judged by the directory it would land in.
+ * Null when a component exists but cannot be resolved.
+ */
+async function canonicalize(fs: FileSystem, path: string): Promise<string | null> {
+	const missing: string[] = []
+	let current = path
+	for (;;) {
+		try {
+			const real = await fs.realpath(current)
+			return missing.length > 0 ? join(real, ...missing) : real
+		} catch {
+			if (await entryExists(fs, current)) return null
+			const parent = dirname(current)
+			if (parent === current) return null
+			missing.unshift(basename(current))
+			current = parent
+		}
+	}
+}
+
+/** Anything `lstat` rejects counts as absent, an unreadable parent included — the caller's own operation then reports it. */
+async function entryExists(fs: FileSystem, path: string): Promise<boolean> {
+	try {
+		await fs.lstat(path)
+		return true
+	} catch {
+		return false
+	}
+}

package/src/core/file-store/file-store.ts

@@ -5,6 +5,11 @@
  * validation, agent-visible path mapping). Replaces the separate path-resolver
  * functions for FileStore consumers.
  *
+ * Every operation resolves the path lexically and then checks that its real
+ * target is still inside the area the store may touch — session and workspace
+ * together, or whatever root a `scoped()` sub-store was carved out of. Links
+ * are not banned: one whose target lands back inside stays usable.
+ *
  * Three scopes:
  * - 'full': accepts agent-visible paths (/home/user/session/... or real paths)
  * - 'session': paths relative to sessionDir
@@ -12,8 +17,9 @@
  */
 
 import { dirname, join, normalize, resolve } from 'node:path'
+import { containmentOf } from '~/core/file-store/containment.js'
 import type { FileEntry, FileStore } from '~/core/file-store/types.js'
-import type { FileSystem } from '~/platform/fs.js'
+import type { FileSystem, WalkEntry } from '~/platform/fs.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { Result } from '~/lib/utils/result.js'
 
@@ -23,6 +29,19 @@ const VIRTUAL_WORKSPACE = '/home/user/workspace'
 
 type FileStoreScope = 'full' | 'session' | 'workspace'
 
+/** A lexically resolved path plus the roots its real target must stay inside. */
+interface ResolvedPath {
+	absolute: string
+	roots: readonly string[]
+}
+
+/**
+ * What the operation does with the final link, which decides what an
+ * unresolvable one means: `follow` leaves it to the operation, `create` refuses
+ * it because writing would create the target, `entry` checks the parent instead.
+ */
+type ContainmentMode = 'follow' | 'create' | 'entry'
+
 export class SessionFileStore implements FileStore {
 	constructor(
 		private readonly sessionDir: string,
@@ -30,25 +49,31 @@ export class SessionFileStore implements FileStore {
 		private readonly sandboxed: boolean,
 		private readonly fs: FileSystem,
 		private readonly scope: FileStoreScope = 'full',
+		/** Set by `scoped()` so a sub-store cannot escape the roots it was carved out of. */
+		private readonly containmentRoots?: readonly string[],
 	) {}
 
 	/** Create a session-scoped FileStore (relative paths → sessionDir) */
 	get session(): SessionFileStore {
-		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'session')
+		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'session', this.containmentRoots)
 	}
 
 	/** Create a workspace-scoped FileStore (relative paths → workspaceDir), or undefined if no workspace */
 	get workspace(): SessionFileStore | undefined {
 		if (!this.workspaceDir) return undefined
-		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'workspace')
+		return new SessionFileStore(this.sessionDir, this.workspaceDir, this.sandboxed, this.fs, 'workspace', this.containmentRoots)
 	}
 
 	async write(path: string, content: string | Buffer): Promise<Result<{ path: string }, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'create')
 		if (!resolved.ok) return resolved
 
-		await this.fs.mkdir(dirname(resolved.value), { recursive: true })
-		await this.fs.writeFile(resolved.value, content)
+		try {
+			await this.fs.mkdir(dirname(resolved.value), { recursive: true })
+			await this.fs.writeFile(resolved.value, content)
+		} catch {
+			return Err(`Failed to write: ${path}`)
+		}
 
 		return Ok({ path: this.toAgentPath(resolved.value) })
 	}
@@ -56,7 +81,7 @@ export class SessionFileStore implements FileStore {
 	async read(path: string): Promise<Result<string, string>>
 	async read(path: string, opts: { type: 'buffer' }): Promise<Result<Buffer, string>>
 	async read(path: string, opts?: { type: 'buffer' }): Promise<Result<string | Buffer, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		try {
@@ -70,21 +95,22 @@ export class SessionFileStore implements FileStore {
 	}
 
 	async exists(path: string): Promise<Result<boolean, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		return Ok(await this.fs.exists(resolved.value))
 	}
 
 	async stat(path: string): Promise<Result<FileEntry, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		try {
+			// `stat` follows links on purpose — a link to a file inside the root is a file here.
 			const s = await this.fs.stat(resolved.value)
 			return Ok({
 				size: s.size,
-				type: s.isFile() ? 'file' : s.isDirectory() ? 'directory' : s.isSymbolicLink() ? 'symlink' : 'other',
+				type: s.isFile() ? 'file' : s.isDirectory() ? 'directory' : 'other',
 				name: resolved.value.split('/').pop() || '',
 			})
 		} catch {
@@ -96,15 +122,24 @@ export class SessionFileStore implements FileStore {
 		path: string,
 		options?: { maxDepth?: number; gitIgnore?: boolean },
 	): Promise<Result<FileEntry[], string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'follow')
 		if (!resolved.ok) return resolved
 
 		const maxDepth = options?.maxDepth ?? 1
 		if (maxDepth < 1) return Ok([])
 
 		try {
+			// A readdir plus a stat per file is one question asked in pieces. Where
+			// the platform takes it whole, ask it whole.
+			if (this.fs.walk) {
+				const base = resolved.value
+				const found = await this.fs.walk(base, { depth: maxDepth })
+				return Ok(found.map((entry) => toFileEntry(entry, base)))
+			}
+
 			const entries: FileEntry[] = []
-			await this.walkInto(resolved.value, '', maxDepth, entries)
+			const readAll = (): Promise<void> => this.walkInto(resolved.value, '', maxDepth, entries)
+			await (this.fs.scopeReads ? this.fs.scopeReads(readAll) : readAll())
 			return Ok(entries)
 		} catch {
 			return Err(`Directory not found: ${path}`)
@@ -142,7 +177,7 @@ export class SessionFileStore implements FileStore {
 	}
 
 	async remove(path: string): Promise<Result<void, string>> {
-		const resolved = this.resolvePath(path)
+		const resolved = await this.resolveContained(path, 'entry')
 		if (!resolved.ok) return resolved
 
 		try {
@@ -166,24 +201,60 @@ export class SessionFileStore implements FileStore {
 		}
 	}
 
+	/** Lexical resolution only — despite the name it never follows a symlink. See FileStore.realPath. */
 	realPath(path: string): Result<string, string> {
-		return this.resolvePath(path)
+		const resolved = this.resolveScoped(path)
+		return resolved.ok ? Ok(resolved.value.absolute) : resolved
 	}
 
+	/** See FileStore.containedPath. */
+	containedPath(path: string): Promise<Result<string, string>> {
+		return this.resolveContained(path, 'create')
+	}
+
+	/** Throws on a path it cannot resolve — never hand it unvalidated request data; use `realPath` there. */
 	scoped(basePath: string): SessionFileStore {
 		// Resolve basePath relative to current scope
-		const resolved = this.resolvePath(basePath)
+		const resolved = this.resolveScoped(basePath)
 		if (!resolved.ok) {
 			throw new Error(`Cannot scope to invalid path: ${basePath}`)
 		}
-		return new SessionFileStore(resolved.value, undefined, false, this.fs, 'session')
+		return new SessionFileStore(resolved.value.absolute, undefined, false, this.fs, 'session', resolved.value.roots)
 	}
 
 	// ============================================================================
 	// Path resolution
 	// ============================================================================
 
-	private resolvePath(path: string): Result<string, string> {
+	/**
+	 * Lexical resolution, plus a check that the real target has not left the roots.
+	 * `mode` says what the operation does with the final link — see ContainmentMode.
+	 */
+	private async resolveContained(path: string, mode: ContainmentMode): Promise<Result<string, string>> {
+		const resolved = this.resolveScoped(path)
+		if (!resolved.ok) return resolved
+
+		const { absolute, roots } = resolved.value
+		const subject = mode === 'entry' ? dirname(absolute) : absolute
+		switch (await containmentOf(this.fs, roots, subject)) {
+			case 'outside':
+				return Err(`Path '${path}' resolves outside allowed directories`)
+			case 'unresolvable':
+				return mode === 'create' ? Err(`Path '${path}' cannot be resolved`) : Ok(absolute)
+			case 'inside':
+				return Ok(absolute)
+		}
+	}
+
+	/** The area this store may touch — both roots where a workspace is configured. */
+	private allowedRoots(): readonly string[] {
+		if (this.containmentRoots) return this.containmentRoots
+		const roots = [resolve(this.sessionDir)]
+		if (this.workspaceDir) roots.push(resolve(this.workspaceDir))
+		return roots
+	}
+
+	private resolveScoped(path: string): Result<ResolvedPath, string> {
 		switch (this.scope) {
 			case 'full':
 				return this.resolveAgentPath(path)
@@ -196,7 +267,7 @@ export class SessionFileStore implements FileStore {
 	}
 
 	/** Resolve a relative path within a root directory */
-	private resolveRelativePath(path: string, rootDir: string): Result<string, string> {
+	private resolveRelativePath(path: string, rootDir: string): Result<ResolvedPath, string> {
 		const normalized = normalize(path)
 		if (normalized.startsWith('..') || normalized.startsWith('/')) {
 			return Err(`Path traversal not allowed: ${path}`)
@@ -205,18 +276,18 @@ export class SessionFileStore implements FileStore {
 		if (!absolute.startsWith(rootDir)) {
 			return Err(`Path traversal not allowed: ${path}`)
 		}
-		return Ok(absolute)
+		return Ok({ absolute, roots: this.allowedRoots() })
 	}
 
 	/** Resolve an agent-visible path to real filesystem path (handles sandboxed virtual paths) */
-	private resolveAgentPath(agentPath: string): Result<string, string> {
+	private resolveAgentPath(agentPath: string): Result<ResolvedPath, string> {
 		if (this.sandboxed) {
 			return this.resolveSandboxedPath(agentPath)
 		}
 		return this.resolveNonSandboxedPath(agentPath)
 	}
 
-	private resolveSandboxedPath(agentPath: string): Result<string, string> {
+	private resolveSandboxedPath(agentPath: string): Result<ResolvedPath, string> {
 		if (agentPath.startsWith(VIRTUAL_SESSION + '/') || agentPath === VIRTUAL_SESSION) {
 			const relative = agentPath.slice(VIRTUAL_SESSION.length)
 			const absolutePath = resolve(this.sessionDir, relative.slice(1) || '.')
@@ -239,7 +310,7 @@ export class SessionFileStore implements FileStore {
 		return Err(`Path must start with ${validPrefixes}. Got: '${agentPath}'`)
 	}
 
-	private resolveNonSandboxedPath(agentPath: string): Result<string, string> {
+	private resolveNonSandboxedPath(agentPath: string): Result<ResolvedPath, string> {
 		const absolutePath = resolve(agentPath)
 		const normalizedSession = resolve(this.sessionDir)
 		const normalizedWorkspace = this.workspaceDir ? resolve(this.workspaceDir) : null
@@ -252,10 +323,10 @@ export class SessionFileStore implements FileStore {
 			return Err(`Path '${agentPath}' is outside allowed directories`)
 		}
 
-		return Ok(absolutePath)
+		return Ok({ absolute: absolutePath, roots: this.allowedRoots() })
 	}
 
-	private validateWithinRoot(absolutePath: string, rootDir: string, originalPath: string): Result<string, string> {
+	private validateWithinRoot(absolutePath: string, rootDir: string, originalPath: string): Result<ResolvedPath, string> {
 		const normalizedRoot = resolve(rootDir)
 		const isWithin = absolutePath === normalizedRoot || absolutePath.startsWith(normalizedRoot + '/')
 
@@ -263,7 +334,7 @@ export class SessionFileStore implements FileStore {
 			return Err(`Path '${originalPath}' resolves outside allowed directories`)
 		}
 
-		return Ok(absolutePath)
+		return Ok({ absolute: absolutePath, roots: this.allowedRoots() })
 	}
 
 	// ============================================================================
@@ -293,3 +364,13 @@ export class SessionFileStore implements FileStore {
 		return realPath
 	}
 }
+
+/** A walked entry as the store reports it: name relative to the listed directory. */
+function toFileEntry(entry: WalkEntry, baseDir: string): FileEntry {
+	const prefixLength = baseDir.endsWith('/') ? baseDir.length : baseDir.length + 1
+	return {
+		name: entry.path.slice(prefixLength),
+		type: entry.type,
+		size: entry.type === 'file' ? entry.size : undefined,
+	}
+}

package/src/core/file-store/types.ts

@@ -39,9 +39,22 @@ export interface FileStore {
 	/** Remove a file. */
 	remove(path: string): Promise<Result<void, string>>
 
-	/** Resolve an agent-visible path to real filesystem path. */
+	/**
+	 * Resolve an agent-visible path to a real filesystem path, lexically.
+	 *
+	 * Does not follow symlinks, so it cannot decide containment on its own. Use
+	 * it only where the path is never handed to the filesystem — everything that
+	 * goes on to read, write or spawn wants `containedPath` instead.
+	 */
 	realPath(path: string): Result<string, string>
 
+	/**
+	 * Resolve to a real filesystem path, refusing one whose real target leaves
+	 * the store's roots. What a caller that reaches the filesystem itself, rather
+	 * than through this store, should ask for.
+	 */
+	containedPath(path: string): Promise<Result<string, string>>
+
 	/** Get the agent-visible root paths (virtual when sandboxed, real otherwise) */
 	getRoots(): { session: string; workspace?: string }
 

package/src/core/image/image-processor.ts

@@ -80,7 +80,9 @@ export class DefaultImageProcessor implements ImageProcessor {
 			return { type: 'text', text: `[Image unavailable: ${path} - unsupported format]` }
 		}
 
-		const resolved = fileStore.realPath(path)
+		// Not `realPath`: the URL comes back from conversation history, and what it
+		// names may have become a link out of the store since it was first read.
+		const resolved = await fileStore.containedPath(path)
 		if (!resolved.ok) {
 			return { type: 'text', text: `[Image unavailable: ${path} - ${resolved.error}]` }
 		}