@wjm200509/dsh-memory 0.0.0-stage → 0.1.0

package/lib/state.js

@@ -0,0 +1,242 @@
+/**
+ * Durable dreaming state under `<memory root>/.state/`:
+ *   state.json  — pending queue, per-session watermarks, pause flag,
+ *                 cross-project bookkeeping
+ *   log.jsonl   — run log, last 200 entries
+ *
+ * A session leaves the queue only through `complete()` after a successful
+ * run, so a host shutdown mid-run keeps the batch queued. Writes are chained
+ * so concurrent callers never interleave a read-modify-write.
+ */
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { renameWithRetry } from "./fsutil.js";
+
+const LOG_LIMIT = 200;
+
+/**
+ * @typedef {{ sessionId: string, cwd: string, endedAt: number, seq: number }} Job
+ * @typedef {{ at: number, cwd?: string, scope?: "cross", sessionIds: string[], ok: boolean, trigger: "auto" | "manual",
+ *   changes?: { created: number, modified: number, deleted: number, paths?: object }, issues?: string[], summary?: string,
+ *   error?: string, dreamSessionId?: string }} LogEntry
+ *   A cross-project run has `scope: "cross"` and no `cwd`; `issues` lists what an ok run left unresolved.
+ */
+
+async function readIfExists(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function writeAtomic(file, content) {
+	const temp = `${file}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temp, content, "utf8");
+		await renameWithRetry(temp, file);
+	} catch (error) {
+		await rm(temp, { force: true }).catch(() => {});
+		throw error;
+	}
+}
+
+export class DreamState {
+	/**
+	 * @param {string} root - memory root.
+	 * @param {{ now?: () => number }} [options]
+	 */
+	constructor(root, { now = Date.now } = {}) {
+		this.now = now;
+		this.dir = join(root, ".state");
+		this.stateFile = join(this.dir, "state.json");
+		this.logFile = join(this.dir, "log.jsonl");
+		/** @type {{ queue: Job[], watermarks: Record<string, number>, paused: { since: number, reason: string } | null, cross?: { at?: number, projects: string[] } }} */
+		this.data = { queue: [], watermarks: {}, paused: null };
+		/** @type {LogEntry[]} */
+		this.log = [];
+		/** True when `load()` found an unreadable state.json and started fresh. */
+		this.recovered = false;
+		this.chain = Promise.resolve();
+	}
+
+	/** Read persisted state; a missing directory means a fresh install. */
+	async load() {
+		const raw = await readIfExists(this.stateFile);
+		if (raw !== null) {
+			try {
+				const parsed = JSON.parse(raw);
+				if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("state.json is not an object");
+				const data = { queue: [], watermarks: {}, paused: null, ...parsed };
+				if (!Array.isArray(data.queue) || typeof data.watermarks !== "object" || data.watermarks === null) throw new Error("state.json has a bad shape");
+				this.data = data;
+			} catch {
+				/* A corrupt state file must not stop the plugin: keep it aside for inspection and start fresh. */
+				await rename(this.stateFile, `${this.stateFile}.corrupt-${this.now()}`).catch(() => {});
+				this.recovered = true;
+			}
+		}
+		/* First load marks the install time: sessions created earlier are never backfilled. */
+		if (typeof this.data.installedAt !== "number") {
+			const installedAt = this.now();
+			await this.persist(() => {
+				this.data.installedAt = installedAt;
+			});
+		}
+		const log = await readIfExists(this.logFile);
+		/* An append torn by a crash leaves a partial last line; skip unparsable lines rather than refuse to load. */
+		this.log = log === null ? [] : log.split("\n").flatMap((line) => {
+			try {
+				return line.trim() === "" ? [] : [JSON.parse(line)];
+			} catch {
+				return [];
+			}
+		}).slice(-LOG_LIMIT);
+	}
+
+	/** Run one mutation after every earlier one, then persist. */
+	persist(mutate) {
+		const next = this.chain.then(async () => {
+			mutate();
+			await mkdir(this.dir, { recursive: true });
+			await writeAtomic(this.stateFile, JSON.stringify(this.data));
+		});
+		this.chain = next.catch(() => {});
+		return next;
+	}
+
+	/** Queue one ended session; a re-queued session keeps only its latest position. */
+	enqueue(job) {
+		return this.persist(() => {
+			this.data.queue = this.data.queue.filter((queued) => queued.sessionId !== job.sessionId);
+			this.data.queue.push({ sessionId: job.sessionId, cwd: job.cwd, endedAt: job.endedAt, seq: job.seq });
+		});
+	}
+
+	/** @returns {Job[]} queued sessions, oldest ending first, optionally for one project. */
+	pending(cwd) {
+		return this.data.queue.filter((job) => cwd === undefined || job.cwd === cwd).sort((a, b) => a.endedAt - b.endedAt).map((job) => ({ ...job }));
+	}
+
+	/**
+	 * Advance watermarks to the seqs a run actually covered, and dequeue those
+	 * sessions unless they were re-queued with newer events meanwhile.
+	 * @param {Array<{ sessionId: string, seq: number }>} covered - the batch as captured when the run started.
+	 */
+	complete(covered) {
+		const seqs = new Map(covered.map((job) => [job.sessionId, job.seq]));
+		return this.persist(() => {
+			for (const [sessionId, seq] of seqs) this.data.watermarks[sessionId] = Math.max(seq, this.data.watermarks[sessionId] ?? 0);
+			for (const [sessionId, seq] of seqs) {
+				const queued = this.data.queue.find((job) => job.sessionId === sessionId);
+				if (queued === undefined || queued.seq <= seq) delete this.data.attempts?.[sessionId];
+			}
+			this.data.queue = this.data.queue.filter((job) => !seqs.has(job.sessionId) || job.seq > seqs.get(job.sessionId));
+		});
+	}
+
+	/**
+	 * Count one failed run against each session of its batch.
+	 * @returns {Promise<Record<string, number>>} the new counts.
+	 */
+	noteFailure(sessionIds) {
+		const counts = {};
+		return this.persist(() => {
+			this.data.attempts ??= {};
+			for (const id of sessionIds) counts[id] = this.data.attempts[id] = (this.data.attempts[id] ?? 0) + 1;
+		}).then(() => counts);
+	}
+
+	/** A session made progress: its earlier failures no longer count against it. */
+	clearAttempts(sessionIds) {
+		if (!sessionIds.some((id) => this.data.attempts?.[id] !== undefined)) return Promise.resolve();
+		return this.persist(() => {
+			for (const id of sessionIds) delete this.data.attempts?.[id];
+		});
+	}
+
+	/** @returns {number} failed runs counted against a session since it last completed. */
+	attempts(sessionId) {
+		return this.data.attempts?.[sessionId] ?? 0;
+	}
+
+	/** Forget watermarks and failure counts of sessions that no longer exist (queued ones are kept). */
+	pruneSessions(existingIds) {
+		const keep = new Set(existingIds);
+		const stale = (id) => !keep.has(id) && !this.data.queue.some((job) => job.sessionId === id);
+		const ids = [...Object.keys(this.data.watermarks), ...Object.keys(this.data.attempts ?? {})];
+		if (!ids.some(stale)) return Promise.resolve();
+		return this.persist(() => {
+			for (const id of Object.keys(this.data.watermarks)) if (stale(id)) delete this.data.watermarks[id];
+			for (const id of Object.keys(this.data.attempts ?? {})) if (stale(id)) delete this.data.attempts[id];
+		});
+	}
+
+	/** @returns {string[]} projects consolidated since the last cross-project run. */
+	crossProjects() {
+		return [...(this.data.cross?.projects ?? [])];
+	}
+
+	/** @returns {number | undefined} epoch ms of the last cross-project run. */
+	get crossAt() {
+		return this.data.cross?.at;
+	}
+
+	/** Note a successful project run, so a cross-project run becomes due. */
+	noteProjectRun(cwd) {
+		return this.persist(() => {
+			const projects = this.data.cross?.projects ?? [];
+			/* The first project run starts the day: a cross-project run is never due right after it. */
+			this.data.cross = { ...this.data.cross, at: this.data.cross?.at ?? this.now(), projects: projects.includes(cwd) ? projects : [...projects, cwd] };
+		});
+	}
+
+	/** Mark a cross-project run done. */
+	completeCross(at) {
+		return this.persist(() => {
+			this.data.cross = { at, projects: [] };
+		});
+	}
+
+	/** @returns {number} last consolidated event seq for a session, 0 if never. */
+	watermark(sessionId) {
+		return this.data.watermarks[sessionId] ?? 0;
+	}
+
+	/** @returns {number} epoch ms when this memory root was first used by the plugin. */
+	get installedAt() {
+		return this.data.installedAt;
+	}
+
+	get paused() {
+		return this.data.paused;
+	}
+
+	/** @param {{ since: number, reason: string, kind?: "auth" | "repeated" | "manual" } | null} value */
+	setPaused(value) {
+		return this.persist(() => {
+			this.data.paused = value;
+		});
+	}
+
+	/** Append one run to the log, rewriting the file when it exceeds the limit. */
+	appendLog(entry) {
+		const next = this.chain.then(async () => {
+			this.log.push(entry);
+			await mkdir(this.dir, { recursive: true });
+			if (this.log.length > LOG_LIMIT) {
+				this.log = this.log.slice(-LOG_LIMIT);
+				await writeAtomic(this.logFile, this.log.map((item) => JSON.stringify(item)).join("\n") + "\n");
+			} else await appendFile(this.logFile, JSON.stringify(entry) + "\n", "utf8");
+		});
+		this.chain = next.catch(() => {});
+		return next;
+	}
+
+	/** @returns {LogEntry[]} the last `n` runs, oldest first. */
+	recentLog(n) {
+		return this.log.slice(-n);
+	}
+}

package/lib/status.js

@@ -0,0 +1,55 @@
+/**
+ * Publishes the runner status into the plugin's own `status` settings field
+ * (the host→client channel). The settings service only writes entries whose
+ * plugin is already active, so a write attempted while the plugin is still
+ * loading fails; a failed write is retried and is never remembered as
+ * published, so the next identical status is not skipped.
+ */
+
+const RETRY_MS = 2000;
+
+/**
+ * @param {{ name: string, root: string, warn: (message: string) => void,
+ *   setTimer?: (fn: () => void, ms: number) => unknown, clearTimer?: (handle: unknown) => void, retryMs?: number }} options
+ */
+export function createStatusPublisher({ name, root, warn, setTimer = setTimeout, clearTimer = clearTimeout, retryMs = RETRY_MS }) {
+	let settings;
+	let latest;
+	let published;
+	let retry;
+
+	const flush = () => {
+		if (settings === undefined || latest === undefined || latest === published) return;
+		const next = latest;
+		const target = settings;
+		target.update(name, { status: JSON.parse(next) }).then(() => {
+			published = next;
+		}, (error) => {
+			if (retry !== undefined || settings !== target) return;
+			warn(`memory: could not publish status (will retry): ${error?.message}`);
+			retry = setTimer(() => {
+				retry = undefined;
+				flush();
+			}, retryMs);
+		});
+	};
+
+	return {
+		/** Start writing through the settings service. */
+		attach(service) {
+			settings = service;
+			flush();
+		},
+		/** Stop writing (settings service gone or plugin unloading). */
+		detach() {
+			settings = undefined;
+			if (retry !== undefined) clearTimer(retry);
+			retry = undefined;
+		},
+		/** Record the newest status and write it when possible. */
+		publish(status) {
+			latest = JSON.stringify({ ...status, root });
+			flush();
+		}
+	};
+}

package/lib/store.js

@@ -0,0 +1,320 @@
+/**
+ * Memory note storage with optimistic concurrency.
+ *
+ * Sessions and dreaming can write the same note. Every read returns a
+ * `version` (content hash); a write or delete must present the version it
+ * read, or `null` to create a note that must not exist yet. A mismatch throws
+ * `MemoryConflictError` and leaves the file untouched, so the caller re-reads
+ * and rewrites instead of silently overwriting. The version is a content hash
+ * rather than mtime/size, which two quick same-length writes could collide on.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, rmdir, stat, writeFile, unlink } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { partitionDir, resolveEntry } from "./paths.js";
+import { renameWithRetry } from "./fsutil.js";
+
+/** Dreaming runs whose pre-change note copies are kept. */
+export const HISTORY_KEEP = 20;
+/** Leftover `.tmp` files older than this are swept. */
+const STALE_TMP_MS = 3_600_000;
+const SEARCH_HITS = 50;
+
+/** Error for a write or delete whose expected version no longer matches. */
+export class MemoryConflictError extends Error {
+	code = "MEMORY_CONFLICT";
+	/**
+	 * @param {string} path - the note path.
+	 * @param {string | null} currentVersion - version on disk, or null when the note is gone.
+	 */
+	constructor(path, currentVersion) {
+		super(`memory note ${path} changed since it was read`);
+		this.name = "MemoryConflictError";
+		this.currentVersion = currentVersion;
+	}
+}
+
+const versionOf = (content) => createHash("sha256").update(content).digest("hex").slice(0, 16);
+
+async function readIfExists(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+/**
+ * Copies a note's content aside before a dreaming run first changes it, to
+ * `<root>/.state/history/<runId>/<path relative to the root>`, so a run's
+ * changes can be undone by copying the files back.
+ * @param {string} root - memory root.
+ * @param {string} runId - directory name for this run.
+ * @returns {(file: string, content: string) => Promise<void>}
+ */
+export function createBackup(root, runId) {
+	const done = new Set();
+	return async (file, content) => {
+		const rel = relative(root, file);
+		if (done.has(rel.toLowerCase())) return;
+		done.add(rel.toLowerCase());
+		const dest = join(root, ".state", "history", runId, rel);
+		await mkdir(dirname(dest), { recursive: true });
+		await writeFile(dest, content, "utf8");
+	};
+}
+
+/** Keep only the newest `keep` run snapshots under `<root>/.state/history/`. */
+export async function pruneHistory(root, keep = HISTORY_KEEP) {
+	const dir = join(root, ".state", "history");
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch {
+		return;
+	}
+	const runs = [];
+	for (const name of names) {
+		const info = await stat(join(dir, name)).catch(() => null);
+		if (info?.isDirectory()) runs.push({ name, at: info.mtimeMs });
+	}
+	runs.sort((a, b) => b.at - a.at);
+	for (const { name } of runs.slice(keep)) await rm(join(dir, name), { recursive: true, force: true });
+}
+
+/**
+ * Records the notes one run changed, for the dreaming log. A note counts
+ * once, by its state before and after the run: written three times is one
+ * modification; created and then deleted is no change.
+ * @param {{ backup?: (file: string, content: string) => Promise<void> }} [options] - copies a note aside before its first change.
+ */
+export function createChangeTracker({ backup } = {}) {
+	/** path → whether it existed before the run, and whether it exists now. */
+	const notes = new Map();
+	return {
+		backup,
+		/** @param {"created" | "modified" | "deleted"} kind @param {string} path - note label, e.g. "user/INDEX.md". */
+		record(kind, path) {
+			const note = notes.get(path) ?? { before: kind !== "created" };
+			note.after = kind !== "deleted";
+			notes.set(path, note);
+		},
+		/** @returns {{ created: number, modified: number, deleted: number, paths: { created: string[], modified: string[], deleted: string[] } }} */
+		summary() {
+			const paths = { created: [], modified: [], deleted: [] };
+			for (const [path, { before, after }] of notes) {
+				if (!before && after) paths.created.push(path);
+				else if (before && after) paths.modified.push(path);
+				else if (before && !after) paths.deleted.push(path);
+			}
+			return { created: paths.created.length, modified: paths.modified.length, deleted: paths.deleted.length, paths };
+		}
+	};
+}
+
+export class MemoryStore {
+	/** @param {string} root - memory root (see `resolveMemoryRoot`). */
+	constructor(root) {
+		this.root = root;
+		/** Per-file tail of the in-process write queue; sessions and dreaming share one process. */
+		this.locks = new Map();
+	}
+
+	/** Run `fn` after every earlier mutation of the same file, so check-then-rename is atomic in-process. */
+	async exclusive(file, fn) {
+		/* Case-folded: on Windows and macOS `Note.md` and `note.md` are one file. */
+		const key = file.toLowerCase();
+		const previous = this.locks.get(key) ?? Promise.resolve();
+		let release;
+		const current = new Promise((resolve) => { release = resolve; });
+		const tail = previous.then(() => current);
+		this.locks.set(key, tail);
+		await previous;
+		try {
+			return await fn();
+		} finally {
+			release();
+			if (this.locks.get(key) === tail) this.locks.delete(key);
+		}
+	}
+
+	/** @returns {Promise<Array<{ path: string, bytes: number, version: string }>>} every note in the partition. */
+	async list(scope, cwd) {
+		const dir = partitionDir(this.root, scope, cwd);
+		const out = [];
+		const walk = async (abs, rel) => {
+			let entries;
+			try {
+				entries = await readdir(abs, { withFileTypes: true });
+			} catch (error) {
+				if (error.code === "ENOENT") return;
+				throw error;
+			}
+			for (const entry of entries) {
+				if (entry.name.startsWith(".")) continue;
+				const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+				if (entry.isDirectory()) await walk(join(abs, entry.name), relPath);
+				else if (entry.isFile() && entry.name.endsWith(".md")) {
+					const content = await readFile(join(abs, entry.name), "utf8");
+					out.push({ path: relPath, bytes: Buffer.byteLength(content), version: versionOf(content) });
+				}
+			}
+		};
+		await walk(dir, "");
+		return out;
+	}
+
+	/** @returns {Promise<{ content: string, version: string } | null>} the note, or null when absent. */
+	async read(scope, cwd, path) {
+		const content = await readIfExists(resolveEntry(partitionDir(this.root, scope, cwd), path));
+		return content === null ? null : { content, version: versionOf(content) };
+	}
+
+	/**
+	 * Create or replace a note.
+	 * @param {string | null} expectedVersion - version read before editing, or null to create.
+	 * @param {ReturnType<typeof createChangeTracker>} [tracker]
+	 * @returns {Promise<{ version: string }>}
+	 */
+	async write(scope, cwd, path, content, expectedVersion, tracker) {
+		const file = resolveEntry(partitionDir(this.root, scope, cwd), path);
+		return this.exclusive(file, async () => {
+			const current = await readIfExists(file);
+			const currentVersion = current === null ? null : versionOf(current);
+			if (currentVersion !== expectedVersion) throw new MemoryConflictError(path, currentVersion);
+			await mkdir(dirname(file), { recursive: true });
+			if (current !== null) await tracker?.backup?.(file, current);
+			const temp = join(dirname(file), `.${randomUUID()}.tmp`);
+			try {
+				await writeFile(temp, content, "utf8");
+				await renameWithRetry(temp, file);
+			} catch (error) {
+				await rm(temp, { force: true });
+				throw error;
+			}
+			tracker?.record(current === null ? "created" : "modified", path);
+			return { version: versionOf(content) };
+		});
+	}
+
+	/**
+	 * Delete a note.
+	 * @param {string} expectedVersion - version read before deleting.
+	 * @param {ReturnType<typeof createChangeTracker>} [tracker]
+	 */
+	async remove(scope, cwd, path, expectedVersion, tracker) {
+		const file = resolveEntry(partitionDir(this.root, scope, cwd), path);
+		await this.exclusive(file, async () => {
+			const current = await readIfExists(file);
+			const currentVersion = current === null ? null : versionOf(current);
+			if (currentVersion === null || currentVersion !== expectedVersion) throw new MemoryConflictError(path, currentVersion);
+			await tracker?.backup?.(file, current);
+			await unlink(file);
+			tracker?.record("deleted", path);
+		});
+		await this.pruneEmptyDirs(partitionDir(this.root, scope, cwd), dirname(file));
+	}
+
+	/**
+	 * Move a note, possibly into another partition, in one rename: the note is
+	 * never missing and never duplicated. The target must not exist.
+	 * @param {{ scope: "project" | "user", cwd?: string, path: string }} from
+	 * @param {{ scope: "project" | "user", cwd?: string, path: string }} to
+	 * @param {string} expectedVersion - version of the source read before moving.
+	 * @param {{ backup?: Function }} [tracker] - only `backup` is used; the caller records the change under its own labels.
+	 * @returns {Promise<{ version: string }>}
+	 */
+	async move(from, to, expectedVersion, tracker) {
+		const source = resolveEntry(partitionDir(this.root, from.scope, from.cwd), from.path);
+		const target = resolveEntry(partitionDir(this.root, to.scope, to.cwd), to.path);
+		if (source.toLowerCase() === target.toLowerCase()) throw new Error("source and target are the same note");
+		const [first, second] = source.toLowerCase() < target.toLowerCase() ? [source, target] : [target, source];
+		const result = await this.exclusive(first, () => this.exclusive(second, async () => {
+			const current = await readIfExists(source);
+			const currentVersion = current === null ? null : versionOf(current);
+			if (currentVersion === null || currentVersion !== expectedVersion) throw new MemoryConflictError(from.path, currentVersion);
+			if ((await readIfExists(target)) !== null) throw new Error(`${to.path} already exists in the target partition; pick another path, or merge into it with memory_write and delete the source.`);
+			await tracker?.backup?.(source, current);
+			await mkdir(dirname(target), { recursive: true });
+			await renameWithRetry(source, target);
+			return { version: versionOf(current) };
+		}));
+		await this.pruneEmptyDirs(partitionDir(this.root, from.scope, from.cwd), dirname(source));
+		return result;
+	}
+
+	/** Remove now-empty note directories up to (not including) the partition directory. */
+	async pruneEmptyDirs(partition, dir) {
+		for (;;) {
+			const rel = relative(partition, dir);
+			if (rel === "" || rel.startsWith("..") || rel === dir) return;
+			try {
+				await rmdir(dir);
+			} catch {
+				return;
+			}
+			dir = dirname(dir);
+		}
+	}
+
+	/**
+	 * Case-insensitive literal search across one partition's notes.
+	 * @returns {Promise<string[]>} `path:line: text` hits, at most 50.
+	 */
+	async search(scope, cwd, query) {
+		const needle = query.toLowerCase();
+		const hits = [];
+		for (const { path } of await this.list(scope, cwd)) {
+			const note = await this.read(scope, cwd, path);
+			for (const [index, line] of (note?.content ?? "").split("\n").entries()) {
+				if (!line.toLowerCase().includes(needle)) continue;
+				hits.push(`${path}:${index + 1}: ${line.trim().slice(0, 200)}`);
+				if (hits.length >= SEARCH_HITS) return hits;
+			}
+		}
+		return hits;
+	}
+
+	/** Delete `.tmp` files that a crash left in the partitions. */
+	async sweep(now = Date.now()) {
+		const walk = async (dir) => {
+			let entries;
+			try {
+				entries = await readdir(dir, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const entry of entries) {
+				const abs = join(dir, entry.name);
+				if (entry.isDirectory()) await walk(abs);
+				else if (entry.isFile() && entry.name.endsWith(".tmp")) {
+					const info = await stat(abs).catch(() => null);
+					if (info !== null && now - info.mtimeMs > STALE_TMP_MS) await rm(abs, { force: true });
+				}
+			}
+		};
+		await walk(join(this.root, "user"));
+		await walk(join(this.root, "projects"));
+	}
+
+	/** @returns {Promise<string | null>} the partition's INDEX.md content, or null. */
+	async readIndex(scope, cwd) {
+		return (await this.read(scope, cwd, "INDEX.md"))?.content ?? null;
+	}
+
+	/**
+	 * Synchronous INDEX read for system-prompt section callbacks, which DSH
+	 * evaluates synchronously; called once per session snapshot.
+	 * @returns {string | null} the partition's INDEX.md content, or null.
+	 */
+	readIndexSync(scope, cwd) {
+		try {
+			return readFileSync(resolveEntry(partitionDir(this.root, scope, cwd), "INDEX.md"), "utf8");
+		} catch {
+			/* A missing or unreadable INDEX (EACCES, EISDIR) must not break the session's prompt assembly: act as if empty. */
+			return null;
+		}
+	}
+}