dsh-novel-write-engine 0.2.1 → 0.2.2

package/lib/index.js

@@ -9,9 +9,14 @@ import { fileURLToPath } from "node:url";
 import { deflateRawSync } from "node:zlib";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 // src/constants.ts
+/** Panel and session identifiers. */
+const PLUGIN_NAME = "dsh-novel-write-engine";
 const PANEL_ID = "novel-workshop";
 const PANEL_ROUTE = "/api/novel-write-engine/panel";
 const SKILL_NAME = "novel-write-engine";
+const REMOTE_VERSION = 4;
+/** The panel is a recent-history view; the wire payload and UI use one cap. */
+const PANEL_CHAPTER_LIMIT = 30;
 /** Project-relative locations. Every write goes through these constants. */
 const PROJECT_FILE = "novel.yaml";
 const OUTLINE_FILE = "outline/outline.yaml";
@@ -26,9 +31,13 @@ const BACKUP_DIR = "backups";
 const HISTORY_DIR = "history";
 /** Brief receipts are append-only evidence, separate from content transactions. */
 const BRIEF_RECEIPTS_FILE = "state/briefs.yaml";
+const OUTLINE_DIR = "outline";
 const LOCK_FILE = ".engine.lock";
 const STAGING_DIR = ".staging";
 const REGISTRY_FILE = "projects.yaml";
+const SESSION_BINDINGS_FILE = "session-bindings.yaml";
+const METADATA_LOCK_FILE = ".metadata.lock";
+const ARCHIVE_DIGESTS_FILE = "state/archive-digests.json";
 /** Files owned by the engine under `state/`. */
 const STATE_FILES = {
 	pipeline: "pipeline.yaml",
@@ -90,6 +99,11 @@ const LIMITS = {
 	maxWorldbookTextChars: 2e3,
 	maxSearchQueryChars: 200
 };
+/** Re-exported enums make adapter code readable without importing types twice. */
+const SCENE_TYPE_DEFAULT = "日常过渡章";
+const DEFAULT_GENRE = "都市现代";
+const DEFAULT_PLATFORM = "fanqie";
+const INITIAL_STAGE = "idle";
 /** The order used to render the nine-phase progress strip. */
 const PHASE_STRIP = [
 	"P1",
@@ -102,6 +116,37 @@ const PHASE_STRIP = [
 	"P8",
 	"P9"
 ];
+/** Tool names, kept here so the arch test can assert one namespace. */
+const TOOL_NAMES = [
+	"novel_init",
+	"novel_status",
+	"novel_brief",
+	"novel_plan_world",
+	"novel_plan_chapter",
+	"novel_write_draft",
+	"novel_review",
+	"novel_revise",
+	"novel_check",
+	"novel_archive",
+	"novel_word_count",
+	"novel_state",
+	"novel_amend",
+	"novel_rollback",
+	"novel_diff",
+	"novel_export",
+	"novel_audit",
+	"novel_pipeline",
+	"novel_blueprint",
+	"novel_outline",
+	"novel_outline_import",
+	"novel_worldbook",
+	"novel_search",
+	"novel_doctor",
+	"novel_report",
+	"novel_guide",
+	"novel_reopen",
+	"novel_restore"
+];
 /** The ten high-frequency tools kept when `tools.mode = core`. */
 const CORE_TOOLS = [
 	"novel_init",
@@ -152,7 +197,7 @@ const SCENE_TYPES = [
 	"情感爆发章",
 	"纯叙事章"
 ];
-/** All thirty-one service operations (22 inherited from 0.1.x, 9 book-level). */
+/** All thirty-two service operations (22 inherited + 9 book-level + restoreBackup). */
 const OPERATIONS = [
 	"initProject",
 	"archiveChapter",
@@ -190,6 +235,9 @@ const OPERATIONS = [
 /** Error families map one-to-one to the three repair actions a caller can take. */
 const ERROR_CODES = {
 	PROJECT_NOT_FOUND: "ENGINE_PROJECT_NOT_FOUND",
+	PROJECT_AMBIGUOUS: "ENGINE_PROJECT_AMBIGUOUS",
+	PROJECT_MISSING: "ENGINE_PROJECT_MISSING",
+	PROJECT_IDENTITY_MISMATCH: "ENGINE_PROJECT_IDENTITY_MISMATCH",
 	PROJECT_EXISTS: "ENGINE_PROJECT_EXISTS",
 	STAGE_ORDER: "ENGINE_STAGE_ORDER",
 	GATE_BLOCKED: "ENGINE_GATE_BLOCKED",
@@ -2182,6 +2230,61 @@ var FsStore = class {
 			throw error;
 		}
 	}
+	/**
+	* Directory entries without following symlinks. Used by bounded workspace
+	* discovery so a symlinked child is never mistaken for a project.
+	*/
+	async entries(relativeDir) {
+		try {
+			const absolute = relativeDir === "." ? resolve(this.root) : await this.safePath(relativeDir);
+			return (await promises.readdir(absolute, { withFileTypes: true })).map((entry) => ({
+				name: entry.name,
+				directory: entry.isDirectory(),
+				symbolicLink: entry.isSymbolicLink()
+			})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+		} catch (error) {
+			if (isMissing(error)) return [];
+			throw error;
+		}
+	}
+	/**
+	* Metadata for a path without following the final symlink. A scandir probe
+	* only needs to know that a candidate is a real directory; it must not read
+	* through a link to decide that.
+	*/
+	async lstat(relativePath) {
+		try {
+			const info = await promises.lstat(relativePath === "." ? resolve(this.root) : this.path(relativePath));
+			return {
+				directory: info.isDirectory(),
+				symbolicLink: info.isSymbolicLink(),
+				file: info.isFile()
+			};
+		} catch (error) {
+			if (isMissing(error)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Follow a project-root symlink when classifying the root itself. Child
+	* discovery still uses lstat/entries, so a symlinked *subdirectory* remains
+	* out of workspace scans. The device/inode pair lets a transaction detect a
+	* root that was deleted and recreated under the same path.
+	*/
+	async statRoot() {
+		try {
+			const info = await promises.stat(resolve(this.root));
+			return {
+				directory: info.isDirectory(),
+				dev: info.dev,
+				ino: info.ino,
+				birthtimeMs: info.birthtimeMs
+			};
+		} catch (error) {
+			if (isMissing(error)) return null;
+			throw error;
+		}
+	}
 	async readText(relativePath) {
 		try {
 			return await promises.readFile(await this.safePath(relativePath), "utf8");
@@ -2202,10 +2305,33 @@ var FsStore = class {
 		}
 		return narrow(kind, (typeof parsed === "object" && parsed !== null && typeof parsed.schema_version === "number" ? parsed.schema_version : 1) < 1 ? migrateDocument(parsed, MIGRATIONS, 1) : parsed);
 	}
+	/**
+	* Create missing directories below the store root without ever recreating the
+	* root itself. `mkdir(..., {recursive:true})` silently recreates a deleted
+	* project directory; walking one segment at a time makes the first missing
+	* root fail with ENOENT and keeps deleted projects deleted.
+	*/
+	async ensureParent(absolutePath) {
+		const root = resolve(this.root);
+		const parent = dirname(absolutePath);
+		const rel = relative(root, parent);
+		if (rel === "" || rel === ".") return;
+		let current = root;
+		for (const segment of rel.split(sep)) {
+			if (segment === "") continue;
+			current = join(current, segment);
+			try {
+				await promises.mkdir(current);
+			} catch (error) {
+				if (error.code === "EEXIST") continue;
+				throw error;
+			}
+		}
+	}
 	/** Write text atomically: temp file, fsync, rename, directory fsync. */
 	async writeText(relativePath, text) {
 		const absolute = await this.safePath(relativePath);
-		await promises.mkdir(dirname(absolute), { recursive: true });
+		await this.ensureParent(absolute);
 		const temp = `${absolute}.${randomUUID()}.tmp`;
 		try {
 			const handle = await promises.open(temp, "w");
@@ -2242,7 +2368,7 @@ var FsStore = class {
 	/** Raw append used only by the journal (JSONL is append-only by design). */
 	async appendText(relativePath, text) {
 		const absolute = await this.safePath(relativePath);
-		await promises.mkdir(dirname(absolute), { recursive: true });
+		await this.ensureParent(absolute);
 		const handle = await promises.open(absolute, "a+");
 		try {
 			const info = await handle.stat();
@@ -2269,7 +2395,7 @@ var FsStore = class {
 	}
 	async writeBytes(relativePath, bytes) {
 		const absolute = await this.safePath(relativePath);
-		await promises.mkdir(dirname(absolute), { recursive: true });
+		await this.ensureParent(absolute);
 		const temp = `${absolute}.${randomUUID()}.tmp`;
 		try {
 			const handle = await promises.open(temp, "w");
@@ -2809,8 +2935,37 @@ async function runTransaction(store, input) {
 	let journaledCommitted = false;
 	let backupMarked = false;
 	let backupComplete = false;
+	let rootDisappeared = false;
+	let rootIdentity = null;
+	const rootKey = (info) => `${info.dev}:${info.ino}:${info.birthtimeMs}`;
+	const rootUnavailable = async () => {
+		try {
+			const info = await store.statRoot();
+			return info === null || !info.directory || rootIdentity !== null && rootKey(info) !== rootIdentity;
+		} catch {
+			return false;
+		}
+	};
+	const assertRootPresent = async () => {
+		const info = await store.statRoot();
+		if (info === null || !info.directory) {
+			rootDisappeared = true;
+			throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, "the project root disappeared during the transaction", "restore the directory/mount and retry; the engine will not recreate a deleted project");
+		}
+		const key = rootKey(info);
+		if (rootIdentity === null) {
+			rootIdentity = key;
+			return;
+		}
+		if (key !== rootIdentity) {
+			rootDisappeared = true;
+			throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, "the project root was replaced during the transaction", "restore the original directory/mount and retry; the engine will not write into a replacement project");
+		}
+	};
 	try {
+		await assertRootPresent();
 		for (const file of input.files) {
+			await assertRootPresent();
 			const target = joinRel(staging, file.path);
 			if (file.bytes !== void 0) await store.writeBytes(target, file.bytes);
 			else await store.writeText(target, file.text ?? "");
@@ -2823,6 +2978,7 @@ async function runTransaction(store, input) {
 			if (sha256(stagedBytes.toString("base64")) !== expected.get(file.path)) throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, `staged copy of ${file.path} failed verification`);
 		}
 		if (input.afterVerify !== void 0) await input.afterVerify();
+		await assertRootPresent();
 		for (const file of input.files) before.set(file.path, await store.readBytes(file.path));
 		for (const file of input.files) {
 			const existing = before.get(file.path);
@@ -2854,6 +3010,7 @@ async function runTransaction(store, input) {
 			backupMarked = true;
 			backupComplete = true;
 		}
+		await assertRootPresent();
 		const beforeHashes = Object.fromEntries(input.files.map((file) => {
 			const bytes = before.get(file.path);
 			return [file.path, bytes === null || bytes === void 0 ? null : sha256(Buffer.from(bytes).toString("base64"))];
@@ -2871,6 +3028,7 @@ async function runTransaction(store, input) {
 			...input.reason === void 0 ? {} : { reason: input.reason }
 		});
 		for (const [index, file] of input.files.entries()) {
+			await assertRootPresent();
 			const from = await store.safePath(joinRel(staging, file.path));
 			const to = await store.safePath(file.path);
 			await promises.mkdir(dirname(to), { recursive: true });
@@ -2879,6 +3037,7 @@ async function runTransaction(store, input) {
 			renamed.push(file.path);
 			if (input.afterRename !== void 0) await input.afterRename(file.path, index);
 		}
+		await assertRootPresent();
 		for (const directory of targetDirectories) await syncDirectory(directory);
 		for (const file of input.files) if (await store.hashBytes(file.path) !== expected.get(file.path)) throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, `readback of ${file.path} does not match what was staged`, "the file on disk was modified by another process during the commit");
 		await appendJournal(store, {
@@ -2900,13 +3059,14 @@ async function runTransaction(store, input) {
 			force: true
 		}).catch(() => void 0);
 	} catch (error) {
-		const rollbackProblem = await restoreTargets(store, renamed, before);
-		if (rollbackProblem === null) await promises.rm(store.path(staging), {
+		if (!rootDisappeared) rootDisappeared = await rootUnavailable();
+		const rollbackProblem = rootDisappeared ? null : await restoreTargets(store, renamed, before);
+		if (!rootDisappeared && rollbackProblem === null) await promises.rm(store.path(staging), {
 			recursive: true,
 			force: true
 		}).catch(() => void 0);
-		if (input.backup && (!backupMarked || !backupComplete && renamed.length === 0)) await store.removeTree(backupDir(input.txid)).catch(() => void 0);
-		if (!journaledCommitted) await appendJournal(store, {
+		if (!rootDisappeared && input.backup && (!backupMarked || !backupComplete && renamed.length === 0)) await store.removeTree(backupDir(input.txid)).catch(() => void 0);
+		if (!journaledCommitted && !rootDisappeared) await appendJournal(store, {
 			txid: input.txid,
 			at: (/* @__PURE__ */ new Date()).toISOString(),
 			op: input.op,
@@ -2926,7 +3086,7 @@ async function runTransaction(store, input) {
 	}
 }
 // src/store/registry.ts
-const empty = () => ({
+const empty$1 = () => ({
 	schema_version: 1,
 	active: null,
 	projects: []
@@ -2943,7 +3103,7 @@ var ProjectRegistry = class {
 	/** Read the registry; a missing file is an empty registry, a corrupt one is a fault. */
 	async read() {
 		const text = await this.store.readText(REGISTRY_FILE);
-		if (text === null) return empty();
+		if (text === null) return empty$1();
 		let raw;
 		try {
 			raw = parse(text);
@@ -2953,20 +3113,45 @@ var ProjectRegistry = class {
 		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${REGISTRY_FILE} is not an object`);
 		const record = raw;
 		if (record.schema_version !== 1) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${REGISTRY_FILE} has an unsupported schema_version`);
+		const projects = [];
+		const indexes = /* @__PURE__ */ new Map();
+		if (record.projects !== void 0 && !Array.isArray(record.projects)) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${REGISTRY_FILE}.projects must be an array`, "fix or delete the registry file; projects on disk are unaffected");
+		if (Array.isArray(record.projects)) for (const value of record.projects) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+			const entry = value;
+			if (typeof entry.root !== "string" || entry.root === "") continue;
+			if (typeof entry.title !== "string") continue;
+			const normalized = {
+				root: resolve(entry.root),
+				title: entry.title,
+				...typeof entry.created_at === "string" && entry.created_at !== "" ? { created_at: entry.created_at } : {},
+				updated_at: typeof entry.updated_at === "string" ? entry.updated_at : ""
+			};
+			const existing = indexes.get(normalized.root);
+			if (existing === void 0) {
+				indexes.set(normalized.root, projects.length);
+				projects.push(normalized);
+			} else projects[existing] = normalized;
+		}
 		return {
 			schema_version: 1,
-			active: typeof record.active === "string" ? record.active : null,
-			projects: Array.isArray(record.projects) ? record.projects.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.root === "string" && typeof entry.title === "string") : []
+			active: typeof record.active === "string" && record.active.trim() !== "" ? resolve(record.active) : null,
+			projects
 		};
 	}
 	/** Insert or update one project row. */
 	async register(entry) {
 		const document = await this.read();
+		const root = resolve(entry.root);
+		const previous = document.projects.find((candidate) => candidate.root === root);
+		const created_at = entry.created_at ?? previous?.created_at;
 		const row = {
-			...entry,
+			root,
+			title: entry.title,
+			...created_at === void 0 || created_at === "" ? {} : { created_at },
 			updated_at: (/* @__PURE__ */ new Date()).toISOString()
 		};
-		const rows = document.projects.filter((candidate) => candidate.root !== entry.root);
+		const rows = document.projects.filter((candidate) => candidate.root !== root);
 		rows.push(row);
 		const next = {
 			...document,
@@ -2979,7 +3164,7 @@ var ProjectRegistry = class {
 	async setActive(root) {
 		const next = {
 			...await this.read(),
-			active: root
+			active: resolve(root)
 		};
 		await this.write(next);
 		return next;
@@ -2987,10 +3172,11 @@ var ProjectRegistry = class {
 	/** Drop a row; the project on disk is untouched. */
 	async forget(root) {
 		const document = await this.read();
+		const target = resolve(root);
 		const next = {
 			...document,
-			projects: document.projects.filter((entry) => entry.root !== root),
-			active: document.active === root ? null : document.active
+			projects: document.projects.filter((entry) => entry.root !== target),
+			active: document.active === target ? null : document.active
 		};
 		await this.write(next);
 		return next;
@@ -2999,6 +3185,132 @@ var ProjectRegistry = class {
 		await this.store.writeText(REGISTRY_FILE, stringify(document, { lineWidth: 0 }));
 	}
 };
+// src/store/bindings.ts
+const empty = () => ({
+	schema_version: 1,
+	bindings: []
+});
+const sources = /* @__PURE__ */ new Set([
+	"explicit",
+	"init",
+	"command"
+]);
+const row = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const record = value;
+	if (typeof record.session_id !== "string" || record.session_id === "") return null;
+	if (typeof record.root !== "string" || record.root === "") return null;
+	const source = typeof record.source === "string" && sources.has(record.source) ? record.source : "explicit";
+	return {
+		session_id: record.session_id,
+		root: resolve(record.root),
+		title: typeof record.title === "string" ? record.title : "",
+		project_created_at: typeof record.project_created_at === "string" ? record.project_created_at : "",
+		bound_at: typeof record.bound_at === "string" ? record.bound_at : "",
+		source
+	};
+};
+/**
+* Session-scoped project choices. This file is convenience state, never project
+* truth: deleting it loses no book, and a corrupt file is a hard read error
+* rather than a silent "no bindings" that could write into another project.
+*/
+var SessionBindings = class {
+	store;
+	options;
+	constructor(store, options = {}) {
+		this.store = store;
+		this.options = options;
+	}
+	async read() {
+		const text = await this.store.readText(SESSION_BINDINGS_FILE);
+		if (text === null) return empty();
+		let raw;
+		try {
+			raw = parse(text);
+		} catch (error) {
+			throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${SESSION_BINDINGS_FILE} is not valid YAML: ${error instanceof Error ? error.message : String(error)}`, "fix or delete the session binding file; projects on disk are unaffected", { cause: error });
+		}
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${SESSION_BINDINGS_FILE} is not an object`);
+		const record = raw;
+		if (record.schema_version !== 1) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${SESSION_BINDINGS_FILE} has an unsupported schema_version`);
+		if (record.bindings !== void 0 && !Array.isArray(record.bindings)) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${SESSION_BINDINGS_FILE}.bindings must be an array`, "fix or delete the session binding file; projects on disk are unaffected");
+		const bindings = [];
+		const indexes = /* @__PURE__ */ new Map();
+		for (const candidate of record.bindings ?? []) {
+			const parsed = row(candidate);
+			if (parsed === null) continue;
+			const existing = indexes.get(parsed.session_id);
+			if (existing === void 0) {
+				indexes.set(parsed.session_id, bindings.length);
+				bindings.push(parsed);
+			} else bindings[existing] = parsed;
+		}
+		return {
+			schema_version: 1,
+			bindings
+		};
+	}
+	async get(sessionId) {
+		return (await this.read()).bindings.find((entry) => entry.session_id === sessionId);
+	}
+	async list() {
+		return (await this.read()).bindings;
+	}
+	/**
+	* Insert or update one session's choice. A byte-for-byte equivalent binding
+	* does not touch the file, so a read-only operation can call this safely.
+	*/
+	async bind(input) {
+		const document = await this.read();
+		const root = resolve(input.root);
+		const existing = document.bindings.find((entry) => entry.session_id === input.session_id);
+		if (existing !== void 0 && existing.root === root && existing.title === input.title && existing.project_created_at === input.project_created_at) return {
+			binding: existing,
+			document,
+			changed: false
+		};
+		const binding = {
+			session_id: input.session_id,
+			root,
+			title: input.title,
+			project_created_at: input.project_created_at,
+			bound_at: (this.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+			source: input.source
+		};
+		const next = {
+			schema_version: 1,
+			bindings: existing === void 0 ? [...document.bindings, binding] : document.bindings.map((entry) => entry.session_id === input.session_id ? binding : entry)
+		};
+		await this.write(next);
+		return {
+			binding,
+			document: next,
+			changed: true
+		};
+	}
+	/** Remove one session binding; a missing row is a no-op. */
+	async clear(sessionId) {
+		const document = await this.read();
+		const bindings = document.bindings.filter((entry) => entry.session_id !== sessionId);
+		if (bindings.length === document.bindings.length) return {
+			document,
+			changed: false
+		};
+		const next = {
+			schema_version: 1,
+			bindings
+		};
+		await this.write(next);
+		return {
+			document: next,
+			changed: true
+		};
+	}
+	async write(document) {
+		await this.store.writeText(SESSION_BINDINGS_FILE, stringify(document, { lineWidth: 0 }));
+	}
+};
 // src/assets.ts
 /**
 * The only reader of bundled assets. `apply()` performs no IO; the engine and
@@ -6717,6 +7029,17 @@ function briefStageFor(operation, stage) {
 	}
 }
 // src/engine/projections.ts
+/** One shared prompt template for `/novel resume` and the panel copy button. */
+function formatResumePrompt(input) {
+	return [
+		`请继续《${input.title}》。`,
+		`项目根：${input.root}（第一次工具调用必须显式传 project_root=${input.root}）。`,
+		`当前第 ${input.chapter} 章，阶段 ${input.stage}。`,
+		`下一步：${input.nextTool}。`,
+		"先调用 novel_status 核对项目根与书名，再按 novel_pipeline 的下一步执行；",
+		"只操作这个项目，不要读取或写入其他书。"
+	].join("\n");
+}
 const STAGE_TO_PHASE = {
 	idle: "P1",
 	P2: "P2",
@@ -6760,8 +7083,9 @@ function projectChapter(record) {
 }
 function projectSummary(snapshot) {
 	return {
-		schemaVersion: 3,
+		schemaVersion: 4,
 		panelId: PANEL_ID,
+		root: snapshot.root,
 		title: snapshot.title,
 		genre: snapshot.genre,
 		platform: snapshot.platform,
@@ -6803,20 +7127,260 @@ function projectChapters(snapshot) {
 		details: draft.details
 	});
 	return {
-		schemaVersion: 3,
+		schemaVersion: 4,
 		panelId: PANEL_ID,
 		rows
 	};
 }
 function projectGates(snapshot) {
 	return {
-		schemaVersion: 3,
+		schemaVersion: 4,
 		panelId: PANEL_ID,
 		stage: snapshot.stage,
 		blocking: snapshot.blocking,
 		explanations: snapshot.blocking.map((item) => `${item.code}${item.scope === void 0 ? "" : ` (${item.scope})`}: ${item.detail}`)
 	};
 }
+// src/engine/project-selection.ts
+const MAX_SCAN_CANDIDATES = 50;
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+/** Filesystem access failures are unreadable; parse/schema faults are damage. */
+const unreadableFsError = (error) => {
+	const code = error.code;
+	return typeof code === "string" && [
+		"EACCES",
+		"EPERM",
+		"EIO",
+		"EBUSY",
+		"ELOOP",
+		"EMFILE",
+		"ENFILE",
+		"EISDIR"
+	].includes(code);
+};
+/**
+* True when anything survives in the project directory besides novel.yaml.
+* Kept next to inspection so the panel, resolver and scanner agree on what
+* "a project used to be here" means.
+*/
+async function hasProjectState(store) {
+	const stateFiles = [
+		STATE_FILES.pipeline,
+		STATE_FILES.chapters,
+		STATE_FILES.characters,
+		STATE_FILES.world,
+		STATE_FILES.locks,
+		STATE_FILES.timeline,
+		STATE_FILES.foreshadows,
+		STATE_FILES.relationships,
+		STATE_FILES.handoff
+	].map((file) => joinRel(STATE_DIR, file));
+	stateFiles.push(joinRel(STATE_DIR, STATE_FILES.journal), ARCHIVE_DIGESTS_FILE, BRIEF_RECEIPTS_FILE);
+	return (await Promise.all(stateFiles.map((path) => store.exists(path)))).some(Boolean) || (await store.list("chapters")).length > 0 || (await store.list("plans")).length > 0 || (await store.list("reviews")).length > 0 || (await store.list("checks")).length > 0 || await store.exists("outline/outline.yaml") || await store.exists("outline/worldbook.yaml");
+}
+/**
+* Inspect one candidate without constructing a full Snapshot. `ok` and
+* `damaged` are both project evidence; only `not-project`/`missing` are absent.
+*/
+async function inspectProject(root) {
+	const absolute = resolve(root);
+	const store = new FsStore(absolute);
+	let directory;
+	try {
+		const info = await store.statRoot();
+		if (info === null) return {
+			root: absolute,
+			state: "missing",
+			title: "（项目目录不存在）"
+		};
+		directory = info.directory;
+	} catch (error) {
+		return {
+			root: absolute,
+			state: "unreadable",
+			title: "（项目目录不可读）",
+			error: errorText(error)
+		};
+	}
+	if (!directory) return {
+		root: absolute,
+		state: "not-project",
+		title: "（不是项目目录）"
+	};
+	let projectExists;
+	try {
+		projectExists = await store.exists(PROJECT_FILE);
+	} catch (error) {
+		return {
+			root: absolute,
+			state: "unreadable",
+			title: "（项目文件不可读）",
+			error: errorText(error)
+		};
+	}
+	if (projectExists) try {
+		const project = await store.readDoc(PROJECT_FILE, "project");
+		if (project === null) return {
+			root: absolute,
+			state: "damaged",
+			title: "（项目文件不可读）",
+			error: `${PROJECT_FILE} disappeared during inspection`
+		};
+		return {
+			root: absolute,
+			state: "ok",
+			title: typeof project.title === "string" ? project.title : "",
+			...typeof project.created_at === "string" && project.created_at !== "" ? { created_at: project.created_at } : {}
+		};
+	} catch (error) {
+		return {
+			root: absolute,
+			state: unreadableFsError(error) ? "unreadable" : "damaged",
+			title: "（项目文件不可读）",
+			error: errorText(error)
+		};
+	}
+	try {
+		if (await hasProjectState(store)) return {
+			root: absolute,
+			state: "damaged",
+			title: "（项目文件缺失）",
+			error: `${PROJECT_FILE} is missing`
+		};
+	} catch (error) {
+		return {
+			root: absolute,
+			state: "unreadable",
+			title: "（项目目录不可读）",
+			error: errorText(error)
+		};
+	}
+	return {
+		root: absolute,
+		state: "not-project",
+		title: "（不是项目）"
+	};
+}
+/**
+* Enumerate the finite workspace shape: cwd, cwd/novel and direct child
+* directories. No ancestor walk, no recursion, and no symlink directory is
+* followed. `truncated` is explicit rather than a silent 50-row cut.
+*/
+async function scanWorkspace(cwd, limit = MAX_SCAN_CANDIDATES) {
+	const base = resolve(cwd);
+	const store = new FsStore(base);
+	const roots = [base];
+	const add = (path) => {
+		const absolute = resolve(path);
+		if (!roots.includes(absolute)) roots.push(absolute);
+	};
+	try {
+		const novel = await store.lstat("novel");
+		if (novel !== null && novel.directory && !novel.symbolicLink) add(join(base, "novel"));
+		for (const entry of await store.entries(".")) {
+			if (!entry.directory || entry.symbolicLink) continue;
+			add(join(base, entry.name));
+		}
+	} catch {}
+	const bounded = Math.max(1, limit);
+	const candidates = [];
+	let truncated = false;
+	for (const root of roots) try {
+		const inspection = await inspectProject(root);
+		if (inspection.state === "not-project" || inspection.state === "missing") continue;
+		if (candidates.length >= bounded) {
+			truncated = true;
+			break;
+		}
+		candidates.push(inspection);
+	} catch (error) {
+		if (candidates.length >= bounded) {
+			truncated = true;
+			break;
+		}
+		candidates.push({
+			root,
+			state: "unreadable",
+			title: "（项目目录不可读）",
+			error: errorText(error)
+		});
+	}
+	return {
+		candidates,
+		truncated
+	};
+}
+/**
+* One/many/none classification with the §6.4 short-circuit order:
+* cwd itself, then cwd/novel, then exactly one readable direct child. Damaged
+* projects are not workspace discovery candidates; scan may still list them.
+*/
+async function discoverWorkspace(cwd) {
+	const base = resolve(cwd);
+	const direct = await inspectProject(base);
+	if (direct.state === "ok") return {
+		kind: "one",
+		root: direct.root
+	};
+	const store = new FsStore(base);
+	const nested = join(base, "novel");
+	try {
+		const info = await store.lstat("novel");
+		if (info !== null && info.directory && !info.symbolicLink) {
+			const candidate = await inspectProject(nested);
+			if (candidate.state === "ok") return {
+				kind: "one",
+				root: candidate.root
+			};
+		}
+	} catch {
+		return { kind: "none" };
+	}
+	const roots = [];
+	try {
+		for (const entry of await store.entries(".")) {
+			if (!entry.directory || entry.symbolicLink) continue;
+			const candidate = await inspectProject(join(base, entry.name)).catch(() => null);
+			if (candidate?.state !== "ok") continue;
+			roots.push(candidate.root);
+			if (roots.length > 50) break;
+		}
+	} catch {
+		return { kind: "none" };
+	}
+	if (roots.length === 0) return { kind: "none" };
+	if (roots.length === 1) return {
+		kind: "one",
+		root: roots[0]
+	};
+	return {
+		kind: "many",
+		roots
+	};
+}
+function describeCandidates(candidates) {
+	return candidates.map((candidate) => {
+		return `- ${candidate.title === void 0 || candidate.title === "" ? "（无标题）" : candidate.title}${candidate.state === void 0 ? "" : ` [${candidate.state}]`}: ${candidate.root}`;
+	}).join("\n");
+}
+function ambiguousError(candidates) {
+	const list = describeCandidates(candidates);
+	return new EngineInputError(ERROR_CODES.PROJECT_AMBIGUOUS, `multiple projects are available; choose one explicitly:\n${list}`, "pass project_root on the next tool call, or use /novel use <path|title>. The registry active project is not used as a silent default for an Agent session.");
+}
+function projectNotFoundError(root) {
+	return new EngineInputError(ERROR_CODES.PROJECT_NOT_FOUND, `no novel project at ${resolve(root)}`, "call novel_init to create one, pass the correct project_root, or run /novel scan to discover projects");
+}
+function missingProjectError(input) {
+	const title = input.lastTitle === void 0 || input.lastTitle === "" ? "" : `《${input.lastTitle}》`;
+	const moved = input.movedTo === void 0 ? "" : ` A project with the same created_at is registered at ${input.movedTo};`;
+	return new EngineFaultError(ERROR_CODES.PROJECT_MISSING, `the project ${title} bound to this session is missing: ${input.selection.root}.${moved} projects are never switched automatically`, `restore the directory or mount, then retry; or explicitly run /novel use <new path> or pass project_root. The binding is kept.${input.movedTo === void 0 ? "" : ` Candidate moved project: ${input.movedTo}.`}`, input.cause === void 0 ? void 0 : { cause: input.cause });
+}
+function identityMismatchError(input) {
+	const expected = input.selection.created_at ?? "（unknown）";
+	const actual = input.actualCreatedAt ?? "（unknown）";
+	const title = input.actualTitle === void 0 || input.actualTitle === "" ? "" : `《${input.actualTitle}》`;
+	return new EngineInputError(ERROR_CODES.PROJECT_IDENTITY_MISMATCH, `the path ${input.selection.root} now contains a different project ${title} (created_at ${actual}; this session is bound to ${expected})`, "the binding was not switched and no write was attempted. Run /novel use <path> or pass project_root to confirm the replacement; old bindings keep failing closed.");
+}
 // src/engine/state.ts
 /** A pipeline document for a brand-new project. */
 function emptyPipeline(patch) {
@@ -6925,7 +7489,7 @@ const STAGE_RANK = {
 	done: 7
 };
 /** Internal, journal-tracked archive idempotency ledger; not a user state doc. */
-const ARCHIVE_DIGESTS = joinRel(STATE_DIR, "archive-digests.json");
+const ARCHIVE_DIGESTS = ARCHIVE_DIGESTS_FILE;
 const LEDGER_PATHS = {
 	chapters: joinRel(STATE_DIR, STATE_FILES.chapters),
 	characters: joinRel(STATE_DIR, STATE_FILES.characters),
@@ -6963,8 +7527,8 @@ var EngineService = class {
 	briefContextCache = /* @__PURE__ */ new WeakMap();
 	briefs;
 	now;
-	/** The project this process last touched; the panel follows it without a workspace hint. */
-	lastRoot = null;
+	metadataMutex = new KeyedMutex();
+	callerContext = new AsyncLocalStorage();
 	constructor(config, rulepack, options = {}) {
 		this.config = config;
 		this.rulepackSource = typeof rulepack === "function" ? rulepack : () => rulepack;
@@ -6986,7 +7550,6 @@ var EngineService = class {
 		this.disposed = true;
 		this.stores.clear();
 		this.replay.clear();
-		this.lastRoot = null;
 		this.compiled = null;
 	}
 	get rulepack() {
@@ -6999,23 +7562,171 @@ var EngineService = class {
 	withSignal(signal, task) {
 		return this.signalContext.run(signal, task);
 	}
+	/** Bind the calling Agent session and cwd to every engine operation in `task`. */
+	withCaller(caller, task) {
+		return this.callerContext.run(caller, task);
+	}
+	caller() {
+		return this.callerContext.getStore();
+	}
 	/** The configured default project root. */
 	defaultRoot() {
 		return resolve(this.config.projectRoot);
 	}
+	/** Resolve a caller-supplied root against the session cwd, like /novel use. */
+	resolveProjectPath(root) {
+		const caller = this.caller();
+		return resolve(caller?.cwd ?? process.cwd(), root);
+	}
+	/** The resolved metadata directory; resolves relative config once per call. */
+	stateRoot() {
+		return this.config.stateDir === "" ? resolve(homedir(), ".dsh", "novel-write-engine") : resolve(this.config.stateDir);
+	}
+	stateStore() {
+		return new FsStore(this.stateRoot());
+	}
+	bindings() {
+		return new SessionBindings(this.stateStore(), { now: this.now });
+	}
 	/**
-	* Resolve an omitted root through the cross-project registry. The registry is
-	* convenience state, so a corrupt or unreadable registry falls back to the
-	* configured root instead of making every call fail.
+	* Serialize metadata read-modify-write across sessions and processes. The
+	* project manuscript lock is a different lock; a slow write never blocks a
+	* registry update.
 	*/
-	async resolveRoot(root) {
-		if (root !== void 0) return resolve(root);
-		if (this.lastRoot !== null) return this.lastRoot;
+	withMetadataLock(task) {
+		const directory = this.stateRoot();
+		return this.metadataMutex.run(directory, async () => {
+			ensureDirAt(directory);
+			const lock = new FileLock(join(directory, METADATA_LOCK_FILE));
+			try {
+				await lock.acquire();
+			} catch (error) {
+				if (error instanceof EngineFaultError && error.code === ERROR_CODES.LOCK_TIMEOUT) throw new EngineFaultError(ERROR_CODES.LOCK_TIMEOUT, "timed out waiting for the project metadata lock", "another DSH instance is writing project registration or session bindings; retry after it finishes", { cause: error });
+				throw error;
+			}
+			try {
+				return await task();
+			} finally {
+				await lock.release();
+			}
+		});
+	}
+	async inspectConfigRoot() {
 		try {
-			const document = await this.registry().read();
-			if (document.active !== null) return resolve(document.active);
-		} catch {}
-		return resolve(this.config.projectRoot);
+			const inspection = await inspectProject(this.defaultRoot());
+			return inspection.state === "ok" || inspection.state === "damaged" || inspection.state === "unreadable" ? inspection : null;
+		} catch (error) {
+			throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `cannot inspect the configured projectRoot ${this.defaultRoot()}: ${errorMessage(error)}`, "fix the configured path or permissions; no project was selected", { cause: error });
+		}
+	}
+	/**
+	* Resolve the four-layer choice: explicit, session binding, bounded workspace
+	* discovery, then registry/config defaults. There is deliberately no
+	* process-global "last project" layer.
+	*/
+	/** Doctor/guide may run before any project exists; that is not a failure. */
+	async resolveRootForInspection(root) {
+		let selection;
+		try {
+			selection = await this.resolveRoot(root);
+		} catch (error) {
+			if (root === void 0 && error instanceof EngineError && error.code === ERROR_CODES.PROJECT_NOT_FOUND) return {
+				root: this.defaultRoot(),
+				source: "config"
+			};
+			throw error;
+		}
+		if (root === void 0 && selection.source === "session") {
+			const inspection = await inspectProject(selection.root);
+			if (inspection.state === "missing") throw missingProjectError({
+				selection,
+				lastTitle: selection.title,
+				movedTo: await this.movedProjectHint(selection)
+			});
+			if (inspection.state === "not-project") throw projectNotFoundError(selection.root);
+			if (inspection.state === "unreadable") throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `the project bound to this session is unreadable: ${inspection.error ?? selection.root}`, "fix the directory permissions, or explicitly rebind with /novel use after the project is readable");
+		}
+		return selection;
+	}
+	async resolveRoot(root) {
+		if (root !== void 0) return {
+			root: this.resolveProjectPath(root),
+			source: "explicit"
+		};
+		const caller = this.caller();
+		if (caller?.sessionId !== void 0) {
+			const binding = await this.bindings().get(caller.sessionId);
+			if (binding !== void 0) return {
+				root: binding.root,
+				source: "session",
+				title: binding.title,
+				created_at: binding.project_created_at
+			};
+			if (caller.cwd !== void 0 && caller.cwd !== "") {
+				const found = await discoverWorkspace(caller.cwd);
+				if (found.kind === "one") return {
+					root: found.root,
+					source: "workspace"
+				};
+				if (found.kind === "many") throw ambiguousError(await Promise.all(found.roots.map(async (candidate) => {
+					const inspection = await inspectProject(candidate);
+					return {
+						root: inspection.root,
+						title: inspection.title,
+						state: inspection.state
+					};
+				})));
+			}
+		}
+		const document = await this.registry().read();
+		const candidates = document.projects.map((entry) => ({
+			root: entry.root,
+			title: entry.title
+		}));
+		const ambiguous = async () => {
+			return ambiguousError(await Promise.all(document.projects.map(async (entry) => {
+				const inspection = await inspectProject(entry.root).catch(() => null);
+				return {
+					root: entry.root,
+					title: entry.title,
+					...inspection === null ? {} : { state: inspection.state }
+				};
+			})));
+		};
+		if (caller?.sessionId !== void 0) {
+			if (candidates.length === 1) return {
+				root: candidates[0].root,
+				source: "single"
+			};
+			if (candidates.length > 1) throw await ambiguous();
+			const config = await this.inspectConfigRoot();
+			if (config !== null) {
+				if (config.state === "unreadable") throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `the configured projectRoot is unreadable: ${config.error ?? this.defaultRoot()}`, "fix the configured path or permissions");
+				return {
+					root: config.root,
+					source: "config"
+				};
+			}
+			throw projectNotFoundError(this.defaultRoot());
+		}
+		if (document.active !== null) return {
+			root: document.active,
+			source: "active"
+		};
+		const config = await this.inspectConfigRoot();
+		if (config !== null) {
+			if (config.state === "unreadable") throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `the configured projectRoot is unreadable: ${config.error ?? this.defaultRoot()}`, "fix the configured path or permissions");
+			return {
+				root: config.root,
+				source: "config"
+			};
+		}
+		if (candidates.length === 1) return {
+			root: candidates[0].root,
+			source: "single"
+		};
+		if (candidates.length > 1) throw await ambiguous();
+		throw projectNotFoundError(this.defaultRoot());
 	}
 	storeFor(root) {
 		const absolute = resolve(root ?? this.config.projectRoot);
@@ -7025,6 +7736,69 @@ var EngineService = class {
 		this.stores.set(absolute, store);
 		return store;
 	}
+	/** Persist one explicit choice for this DSH session. */
+	async bindSelection(root, title, projectCreatedAt, source) {
+		const caller = this.caller();
+		if (caller?.sessionId === void 0) return;
+		const existing = await this.bindings().get(caller.sessionId);
+		if (existing !== void 0 && existing.root === resolve(root) && existing.title === title && existing.project_created_at === projectCreatedAt) return;
+		await this.withMetadataLock(() => this.bindings().bind({
+			session_id: caller.sessionId,
+			root,
+			title,
+			project_created_at: projectCreatedAt,
+			source
+		}));
+	}
+	/**
+	* Best-effort discovery bookkeeping. A metadata failure must never turn a
+	* successful project read/write into a failure; the registry is convenience.
+	*/
+	async autoRegister(snapshot) {
+		if (snapshot.projectError !== null) return;
+		try {
+			const known = (await this.registry().read()).projects.find((entry) => entry.root === snapshot.root);
+			const sameRow = known !== void 0 && known.title === snapshot.project.title && (known.created_at ?? "") === (snapshot.project.created_at ?? "");
+			const differentIdentity = known !== void 0 && known.created_at !== void 0 && known.created_at !== "" && known.created_at !== snapshot.project.created_at;
+			if (sameRow || differentIdentity) return;
+			await this.withMetadataLock(async () => {
+				const lockedRegistry = this.registry();
+				const existing = (await lockedRegistry.read()).projects.find((entry) => entry.root === snapshot.root);
+				if (existing !== void 0) {
+					if (existing.created_at !== void 0 && existing.created_at !== "" && existing.created_at !== snapshot.project.created_at) return;
+					if (existing.title === snapshot.project.title && (existing.created_at ?? "") === (snapshot.project.created_at ?? "")) return;
+				}
+				await lockedRegistry.register({
+					root: snapshot.root,
+					title: snapshot.project.title,
+					created_at: snapshot.project.created_at
+				});
+			});
+		} catch {}
+	}
+	/** Record the session binding/registration implied by a successful selection. */
+	async recordSelection(selection, snapshot, options = {}) {
+		if (this.caller()?.sessionId === void 0) return;
+		if ((options.bind ?? (options.bindSource !== void 0 || selection.source === "explicit")) && snapshot.projectError === null) await this.bindSelection(snapshot.root, snapshot.project.title, snapshot.project.created_at, options.bindSource ?? "explicit");
+		if (options.register ?? (selection.source === "explicit" || selection.source === "workspace")) await this.autoRegister(snapshot);
+	}
+	/**
+	* Read paths may record convenience metadata, but a corrupt or read-only
+	* state directory must not turn a successful explicit-root read into a
+	* failure. Resolution without an explicit root still reads the binding
+	* fail-closed; writes use recordSelection directly and report a committed
+	* mutation with a warning if its metadata update fails.
+	*/
+	async recordSelectionBestEffort(selection, snapshot) {
+		try {
+			await this.recordSelection(selection, snapshot);
+		} catch {}
+	}
+	/** Registration/activation/use need a readable project identity. */
+	assertProjectHealthy(snapshot, operation) {
+		if (snapshot.projectError === null) return;
+		throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `${operation} requires a readable novel.yaml: ${snapshot.projectError}`, "repair the project definition with novel_status + novel_amend using an explicit project_root; the registry/binding was not changed");
+	}
 	async initProject(input) {
 		const title = typeof input.title === "string" ? input.title.trim() : "";
 		if (title === "") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "title must not be empty");
@@ -7043,10 +7817,16 @@ var EngineService = class {
 			const [min, max] = input.dialogue_ratio;
 			if (!Number.isFinite(min) || !Number.isFinite(max) || min < 0 || max > 1 || max < min) throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "dialogue_ratio must be [min, max] within 0..1 with min <= max");
 		}
-		return this.mutate({
-			root: input.root,
+		const selection = {
+			root: input.root === void 0 ? this.defaultRoot() : this.resolveProjectPath(input.root),
+			source: input.root === void 0 ? "config" : "explicit"
+		};
+		const result = await this.mutate({
+			selection,
 			op: "initProject",
-			key: () => `init:${resolve(input.root ?? this.config.projectRoot)}`,
+			bindOnSuccess: false,
+			registerOnSuccess: false,
+			key: () => `init:${selection.root}`,
 			run: async (_snapshot, context) => {
 				if (await context.store.exists("novel.yaml")) throw new EngineInputError(ERROR_CODES.PROJECT_EXISTS, `a project already exists at ${context.store.root}`, "use a different directory, or call novel_status to inspect the existing project");
 				const project = {
@@ -7145,6 +7925,20 @@ var EngineService = class {
 			},
 			emptyAllowed: true
 		});
+		const created = await this.loadAt({
+			root: result.data.root,
+			source: "explicit"
+		});
+		await this.autoRegister(created);
+		try {
+			await this.bindSelection(created.root, created.project.title, created.project.created_at, "init");
+		} catch (error) {
+			result.warnings.push({
+				code: "SESSION_BINDING_FAILED",
+				message: `project was created, but the session binding could not be written: ${errorMessage(error)}`
+			});
+		}
+		return result;
 	}
 	async submitBookPlan(input) {
 		const allowed = /* @__PURE__ */ new Set([
@@ -7848,7 +8642,14 @@ var EngineService = class {
 	async getStatus(input = {}) {
 		if (input.chapter !== void 0) this.assertChapterParameter(input.chapter);
 		const snapshot = await this.load(input.root);
-		const chapter = input.chapter ?? snapshot.pipeline.chapter;
+		return this.statusFor(snapshot, input.chapter ?? snapshot.pipeline.chapter);
+	}
+	/**
+	* Build a status report from an already-loaded snapshot. This deliberately
+	* has no selection side effect: read-only callers such as /novel resume must
+	* not register or bind the project just by reading it.
+	*/
+	async statusFor(snapshot, chapter) {
 		const metrics = await this.metricsFor(snapshot, chapter);
 		const journal = await this.journalBlocking(snapshot);
 		const next = journal.length > 0 && this.stateErrors(snapshot).length === 0 ? {
@@ -7870,6 +8671,10 @@ var EngineService = class {
 				rounds: { ...snapshot.pipeline.rounds },
 				blocking: [...this.effectiveBlocking(snapshot), ...journal],
 				state_errors: this.stateErrors(snapshot),
+				selection: {
+					source: snapshot.selection.source,
+					root: snapshot.selection.root
+				},
 				metrics,
 				...snapshot.handoff === null ? {} : (() => {
 					const position = projectHandoff(snapshot.handoff, snapshot.pipeline.chapter);
@@ -8262,13 +9067,14 @@ var EngineService = class {
 		};
 	}
 	async doctor(input = {}) {
-		const root = await this.resolveRoot(input.root);
+		const selection = await this.resolveRootForInspection(input.root);
+		const root = selection.root;
 		const store = this.storeFor(root);
 		const checks = [];
 		const add = (check) => {
 			checks.push(check);
 		};
-		if (!await store.exists("novel.yaml") && !await this.projectStateExists(store)) {
+		if (!await store.exists("novel.yaml") && !await hasProjectState(store)) {
 			add({
 				id: "project",
 				severity: "error",
@@ -8293,7 +9099,8 @@ var EngineService = class {
 		}
 		let snapshot;
 		try {
-			snapshot = await this.load(root);
+			snapshot = await this.loadAt(selection);
+			await this.recordSelectionBestEffort(selection, snapshot);
 		} catch (error) {
 			add({
 				id: "load",
@@ -8588,9 +9395,10 @@ var EngineService = class {
 		};
 	}
 	async guide(input = {}) {
-		const root = await this.resolveRoot(input.root);
+		const selection = await this.resolveRootForInspection(input.root);
+		const root = selection.root;
 		const store = this.storeFor(root);
-		if (!await store.exists("novel.yaml") && !await this.projectStateExists(store)) return {
+		if (!await store.exists("novel.yaml") && !await hasProjectState(store)) return {
 			data: buildGuide({
 				projectPresent: false,
 				chapter: 1,
@@ -8646,7 +9454,8 @@ var EngineService = class {
 			revision: 1,
 			warnings: []
 		};
-		const snapshot = await this.load(root);
+		const snapshot = await this.loadAt(selection);
+		await this.recordSelectionBestEffort(selection, snapshot);
 		const target = snapshot.project.targets.total_chapters;
 		const finished = snapshot.pipeline.stage === "done" && target !== null && snapshot.chapters.chapters.length >= target;
 		const journalBlocking = await this.journalBlocking(snapshot);
@@ -9615,7 +10424,8 @@ var EngineService = class {
 		if (typeof input.path !== "string" || input.path.trim() === "") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "amend path must be a non-empty string");
 		if (typeof input.reason !== "string" || input.reason.trim() === "") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "amend requires a reason");
 		if (typeof input.content !== "object" || input.content === null || Array.isArray(input.content)) throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "amend content must be an object");
-		const resolvedRoot = await this.resolveRoot(input.root);
+		const selection = await this.resolveRoot(input.root);
+		const resolvedRoot = selection.root;
 		const store = this.storeFor(resolvedRoot);
 		const absolute = store.path(input.path);
 		const kind = Object.hasOwn(MUTABLE_STATE, input.path) ? MUTABLE_STATE[input.path] : void 0;
@@ -9626,7 +10436,7 @@ var EngineService = class {
 			if (await this.stateDocIsUnreadable(store, path, docKind)) repairPaths.push(path);
 		}
 		return this.mutate({
-			root: resolvedRoot,
+			selection,
 			op: "amend",
 			reason: input.reason,
 			...repairPaths.length === 0 ? {} : { repairPaths },
@@ -9823,15 +10633,8 @@ var EngineService = class {
 		if (input.before !== void 0 && typeof input.before !== "string") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "diff before must be a string");
 		if (input.after !== void 0 && typeof input.after !== "string") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "diff after must be a string");
 		if (input.before !== void 0 && input.after !== void 0) {
-			let chapter = input.chapter;
-			let revision = 1;
-			if (chapter === void 0) try {
-				const snapshot = await this.load(input.root);
-				chapter = snapshot.pipeline.chapter;
-				revision = snapshot.pipeline.revision;
-			} catch {
-				chapter = 0;
-			}
+			const chapter = input.chapter ?? 0;
+			const revision = 1;
 			const report = diffLines(input.before, input.after);
 			return {
 				data: {
@@ -10088,13 +10891,155 @@ var EngineService = class {
 	async panelGates(input = {}) {
 		return projectGates(await this.panelSnapshot(input.root));
 	}
-	/** One snapshot, three projections: the panel never mixes revisions. */
+	/**
+	* Build the read-only panel payload. The query root is accepted only when it
+	* is registered, active or the configured root; arbitrary paths never reach
+	* the filesystem from the panel route.
+	*/
 	async panelBundle(input = {}) {
-		const snapshot = await this.panelSnapshot(input.root);
+		const registry = await this.registry().read();
+		const active = registry.active;
+		const rows = /* @__PURE__ */ new Map();
+		const add = (option) => {
+			if (!rows.has(option.root)) rows.set(option.root, option);
+		};
+		const optionFor = async (root, registered, fallbackTitle, expectedCreatedAt) => {
+			const inspection = await inspectProject(root);
+			const state = inspection.state === "ok" ? "ok" : inspection.state === "damaged" ? "damaged" : inspection.state === "unreadable" ? "unreadable" : "missing";
+			const sameIdentity = expectedCreatedAt === void 0 || expectedCreatedAt === "" || inspection.created_at === expectedCreatedAt;
+			const title = inspection.state === "ok" && inspection.title !== "" && sameIdentity ? inspection.title : fallbackTitle !== void 0 && fallbackTitle !== "" ? fallbackTitle : inspection.title;
+			return {
+				root: inspection.root,
+				title,
+				active: active === inspection.root,
+				registered,
+				state
+			};
+		};
+		for (const entry of registry.projects) add(await optionFor(entry.root, true, entry.title, entry.created_at));
+		if (active !== null && !rows.has(active)) {
+			const known = registry.projects.find((entry) => entry.root === active);
+			add(await optionFor(active, known !== void 0, known?.title, known?.created_at));
+		}
+		const configured = this.defaultRoot();
+		if (!rows.has(configured)) {
+			const option = await optionFor(configured, false);
+			if (option.state !== "missing" || active === configured) add(option);
+		}
+		const selectedRoot = input.root === void 0 ? void 0 : resolve(input.root);
+		if (selectedRoot !== void 0 && !rows.has(selectedRoot) && selectedRoot === configured) add(await optionFor(configured, false));
+		const projects = [...rows.values()].sort((left, right) => compareText(left.root, right.root));
+		let selection;
+		if (selectedRoot !== void 0) {
+			if (!rows.has(selectedRoot)) return {
+				projects,
+				selection: {
+					root: selectedRoot,
+					source: "query"
+				},
+				missing: {
+					root: selectedRoot,
+					title: "（未登记的项目）",
+					code: ERROR_CODES.PROJECT_NOT_FOUND,
+					reason: "not_registered",
+					hint: "用 /novel scan --register 或 /novel admin novel_registry_register 登记后刷新；面板不会读取任意路径。"
+				}
+			};
+			selection = {
+				root: selectedRoot,
+				source: "query"
+			};
+		} else if (active !== null) selection = {
+			root: active,
+			source: "active"
+		};
+		else if (registry.projects.length === 1) selection = {
+			root: registry.projects[0].root,
+			source: "single"
+		};
+		else if (rows.has(configured) && !registry.projects.some((entry) => entry.root === configured)) selection = {
+			root: configured,
+			source: "config"
+		};
+		else selection = {
+			root: null,
+			source: "none"
+		};
+		if (selection.root === null) return {
+			projects,
+			selection,
+			...projects.length === 0 ? {
+				empty: true,
+				error: "还没有项目：调用 novel_init 创建。"
+			} : {}
+		};
+		const option = rows.get(selection.root);
+		const inspection = await inspectProject(selection.root);
+		if (option.state === "missing" || option.state === "unreadable" || inspection.state === "not-project") return {
+			projects,
+			selection,
+			missing: {
+				root: selection.root,
+				title: option.title,
+				code: inspection.state === "not-project" ? ERROR_CODES.PROJECT_NOT_FOUND : ERROR_CODES.PROJECT_MISSING,
+				reason: inspection.state === "not-project" ? "not-project" : inspection.state === "unreadable" ? "unreadable" : "missing",
+				hint: inspection.state === "not-project" ? "目录存在，但没有 novel.yaml 或项目状态；请恢复项目定义，或改选其他项目。" : inspection.state === "unreadable" ? "目录不可读；请修复权限或 IO 错误后刷新，登记行和面板偏好会保留。" : "项目目录不在了；请恢复目录或挂载后刷新，登记行和面板偏好会保留。"
+			}
+		};
+		let snapshot;
+		try {
+			snapshot = await this.panelSnapshot(selection.root);
+		} catch (error) {
+			if (error instanceof EngineError && (error.code === ERROR_CODES.PROJECT_MISSING || error.code === ERROR_CODES.PROJECT_NOT_FOUND)) return {
+				projects,
+				selection,
+				missing: {
+					root: selection.root,
+					title: option.title,
+					code: error.code === ERROR_CODES.PROJECT_MISSING ? ERROR_CODES.PROJECT_MISSING : ERROR_CODES.PROJECT_NOT_FOUND,
+					reason: "missing",
+					hint: error.hint ?? "项目目录不在了；请恢复目录或挂载后刷新，登记行和面板偏好会保留。"
+				}
+			};
+			throw error;
+		}
+		const summary = projectSummary(snapshot);
+		const resume = summary.next === void 0 ? void 0 : { text: formatResumePrompt({
+			title: summary.title,
+			root: summary.root,
+			chapter: summary.chapter,
+			stage: summary.stage,
+			nextTool: summary.next.tool
+		}) };
 		return {
-			summary: projectSummary(snapshot),
+			projects,
+			selection,
+			summary,
 			chapters: projectChapters(snapshot),
-			gates: projectGates(snapshot)
+			gates: projectGates(snapshot),
+			...resume === void 0 ? {} : { resume }
+		};
+	}
+	/** Read-only resume text shared with the panel copy button. */
+	async resumePrompt(input = {}) {
+		if (this.caller()?.sessionId === void 0) throw new EngineInputError(ERROR_CODES.CONFIG_INVALID, "resume requires an Agent session", "run /novel resume from an Agent conversation");
+		const selection = await this.resolveRoot(input.root);
+		const snapshot = await this.loadAt(selection);
+		const status = await this.statusFor(snapshot, snapshot.pipeline.chapter);
+		const nextTool = status.data.next?.tool;
+		return {
+			data: {
+				text: nextTool === void 0 ? null : formatResumePrompt({
+					title: status.data.project.title,
+					root: status.data.project.root,
+					chapter: status.data.chapter,
+					stage: status.data.stage,
+					nextTool
+				}),
+				selection: status.data.selection
+			},
+			revision: status.revision,
+			warnings: []
 		};
 	}
 	async stats(input = {}) {
@@ -10123,42 +11068,287 @@ var EngineService = class {
 		};
 	}
 	registry() {
-		return new ProjectRegistry(new FsStore(this.config.stateDir === "" ? join(homedir(), ".dsh", "novel-write-engine") : this.config.stateDir));
+		return new ProjectRegistry(this.stateStore());
 	}
-	/** List known projects (convenience only; a project opens without a row). */
+	/** List known projects with a cheap directory state for the panel/command. */
 	async listProjects() {
 		const document = await this.registry().read();
+		const projects = await Promise.all(document.projects.map(async (entry) => {
+			const inspection = await inspectProject(entry.root);
+			const sameIdentity = entry.created_at === void 0 || entry.created_at === "" || inspection.created_at === entry.created_at;
+			return {
+				...entry,
+				...inspection.state === "ok" && inspection.title !== "" && sameIdentity ? { title: inspection.title } : {},
+				state: inspection.state
+			};
+		}));
 		return {
 			active: document.active,
-			projects: document.projects
+			projects
 		};
 	}
-	/** Record the current project in the registry. */
+	/**
+	* Record an explicit project row. An unchanged duplicate is a no-op; a path
+	* reused by another project updates the row and reports `replaced`.
+	*/
 	async registerProject(input = {}) {
-		const snapshot = await this.load(input.root);
-		const document = await this.registry().register({
-			root: snapshot.root,
-			title: snapshot.project.title
-		});
-		return {
-			active: document.active,
-			projects: document.projects
+		const selection = input.root === void 0 ? await this.resolveRoot(void 0) : {
+			root: this.resolveProjectPath(input.root),
+			source: "explicit"
 		};
+		const snapshot = await this.loadAt(selection);
+		this.assertProjectHealthy(snapshot, "novel_registry_register");
+		return this.withMetadataLock(async () => {
+			const registry = this.registry();
+			const document = await registry.read();
+			const previous = document.projects.find((entry) => entry.root === snapshot.root);
+			const replaced = previous !== void 0 && previous.created_at !== void 0 && previous.created_at !== "" && previous.created_at !== snapshot.project.created_at;
+			if (!replaced && previous !== void 0 && previous.title === snapshot.project.title && (previous.created_at ?? "") === (snapshot.project.created_at ?? "")) return {
+				active: document.active,
+				projects: document.projects,
+				replaced: false
+			};
+			const next = await registry.register({
+				root: snapshot.root,
+				title: snapshot.project.title,
+				created_at: snapshot.project.created_at
+			});
+			return {
+				active: next.active,
+				projects: next.projects,
+				replaced
+			};
+		});
 	}
-	/** Choose the default project for future convenience calls. */
+	/** Choose the panel/default project. This never binds the current session. */
 	async setActiveProject(input) {
-		const document = await this.registry().setActive(resolve(input.root));
-		this.lastRoot = document.active === null ? null : resolve(document.active);
-		return { active: document.active };
+		const selection = {
+			root: this.resolveProjectPath(input.root),
+			source: "explicit"
+		};
+		const snapshot = await this.loadAt(selection);
+		this.assertProjectHealthy(snapshot, "novel_registry_activate");
+		return this.withMetadataLock(async () => {
+			const registry = this.registry();
+			const previous = (await registry.read()).projects.find((entry) => entry.root === snapshot.root);
+			const replaced = previous !== void 0 && previous.created_at !== void 0 && previous.created_at !== "" && previous.created_at !== snapshot.project.created_at;
+			await registry.register({
+				root: snapshot.root,
+				title: snapshot.project.title,
+				created_at: snapshot.project.created_at
+			});
+			return {
+				active: (await registry.setActive(snapshot.root)).active,
+				replaced
+			};
+		});
 	}
-	/** Forget a registry row; the project directory is never touched. */
+	/** Forget a registry row; the project directory and bindings are never touched. */
 	async forgetProject(input) {
-		const document = await this.registry().forget(resolve(input.root));
-		if (this.lastRoot === resolve(input.root)) this.lastRoot = document.active === null ? null : resolve(document.active);
+		return this.withMetadataLock(async () => {
+			const document = await this.registry().forget(this.resolveProjectPath(input.root));
+			return {
+				active: document.active,
+				projects: document.projects
+			};
+		});
+	}
+	/**
+	* Bounded workspace scan. Normal mode is read-only; `register` updates only
+	* healthy, newly discovered rows, never active or session bindings.
+	*/
+	async scanProjects(input) {
+		const cwd = resolve(input.cwd);
+		const scan = await scanWorkspace(cwd);
+		const before = await this.registry().read();
+		const registeredRoots = new Set(before.projects.map((entry) => entry.root));
+		const candidates = scan.candidates.map((candidate) => ({
+			...candidate,
+			registered: registeredRoots.has(candidate.root)
+		}));
+		if (input.register !== true) return {
+			cwd,
+			candidates,
+			truncated: scan.truncated,
+			added: [],
+			already: [],
+			skipped: [],
+			identity_changed: []
+		};
+		const loaded = /* @__PURE__ */ new Map();
+		const skipped = [];
+		for (const candidate of candidates) {
+			if (candidate.state !== "ok") {
+				skipped.push({
+					root: candidate.root,
+					reason: candidate.state === "damaged" ? `damaged: ${candidate.error ?? "novel.yaml is missing/unreadable"}` : candidate.state === "unreadable" ? `unreadable: ${candidate.error ?? "permission or IO error"}` : `not a project (${candidate.state})`
+				});
+				continue;
+			}
+			if (registeredRoots.has(candidate.root)) continue;
+			try {
+				const snapshot = await this.loadAt({
+					root: candidate.root,
+					source: "explicit"
+				});
+				if (snapshot.projectError !== null) {
+					skipped.push({
+						root: candidate.root,
+						reason: `damaged: ${snapshot.projectError}`
+					});
+					continue;
+				}
+				loaded.set(candidate.root, snapshot);
+			} catch (error) {
+				skipped.push({
+					root: candidate.root,
+					reason: errorMessage(error)
+				});
+			}
+		}
+		const added = [];
+		const already = [];
+		const identityChanged = [];
+		await this.withMetadataLock(async () => {
+			const registry = this.registry();
+			const document = await registry.read();
+			for (const candidate of candidates) {
+				if (candidate.state !== "ok") continue;
+				const existing = document.projects.find((entry) => entry.root === candidate.root);
+				if (existing !== void 0) {
+					candidate.registered = true;
+					already.push(candidate.root);
+					const previousCreatedAt = existing.created_at ?? "";
+					const currentCreatedAt = candidate.created_at ?? "";
+					if (previousCreatedAt !== "" && previousCreatedAt !== currentCreatedAt) {
+						identityChanged.push(candidate.root);
+						candidate.identity_changed = true;
+						candidate.reason = "registered under a different created_at (or the replacement has none); not overwritten. Run explicit register/activate to confirm the replacement.";
+						continue;
+					}
+					if (candidate.title !== "" && (existing.title !== candidate.title || previousCreatedAt !== currentCreatedAt)) try {
+						await registry.register({
+							root: candidate.root,
+							title: candidate.title,
+							created_at: candidate.created_at
+						});
+					} catch (error) {
+						skipped.push({
+							root: candidate.root,
+							reason: `registry update failed: ${errorMessage(error)}`
+						});
+					}
+					continue;
+				}
+				const snapshot = loaded.get(candidate.root);
+				if (snapshot === void 0) continue;
+				try {
+					await registry.register({
+						root: snapshot.root,
+						title: snapshot.project.title,
+						created_at: snapshot.project.created_at
+					});
+					added.push(candidate.root);
+					candidate.registered = true;
+					candidate.title = snapshot.project.title;
+					candidate.created_at = snapshot.project.created_at;
+				} catch (error) {
+					skipped.push({
+						root: candidate.root,
+						reason: `registry write failed: ${errorMessage(error)}`
+					});
+				}
+			}
+		});
 		return {
-			active: document.active,
-			projects: document.projects
+			cwd,
+			candidates,
+			truncated: scan.truncated,
+			added,
+			already,
+			skipped,
+			identity_changed: identityChanged
+		};
+	}
+	/** Current session binding, or the inferred fallback when none is set. */
+	async currentProject() {
+		const caller = this.caller();
+		if (caller?.sessionId === void 0) throw new EngineInputError(ERROR_CODES.CONFIG_INVALID, "currentProject requires an Agent session", "run /novel current from an Agent conversation");
+		const binding = await this.bindings().get(caller.sessionId);
+		if (binding !== void 0) {
+			const inspection = await inspectProject(binding.root).catch(() => null);
+			return {
+				selection: {
+					root: binding.root,
+					source: "session",
+					title: binding.title,
+					created_at: binding.project_created_at
+				},
+				bound: true,
+				...inspection === null ? {} : { state: inspection.state }
+			};
+		}
+		try {
+			return {
+				selection: await this.resolveRoot(void 0),
+				bound: false
+			};
+		} catch (error) {
+			return {
+				selection: null,
+				bound: false,
+				error: errorMessage(error)
+			};
+		}
+	}
+	/** Explicitly switch this session; failure leaves the old binding untouched. */
+	async useProject(input) {
+		const caller = this.caller();
+		if (caller?.sessionId === void 0) throw new EngineInputError(ERROR_CODES.CONFIG_INVALID, "useProject requires an Agent session", "run /novel use from an Agent conversation");
+		const target = input.target.trim().replace(/^(["'])(.*)\1$/u, "$2");
+		if (target === "") throw new EngineInputError(ERROR_CODES.SCHEMA_INVALID, "use requires a path, title or \".\"");
+		let root;
+		if (target === ".") {
+			if (caller.cwd === void 0 || caller.cwd === "") throw new EngineInputError(ERROR_CODES.CONFIG_INVALID, "use \".\" requires a working directory", "run the command from a project workspace, or pass an explicit path");
+			const found = await discoverWorkspace(caller.cwd);
+			if (found.kind === "many") throw ambiguousError(found.roots.map((candidate) => ({ root: candidate })));
+			if (found.kind === "none") throw projectNotFoundError(caller.cwd);
+			root = found.root;
+		} else {
+			const candidate = resolve(caller.cwd ?? process.cwd(), target);
+			const inspection = await inspectProject(candidate).catch(() => null);
+			if (inspection !== null && inspection.state !== "not-project" && inspection.state !== "missing") root = candidate;
+			else {
+				const matches = (await this.registry().read()).projects.filter((entry) => entry.title === target);
+				if (matches.length > 1) throw new EngineInputError(ERROR_CODES.PROJECT_AMBIGUOUS, `multiple registered projects are named "${target}":\n${describeCandidates(matches)}`, "use the full project path instead of the title");
+				root = matches[0]?.root;
+			}
+		}
+		if (root === void 0) throw new EngineInputError(ERROR_CODES.PROJECT_NOT_FOUND, `no registered project or readable directory matches "${target}"`, "run /novel projects or /novel scan to see available projects");
+		const selection = {
+			root,
+			source: "explicit"
 		};
+		const snapshot = await this.loadAt(selection);
+		this.assertProjectHealthy(snapshot, "novel_use");
+		await this.bindSelection(snapshot.root, snapshot.project.title, snapshot.project.created_at, "command");
+		await this.autoRegister(snapshot);
+		return {
+			selection: {
+				root: snapshot.root,
+				source: "explicit",
+				title: snapshot.project.title,
+				created_at: snapshot.project.created_at
+			},
+			title: snapshot.project.title,
+			created_at: snapshot.project.created_at
+		};
+	}
+	/** Clear only this session's choice; never touches a project or registry row. */
+	async unbindProject() {
+		const caller = this.caller();
+		if (caller?.sessionId === void 0) throw new EngineInputError(ERROR_CODES.CONFIG_INVALID, "unbindProject requires an Agent session", "run /novel unbind from an Agent conversation");
+		return { cleared: (await this.withMetadataLock(() => this.bindings().clear(caller.sessionId))).changed };
 	}
 	/**
 	* Import one ledger from a settings pack. Always previews with a diff; a
@@ -10310,7 +11500,8 @@ var EngineService = class {
 		};
 	}
 	async panelSnapshot(root) {
-		const snapshot = await this.load(root);
+		const selection = await this.resolveRoot(root);
+		const snapshot = await this.loadAt(selection);
 		const archived = snapshot.chapters.chapters;
 		const archivedCurrent = archived.some((chapter) => chapter.num === snapshot.pipeline.chapter);
 		const target = snapshot.project.targets.total_chapters;
@@ -11161,22 +12352,6 @@ var EngineService = class {
 		this.assertChapterParameter(chapter);
 		if (chapter !== snapshot.pipeline.chapter) throw new EngineInputError(ERROR_CODES.STAGE_ORDER, `chapter ${chapter} is not the active chapter (${snapshot.pipeline.chapter})`, "archive the active chapter before starting the next one");
 	}
-	/** True when anything survives in the project directory besides novel.yaml. */
-	async projectStateExists(store) {
-		const stateFiles = [
-			STATE_FILES.pipeline,
-			STATE_FILES.chapters,
-			STATE_FILES.characters,
-			STATE_FILES.world,
-			STATE_FILES.locks,
-			STATE_FILES.timeline,
-			STATE_FILES.foreshadows,
-			STATE_FILES.relationships,
-			STATE_FILES.handoff
-		].map((file) => joinRel(STATE_DIR, file));
-		stateFiles.push(joinRel(STATE_DIR, STATE_FILES.journal), ARCHIVE_DIGESTS, BRIEF_RECEIPTS_FILE);
-		return (await Promise.all(stateFiles.map((path) => store.exists(path)))).some(Boolean) || (await store.list("chapters")).length > 0 || (await store.list("plans")).length > 0 || (await store.list("reviews")).length > 0 || (await store.list("checks")).length > 0 || await store.exists("outline/outline.yaml") || await store.exists("outline/worldbook.yaml");
-	}
 	/** A live writer lock makes a read-only snapshot potentially torn. */
 	async lockIsLive(store) {
 		const text = await store.readText(LOCK_FILE);
@@ -11187,8 +12362,34 @@ var EngineService = class {
 		const info = await store.stat(LOCK_FILE);
 		return info !== null && Date.now() - info.mtimeMs < 1e3;
 	}
-	async load(root, retries = 1, allowLock = false) {
-		const store = this.storeFor(await this.resolveRoot(root));
+	/** Resolve a selection, load it, then persist the explicit choice (best effort). */
+	async load(root) {
+		const selection = await this.resolveRoot(root);
+		const snapshot = await this.loadAt(selection);
+		await this.recordSelectionBestEffort(selection, snapshot);
+		return snapshot;
+	}
+	/** Load exactly one already-resolved selection; never writes a binding. */
+	async movedProjectHint(selection) {
+		if (selection.created_at === void 0 || selection.created_at === "") return void 0;
+		try {
+			return (await this.registry().read()).projects.find((entry) => entry.root !== selection.root && entry.created_at !== void 0 && entry.created_at === selection.created_at)?.root;
+		} catch {
+			return;
+		}
+	}
+	async loadAt(selection, retries = 1, allowLock = false) {
+		const store = this.storeFor(selection.root);
+		if (selection.source === "session") {
+			const inspection = await inspectProject(selection.root);
+			if (inspection.state === "missing") throw missingProjectError({
+				selection,
+				lastTitle: selection.title,
+				movedTo: await this.movedProjectHint(selection)
+			});
+			if (inspection.state === "not-project") throw projectNotFoundError(selection.root);
+			if (inspection.state === "unreadable") throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `the project bound to this session is unreadable: ${inspection.error ?? selection.root}`, "fix the directory permissions, or explicitly rebind with /novel use after the project is readable");
+		}
 		if (!allowLock && await this.lockIsLive(store)) {
 			for (let attempt = 0; attempt < 10; attempt += 1) {
 				await new Promise((resolve) => setTimeout(resolve, 25));
@@ -11197,10 +12398,17 @@ var EngineService = class {
 			if (await this.lockIsLive(store)) throw new EngineFaultError(ERROR_CODES.TXN_IN_PROGRESS, "a writer is changing this project; the read-only snapshot would be torn", "retry after the write finishes; do not interpret this snapshot as stable");
 		}
 		const projectExists = await store.exists(PROJECT_FILE);
-		if (!projectExists && !await this.projectStateExists(store)) throw new EngineInputError(ERROR_CODES.PROJECT_NOT_FOUND, `no novel project at ${store.root}`, "call novel_init to create one, or pass the correct project root");
+		if (!projectExists && !await hasProjectState(store)) {
+			if (selection.source === "session") throw missingProjectError({
+				selection,
+				lastTitle: selection.title
+			});
+			throw projectNotFoundError(store.root);
+		}
 		let project = {
 			...ENGINE_PROJECT_INITIAL,
-			title: "（项目文件不可读）"
+			title: "（项目文件不可读）",
+			created_at: ""
 		};
 		let projectError = projectExists ? null : `${PROJECT_FILE} is missing`;
 		if (projectExists) try {
@@ -11211,6 +12419,13 @@ var EngineService = class {
 			if (error instanceof EngineFaultError && (error.code === ERROR_CODES.SCHEMA_TOO_NEW || error.code === ERROR_CODES.PATH_ESCAPE)) throw error;
 			projectError = errorMessage(error);
 		}
+		if (projectError === null && selection.created_at !== void 0 && selection.created_at !== "") {
+			if (project.created_at === "" || project.created_at !== selection.created_at) throw identityMismatchError({
+				selection,
+				actualCreatedAt: project.created_at,
+				actualTitle: project.title
+			});
+		}
 		const pipeline = await store.readDoc(joinRel(STATE_DIR, STATE_FILES.pipeline), "pipeline");
 		if (pipeline === null) throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, "state/pipeline.yaml is missing");
 		let briefs = pipeline.briefs;
@@ -11347,16 +12562,16 @@ var EngineService = class {
 		if (check === null && checkError === null && pipeline.stage === "ready_to_archive") checkError = `${checkFile(chapter)} is missing`;
 		const latest = await store.readDoc(joinRel(STATE_DIR, STATE_FILES.pipeline), "pipeline");
 		if (latest === null || latest.revision !== pipeline.revision) {
-			if (retries > 0) return this.load(store.root, retries - 1, allowLock);
+			if (retries > 0) return this.loadAt(selection, retries - 1, allowLock);
 			throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, "the project changed while its snapshot was being read", "retry the read; if it keeps moving, wait for the writer to finish");
 		}
 		if (!allowLock && await this.lockIsLive(store)) {
-			if (retries > 0) return this.load(store.root, retries - 1, false);
+			if (retries > 0) return this.loadAt(selection, retries - 1, false);
 			throw new EngineFaultError(ERROR_CODES.TXN_IN_PROGRESS, "a writer started while the snapshot was being read; the snapshot is torn", "retry after the write finishes; do not interpret this snapshot as stable");
 		}
-		this.lastRoot = store.root;
 		return {
 			root: store.root,
+			selection,
 			project,
 			projectError,
 			pipeline,
@@ -11421,7 +12636,8 @@ var EngineService = class {
 		}
 	}
 	async mutate(options) {
-		const root = await this.resolveRoot(options.root);
+		const selection = options.selection ?? await this.resolveRoot(options.root);
+		const root = selection.root;
 		const signal = this.signalContext.getStore();
 		const abortIfNeeded = () => {
 			if (signal?.aborted === true) throw new EngineFaultError(ERROR_CODES.TXN_ABORTED, `${options.op} was aborted before commit`, "retry the call if you still want the write");
@@ -11430,9 +12646,24 @@ var EngineService = class {
 		return this.mutex.run(root, async () => {
 			if (options.emptyAllowed === true) ensureDirAt(root);
 			const store = this.storeFor(root);
+			if (options.emptyAllowed !== true && selection.source === "session") {
+				const inspection = await inspectProject(selection.root);
+				if (inspection.state === "missing") throw missingProjectError({
+					selection,
+					lastTitle: selection.title,
+					movedTo: await this.movedProjectHint(selection)
+				});
+				if (inspection.state === "not-project") throw projectNotFoundError(selection.root);
+				if (inspection.state === "unreadable") throw new EngineFaultError(ERROR_CODES.SCHEMA_INVALID, `the project bound to this session is unreadable: ${inspection.error ?? selection.root}`, "fix the directory permissions, or explicitly rebind with /novel use after the project is readable");
+				if (inspection.state === "damaged" && selection.created_at !== void 0 && selection.created_at !== "") throw identityMismatchError({
+					selection,
+					actualTitle: inspection.title
+				});
+			}
 			const journalPath = joinRel(STATE_DIR, STATE_FILES.journal);
 			const journalWasPresent = await store.exists(journalPath);
 			const projectExists = await store.exists(PROJECT_FILE);
+			if (options.emptyAllowed !== true && !projectExists && !await hasProjectState(store)) throw projectNotFoundError(root);
 			if (options.emptyAllowed === true && projectExists) throw new EngineInputError(ERROR_CODES.PROJECT_EXISTS, `a project already exists at ${store.root}`, "use a different directory, or call novel_status to inspect the existing project");
 			if (options.emptyAllowed !== true && projectExists && !await store.exists(joinRel("state", STATE_FILES.journal))) throw new EngineFaultError(ERROR_CODES.JOURNAL_MISSING, "state/journal.jsonl is missing; journal integrity and crash recovery are unavailable", "restore state/journal.jsonl from a backup before writing; a project with novel.yaml must have its audit journal");
 			const lock = new FileLock(join(root, LOCK_FILE), void 0, void 0, async (record) => {
@@ -11466,7 +12697,7 @@ var EngineService = class {
 						const stateCandidates = journalWasPresent ? stateFiles : stateFiles.filter((path) => path !== joinRel(STATE_DIR, STATE_FILES.journal));
 						if ((await Promise.all(stateCandidates.map((file) => store.exists(file)))).some(Boolean) || (await store.list("chapters")).length > 0 || (await store.list("plans")).length > 0 || (await store.list("reviews")).length > 0 || (await store.list("checks")).length > 0 || await store.exists("outline/outline.yaml") || await store.exists("outline/worldbook.yaml")) throw new EngineInputError(ERROR_CODES.PROJECT_EXISTS, "state documents exist but novel.yaml is missing; refusing to overwrite the project", "restore novel.yaml, or initialize a new empty directory");
 						await assertJournalConsistent(store);
-						const created = await options.run(this.emptySnapshot(root), {
+						const created = await options.run(this.emptySnapshot(root, selection), {
 							store,
 							revision: 1
 						});
@@ -11481,7 +12712,6 @@ var EngineService = class {
 							...options.reason === void 0 ? {} : { reason: options.reason }
 						});
 						this.replay.clear();
-						this.lastRoot = root;
 						return {
 							data: created.data,
 							revision: 1,
@@ -11490,7 +12720,11 @@ var EngineService = class {
 					}
 				}
 				await assertJournalConsistent(store, options.repairPaths ?? []);
-				const snapshot = await this.load(root, 1, true);
+				const snapshot = await this.loadAt(selection, 1, true);
+				if (selection.source === "session" && selection.created_at !== void 0 && selection.created_at !== "" && snapshot.projectError !== null) throw identityMismatchError({
+					selection,
+					actualTitle: snapshot.project.title
+				});
 				const key = options.key?.(snapshot);
 				if (key !== void 0) {
 					const cached = this.replay.get(`${root}|${options.op}|${key}`);
@@ -11549,6 +12783,21 @@ var EngineService = class {
 					revision,
 					warnings: outcome.warnings ?? []
 				};
+				let metadataSnapshot = snapshot;
+				if ((options.bindOnSuccess !== false || options.registerOnSuccess !== false) && outcome.files.some((file) => file.path === "novel.yaml")) try {
+					metadataSnapshot = await this.loadAt(selection, 1, true);
+				} catch {}
+				try {
+					await this.recordSelection(selection, metadataSnapshot, {
+						bind: options.bindOnSuccess,
+						register: options.registerOnSuccess
+					});
+				} catch (error) {
+					result.warnings.push({
+						code: "SESSION_BINDING_FAILED",
+						message: `project write committed, but project selection metadata could not be written: ${errorMessage(error)}`
+					});
+				}
 				if (key !== void 0) {
 					this.invalidateReplay(root, options.op);
 					this.replay.set(`${root}|${options.op}|${key}`, result);
@@ -11568,9 +12817,10 @@ var EngineService = class {
 			if (contentChanging || !key.includes("|export|")) this.replay.delete(key);
 		}
 	}
-	emptySnapshot(root) {
+	emptySnapshot(root, selection) {
 		return {
 			root,
+			selection,
 			project: { ...ENGINE_PROJECT_INITIAL },
 			projectError: null,
 			pipeline: emptyPipeline({
@@ -12308,10 +13558,17 @@ const fail = (error) => {
 	}
 	throw error;
 };
-/** Wrap an execute body with cancellation and a machine-code error. */
-const makeGuarded = (engine) => (body) => async (args, exec) => {
+/** Wrap an execute body with caller context, cancellation and a machine-code error. */
+const makeGuarded = (engine, workingDirectory) => (body) => async (args, exec) => {
+	const caller = {};
+	if (typeof exec?.agent?.id === "string" && exec.agent.id !== "") caller.sessionId = exec.agent.id;
+	if (exec?.agent !== void 0 && workingDirectory !== void 0) try {
+		caller.cwd = await workingDirectory.ensure(exec.agent, exec.signal);
+	} catch {}
 	try {
-		return await engine.withSignal(exec?.signal, () => body(args));
+		const invoke = () => engine.withSignal(exec?.signal, () => body(args));
+		const withCaller = engine.withCaller;
+		return await (typeof withCaller === "function" ? withCaller.call(engine, caller, invoke) : invoke());
 	} catch (error) {
 		return fail(error);
 	}
@@ -12360,14 +13617,22 @@ const stringArray = {
 };
 const root = {
 	type: "string",
-	description: "Project root. When omitted, resolves to the last active project, then the registry active root, then the configured projectRoot; pass it explicitly when several projects exist."
+	description: "Project root. Passing it selects this project for the current session and persists the choice. When omitted: session binding -> unique project in the workspace -> single registered project -> configured projectRoot -> error. Multiple projects require an explicit choice."
+};
+const initRoot = {
+	type: "string",
+	description: "Project root for the new project. Passing it creates the project there. When omitted, only the configured projectRoot is used; novel_init does not follow the session binding, workspace discovery or registry active. The created project is bound to the current session on success."
+};
+const utilityRoot = {
+	type: "string",
+	description: "Project root for the project-backed mode of this tool. Text-only word_count/diff calls ignore it and do not create a session binding; use a project-backed call when you want to select a book."
 };
 /**
 * The twenty-eight tools are thin adapters: narrow parameters, call one service
 * operation, render the canonical value. They never read a file.
 */
-function createNovelTools(engine) {
-	const guarded = makeGuarded(engine);
+function createNovelTools(engine, options = {}) {
+	const guarded = makeGuarded(engine, options.workingDirectory);
 	return [
 		defineTool({
 			name: "novel_init",
@@ -12406,7 +13671,7 @@ function createNovelTools(engine) {
 				selling_points: stringArray,
 				ending: { type: "string" },
 				strict_outline: { type: "boolean" },
-				project_root: root
+				project_root: initRoot
 			},
 			output: jsonOutput,
 			execute: guarded(async (args) => engine.initProject({
@@ -12444,6 +13709,7 @@ function createNovelTools(engine) {
 					const where = active === value.chapter ? `第 ${value.chapter} 章` : `当前第 ${active} 章 · 查询第 ${value.chapter} 章字数`;
 					return text([
 						`《${value.project.title}》 ${where} · ${value.stage}`,
+						...value.selection === void 0 ? [] : [`项目根 ${value.selection.root} · 选择来源 ${value.selection.source}`],
 						...value.rounds === void 0 ? [] : [`轮次：评审 ${value.rounds.review} / 修订 ${value.rounds.revise} / 校验 ${value.rounds.check}`],
 						value.blocking.length === 0 ? "门控：全部通过" : `门控：${value.blocking.length} 条阻塞`,
 						...value.blocking.map((item) => `  - ${item.code}: ${item.detail}`),
@@ -12755,7 +14021,7 @@ function createNovelTools(engine) {
 			parameters: {
 				text: { type: "string" },
 				chapter: { type: "integer" },
-				project_root: root
+				project_root: utilityRoot
 			},
 			output: jsonOutput,
 			execute: guarded(async (args) => engine.countWords({
@@ -12893,7 +14159,7 @@ function createNovelTools(engine) {
 				chapter: { type: "integer" },
 				before: { type: "string" },
 				after: { type: "string" },
-				project_root: root
+				project_root: utilityRoot
 			},
 			output: jsonOutput,
 			execute: guarded(async (args) => engine.diff({
@@ -13260,8 +14526,21 @@ const OPERATIONS$1 = {
 	novel_reopen: (engine, args) => engine.reopenChapter(args),
 	novel_restore: (engine, args) => engine.restoreBackup(args),
 	novel_registry_list: (engine) => engine.listProjects(),
-	novel_registry_register: (engine, args) => engine.registerProject({ root: rootArg(args) }),
-	novel_registry_activate: (engine, args) => engine.setActiveProject({ root: rootArg(args) }),
+	novel_registry_register: async (engine, args) => {
+		const result = await engine.registerProject({ root: rootArg(args) });
+		return {
+			...result,
+			...result.replaced ? { message: "原路径已换成另一本书；登记行已更新。已有会话绑定仍会按 created_at 拒绝，请重新 /novel use。" } : {}
+		};
+	},
+	novel_registry_activate: async (engine, args) => {
+		const result = await engine.setActiveProject({ root: rootArg(args) });
+		return {
+			...result,
+			message: "active 只影响面板默认；当前会话没有切换。写作请用 /novel use 或显式 project_root。",
+			...result.replaced ? { replacement: "原路径已换成另一本书；登记行已更新，旧会话绑定仍需重新 /novel use。" } : {}
+		};
+	},
 	novel_registry_forget: (engine, args) => engine.forgetProject({ root: rootArg(args) }),
 	novel_import: (engine, args) => engine.importPack(args)
 };
@@ -13328,6 +14607,7 @@ const statusText = async (engine) => {
 	return [
 		`《${data.project.title}》 ${data.project.genre} · ${data.project.platform}`,
 		`第 ${data.chapter} 章 · 阶段 ${data.stage}`,
+		...data.selection === void 0 ? [] : [`项目根 ${data.selection.root} · 选择来源 ${data.selection.source}`],
 		`轮次 评审 ${data.rounds.review} / 修订 ${data.rounds.revise} / 校验 ${data.rounds.check}`,
 		data.metrics === null ? "字数 —" : `字数 ${data.metrics.total_word_count}（汉字 ${data.metrics.cjk_chars} + 标点 ${data.metrics.punctuation_chars}，含标点）`,
 		data.blocking.length === 0 ? "门控 全部通过" : `门控 ${data.blocking.length} 条阻塞：`,
@@ -13346,6 +14626,12 @@ const usage = () => [
 	"/novel doctor        项目体检",
 	"/novel search <词>   搜索正文/大纲/世界观/台账",
 	"/novel export md|txt|epub|outline|worldbook|proposal",
+	"/novel projects      列出项目与目录状态",
+	"/novel current       当前会话绑定与选择来源",
+	"/novel use <path|title|.>  切换当前会话项目",
+	"/novel unbind        清除当前会话绑定（不删项目）",
+	"/novel scan [--register]   扫描工作区候选",
+	"/novel resume        输出可粘贴的续写指令",
 	"/novel admin         隐藏操作与参数说明",
 	"/novel admin <op> <json>  执行隐藏操作",
 	"/novel-next          等价于 /novel next",
@@ -13353,9 +14639,10 @@ const usage = () => [
 	"/novel-export <kind>",
 	"/novel-admin [<op> <json>]"
 ].join("\n");
-/** The five slash commands; every one calls a service operation, none touches a file. */
-function createCommands(engine) {
-	const dispatch = async (raw, signal) => {
+/** Every command calls a service operation; none touches a file directly. */
+function createCommands(engine, host = {}) {
+	const dispatch = async (invocation) => {
+		const { rawInput: raw, signal } = invocation;
 		if (signal.aborted) return bad("已取消");
 		const [head = "", ...rest] = raw.trim().split(/\s+/).filter((part) => part !== "");
 		try {
@@ -13429,6 +14716,78 @@ function createCommands(engine) {
 					const { data } = await engine.export({ kind });
 					return ok(`已导出 ${data.kind}：${data.files.join(", ")}`);
 				}
+				case "projects": {
+					const list = await engine.listProjects();
+					let current;
+					try {
+						const selection = await engine.currentProject();
+						current = selection.bound ? selection.selection?.root : void 0;
+					} catch {}
+					const lines = [
+						`项目 ${list.projects.length} 个${list.active === null ? "" : ` · 面板默认 ${list.active}`}`,
+						...list.projects.map((project) => {
+							const marks = [
+								...project.root === current ? ["*"] : [],
+								...project.root === list.active ? ["P"] : [],
+								...project.state === "ok" ? [] : ["!"]
+							].join("");
+							const state = project.state === "ok" ? "" : ` [${project.state}]`;
+							return `${marks === "" ? "  " : marks} 《${project.title}》 — ${project.root}${state}`;
+						}),
+						"* 当前会话 · P 面板默认 · ! 目录缺失/待修复"
+					];
+					return ok(lines.join("\n"));
+				}
+				case "current": {
+					const current = await engine.currentProject();
+					if (current.selection === null) return ok(`当前会话未绑定；也没有可唯一推导的项目。${current.error === void 0 ? "" : `\n${current.error}`}\n运行 /novel use <path|title|.> 选择项目。`);
+					return ok(current.bound ? [
+						`当前会话绑定《${current.selection.title ?? ""}》${current.state === void 0 || current.state === "ok" ? "" : ` [${current.state}]`}`,
+						`项目根 ${current.selection.root}`,
+						...current.state === "missing" ? ["项目目录不在了；绑定保留，恢复目录后可继续，或 /novel unbind 后重选。"] : current.state === "not-project" ? ["目录存在，但没有 novel.yaml 或项目状态；请恢复项目定义或重新选择。"] : current.state === "damaged" ? ["项目定义不可读；先用显式 project_root 的 novel_amend 修复。"] : current.state === "unreadable" ? ["项目目录不可读；修复权限或 IO 错误后再试。"] : []
+					].join("\n") : `当前会话未绑定；将按 ${current.selection.source} 推导到 ${current.selection.root}\n要固定选择，运行 /novel use ${current.selection.root}`);
+				}
+				case "use": {
+					const target = raw.trim().slice(3).trim();
+					if (target === "") return bad("用法：/novel use <path|title|.>");
+					const result = await engine.useProject({ target });
+					return ok(`当前会话已切换到《${result.title}》\n项目根 ${result.selection.root}\n面板 active 未改变；后续工具调用会默认使用这本书。`);
+				}
+				case "unbind": {
+					const result = await engine.unbindProject();
+					return ok(result.cleared ? "已清除当前会话绑定；项目和注册表未改动。" : "当前会话没有绑定；项目和注册表未改动。");
+				}
+				case "scan": {
+					const flags = rest.filter((part) => part.startsWith("--"));
+					const positional = rest.filter((part) => !part.startsWith("--"));
+					if (flags.filter((flag) => flag !== "--register").length > 0 || positional.length > 0) return bad("用法：/novel scan [--register]；scan 不接受路径参数");
+					const cwd = invocation.cwd;
+					if (cwd === void 0 || cwd === "") return bad("请在项目工作区中执行 /novel scan");
+					const register = flags.includes("--register");
+					const result = await engine.scanProjects({
+						cwd,
+						register
+					});
+					const lines = [`扫描到 ${result.candidates.length} 个候选；${result.candidates.filter((row) => row.registered).length} 个已登记${result.truncated ? "（只显示前 50 个，请缩小工作区）" : ""}`, ...result.candidates.map((candidate) => {
+						const state = candidate.state === "ok" ? "" : ` [${candidate.state}]`;
+						const registered = candidate.registered ? " 已登记" : "";
+						const identity = candidate.identity_changed === true ? " ! identity_changed" : "";
+						return `- 《${candidate.title}》 — ${candidate.root}${state}${registered}${identity}`;
+					})];
+					if (result.candidates.length === 0) lines.push("未发现项目；检查当前目录，或用 novel_init 创建第一本书。");
+					if (register) {
+						lines.push(`登记结果：新增 ${result.added.length} · 已存在 ${result.already.length} · 跳过 ${result.skipped.length}`);
+						if (result.identity_changed.length > 0) lines.push(`identity_changed：${result.identity_changed.join(", ")}；这些行没有被覆盖，请用显式 register/activate 确认替换。`);
+						for (const skipped of result.skipped) lines.push(`跳过 ${skipped.root}：${skipped.reason}`);
+						lines.push("登记不等于选择，写作请用 /novel use 或 project_root。");
+					}
+					return ok(lines.join("\n"));
+				}
+				case "resume": {
+					const { data } = await engine.resumePrompt({});
+					if (data.text === null) return bad("当前项目没有可续写的下一步；先用 /novel status 查看项目状态。");
+					return ok(data.text);
+				}
 				case "admin": {
 					if (rest.length === 0) return ok(adminHelp());
 					const text = raw.trim();
@@ -13445,12 +14804,27 @@ function createCommands(engine) {
 			return failure(error);
 		}
 	};
+	const withInvocation = async (invocation, task) => {
+		const caller = {};
+		if (typeof invocation.agent?.id === "string" && invocation.agent.id !== "") caller.sessionId = invocation.agent.id;
+		if (invocation.cwd !== void 0 && invocation.cwd !== "") caller.cwd = invocation.cwd;
+		else if (invocation.agent !== void 0 && host.workingDirectory !== void 0) try {
+			caller.cwd = await host.workingDirectory.ensure(invocation.agent, invocation.signal);
+		} catch {}
+		const enriched = {
+			...invocation,
+			...caller.cwd === void 0 ? {} : { cwd: caller.cwd }
+		};
+		const run = () => task(enriched);
+		const withCaller = engine.withCaller;
+		return typeof withCaller === "function" ? withCaller.call(engine, caller, run) : run();
+	};
 	return [
 		{
 			name: "novel",
 			description: "Novel engine: status, next step, stats, export and admin help.",
-			input: { hint: "[status|next|stats|export <kind>|admin]" },
-			handler: (invocation) => dispatch(invocation.rawInput, invocation.signal)
+			input: { hint: "[status|next|stats|projects|current|use|unbind|scan|resume|export <kind>|admin]" },
+			handler: (invocation) => dispatch(invocation)
 		},
 		{
 			name: "novel-next",
@@ -13519,7 +14893,10 @@ function createCommands(engine) {
 				}
 			}
 		}
-	];
+	].map((command) => ({
+		...command,
+		handler: (invocation) => withInvocation(invocation, command.handler)
+	}));
 }
 // src/skills/index.ts
 /** Read once at module load; `apply()` itself performs no IO. */
@@ -13535,13 +14912,22 @@ function createSkill() {
 	};
 }
 // src/remote/index.ts
-/** Build the payload from one synchronized snapshot of the project. */
-async function panelPayload(engine) {
+/** Build the payload for one optional panel query root. */
+async function panelPayload(engine, root) {
 	return {
-		schemaVersion: 3,
-		...await engine.panelBundle()
+		...await engine.panelBundle(root === void 0 ? {} : { root }),
+		schemaVersion: 4
 	};
 }
+const queryRoot = (url) => {
+	if (url === void 0 || url === "") return void 0;
+	try {
+		const value = new URL(url, "http://panel.local").searchParams.get("root");
+		return value === null || value.trim() === "" ? void 0 : value;
+	} catch {
+		return;
+	}
+};
 const denyAll = () => 503;
 const rejectionText = {
 	401: "unauthorized",
@@ -13568,7 +14954,7 @@ function panelHandler(engine, guard = denyAll) {
 			return;
 		}
 		try {
-			const payload = await panelPayload(engine);
+			const payload = await panelPayload(engine, queryRoot(request.url));
 			const body = method === "HEAD" ? "" : JSON.stringify(payload);
 			response.statusCode = 200;
 			response.setHeader("content-type", "application/json; charset=utf-8");
@@ -13580,7 +14966,12 @@ function panelHandler(engine, guard = denyAll) {
 				response.setHeader("content-type", "application/json; charset=utf-8");
 				response.setHeader("cache-control", "no-store");
 				response.end(JSON.stringify({
-					schemaVersion: 3,
+					schemaVersion: 4,
+					projects: [],
+					selection: {
+						root: null,
+						source: "none"
+					},
 					error: "还没有项目：调用 novel_init 创建。",
 					empty: true
 				}));
@@ -13590,7 +14981,12 @@ function panelHandler(engine, guard = denyAll) {
 			response.setHeader("content-type", "application/json; charset=utf-8");
 			response.setHeader("cache-control", "no-store");
 			response.end(JSON.stringify({
-				schemaVersion: 3,
+				schemaVersion: 4,
+				projects: [],
+				selection: {
+					root: null,
+					source: "none"
+				},
 				error: error instanceof Error ? error.message : String(error)
 			}));
 		}
@@ -14071,13 +15467,15 @@ function apply(ctx, config) {
 	const engine = new EngineService(engineConfig, () => loadRulepack(), { onEvent: emit });
 	ctx.effect(() => () => engine.dispose(), `${name}: engine dispose`);
 	ctx.provide?.("novelEngine", engine);
-	for (const tool of createNovelTools(engine)) {
+	const serviceOf = ctx.get;
+	const workingDirectory = typeof serviceOf === "function" ? serviceOf.call(ctx, "workingDirectory") : void 0;
+	for (const tool of createNovelTools(engine, { workingDirectory })) {
 		if (toolsMode === "core" && !CORE_TOOLS.includes(tool.name)) continue;
 		ctx.tools.register(tool);
 	}
 	const optional = ctx;
 	optional.inject(["commands"], (commandsCtx) => {
-		for (const command of createCommands(engine)) commandsCtx.effect(() => commandsCtx.commands.register(command), `${name}: command ${command.name}`);
+		for (const command of createCommands(engine, { workingDirectory })) commandsCtx.effect(() => commandsCtx.commands.register(command), `${name}: command ${command.name}`);
 	});
 	optional.inject(["skills"], (skillsCtx) => {
 		skillsCtx.effect(() => skillsCtx.skills.register(createSkill()), `${name}: entry skill`);
@@ -14111,4 +15509,4 @@ function connectionFence(scope) {
 	}
 	if (Object.prototype.hasOwnProperty.call(candidate, "connection")) return candidate.connection;
 }
-export { BriefLibrary, Config, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, GENRES, OPERATIONS, PLATFORMS, SCENE_TYPES, SCHEMA_VERSION, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, verifyReference };
+export { ARCHIVE_DIGESTS_FILE, BACKUP_DIR, BRIEF_RECEIPTS_FILE, BriefLibrary, CHAPTERS_DIR, CHECK_DIR, CORE_TOOLS, Config, DEFAULT_GENRE, DEFAULT_PLATFORM, ERROR_CODES, EXPORT_DIR, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, GENRES, HISTORY_DIR, HISTORY_KINDS, INITIAL_STAGE, LIMITS, LOCK_FILE, METADATA_LOCK_FILE, OPERATIONS, OUTLINE_DIR, OUTLINE_FILE, PANEL_CHAPTER_LIMIT, PANEL_ID, PANEL_ROUTE, PHASE_STRIP, PLAN_DIR, PLATFORMS, PLUGIN_NAME, PROJECT_FILE, REGISTRY_FILE, REMOTE_VERSION, REVIEW_DIR, SCENE_TYPES, SCENE_TYPE_DEFAULT, SCHEMA_VERSION, SESSION_BINDINGS_FILE, SKILL_NAME, STAGING_DIR, STATE_DIR, STATE_FILES, TOOL_NAMES, WORLDBOOK_FILE, applicableGates, apply, blockedError, briefStageFor, chapterFile, chapterHeading, chapterHistoryFile, checkFile, checkHistoryFile, deprecatedChapterFile, deprecatedHistoryFile, evaluateGates, faultError, formatResumePrompt, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, planChapterFile, planHistoryFile, planWorldFile, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, reviewFile, reviewHistoryFile, verifyReference };