fix(harness): scope settings discovery to sessions; boot reads the us…

…er layer only `Settings.load`'s `hostDir` is a session property by contract, but boot and `reload` passed the process's own `hostCwd` to it. That made the process behave like a session anchored at its launch directory: the project-layer discovery walk climbs ancestors, so a `.codework/` found anywhere above the launch directory silently configured the process -- a server started in /var/usr could pick up a stranger's project settings. - Boot and `rebuild` now load the user layer and the explicit override only; project plugins still arrive at a session's first exchange through `follow`'s union, and survive reloads through retained origins. - `--user-config-dir` is pre-resolved at the harness boundary: `~` expands to home and a relative spelling resolves against `hostCwd`, so a session `hostDir` can never move the override's anchor. - `hostCwd` doc corrected: it is the process-level directory (sandbox default, `.npmrc`/parse fallback, override base), not a project-settings root. - The resolve-only boot invariant moves to the user layer: an unresolvable user-layer entry still fails startup rather than fetching; a project-layer entry is now its session's drift report, not a process-level failure. - Tests pin a launch inside a project's subtree never importing its plugin (import side-effect sentinel), project entries surfacing as session drift, and relative `--user-config-dir` resolving against `hostCwd` with a different session `hostDir`.
sanchitrk · Sep 22, 2026 · Sep 17, 2026 · Sep 18, 2026 · Sep 19, 2026 · Sep 19, 2026
commit f53066598931936d0284502b40887d26e198f111
diff --git a/packages/harness/src/effect/harness.ts b/packages/harness/src/effect/harness.ts
@@ -4,7 +4,7 @@ import { Control } from "../control.ts";
 import { Database } from "../db/db.ts";
 import { Event } from "../event/event.ts";
 import { Global } from "../global.ts";
-import { fileSystem } from "../host.ts";
+import { fileSystem, hostPath } from "../host.ts";
 import { EventRegistry } from "../event/registry.ts";
 import { follow, load, type Origin, type PluginRef, type Pool } from "../plugin/catalog.ts";
 import { anchor } from "../plugin/loader.ts";
@@ -25,6 +25,7 @@ import { SessionRuntime } from "../session/runtime.ts";
 import type { Info as SettingsInfo } from "../settings/schema.ts";
 import { Settings } from "../settings/settings.ts";
 import { State } from "../state/state.ts";
+import { expandTilde } from "../util/home.ts";
 
 export interface Options {
 	/**
@@ -35,9 +36,10 @@ export interface Options {
 	readonly plugins?: ReadonlyArray<PluginRef>;
 	readonly database?: string;
 	/**
-	 * The host directory the project settings layer is discovered from. Defaults to the OS
-	 * process's directory; a test or an embedder that runs somewhere other than where it wants
-	 * settings read from passes its own, rather than inheriting whatever launched the process.
+	 * The process-level host directory: the default sandbox mount, the `.npmrc`/parse fallback
+	 * for plugin references no file declared, and the base a relative `--user-config-dir`
+	 * resolves against. Defaults to the OS process's directory. It is never a project-settings
+	 * root -- that discovery belongs to a session's `hostDir`.
 	 */
 	readonly hostCwd?: string;
 	readonly home?: string;
@@ -56,15 +58,23 @@ export const layer = (options: Options = {}) =>
 			// can quietly fall back to the OS process's directory when it meant a session's mount.
 			const hostCwd = options.hostCwd ?? process.cwd();
 			const global = Global.layerWith(paths);
-			const settingsOptions = options.userConfigDir === undefined ? {} : { userConfigDir: options.userConfigDir };
+			// `--user-config-dir` is a process-level flag: `~` expands to the user's home, and a
+			// relative spelling resolves against the process's own directory. A session's
+			// `hostDir` has no claim on it.
+			const settingsOptions =
+				options.userConfigDir === undefined
+					? {}
+					: { userConfigDir: hostPath.resolve(hostCwd, expandTilde(options.userConfigDir, hostPath)) };
 			// Settings are read once here because the plugin selection has to be prepared before
-			// any layer that depends on it; every later read goes through `Settings.Service`,
-			// which discovers from the session's own `hostDir` rather than from this one.
+			// any layer that depends on it; every later read goes through `Settings.Service`.
 			//
-			// This read happens before any session exists, so the process's directory is the only
-			// root available -- and the right one: it is what decides which plugins this process
-			// loads at all. Which of them a given session *runs* is the per-session question.
-			const config = yield* Settings.load({ ...settingsOptions, home: paths.home, hostDir: hostCwd });
+			// No `hostDir` is passed: that parameter is a property of a session, and a process
+			// has none. Boot reads the user layer and the explicit override only -- a server can
+			// start anywhere, so it must never walk ancestors of the directory it happened to
+			// launch in for a `.codework/`, which would hand it a stranger's project settings.
+			// A project's plugins still load: lazily, at the session's first exchange, through
+			// `follow`.
+			const config = yield* Settings.load({ ...settingsOptions, home: paths.home });
 			/*
 			 * Which entries this process configures from, per exchange.
 			 *
@@ -148,9 +158,10 @@ export const layer = (options: Options = {}) =>
 			const rebuild = () =>
 				Effect.gen(function* () {
 					reloads += 1;
-					// Re-read from the same root this process booted with, so the rebuilt pool
-					// holds what the old one did plus whatever was added since.
-					const current = yield* Settings.load({ ...settingsOptions, home: paths.home, hostDir: hostCwd });
+					// Re-read the process's layers -- the user layer and the explicit override, as
+					// at boot. Project layers belong to sessions and come back through the
+					// retained origins below, never through a process-level discovery walk.
+					const current = yield* Settings.load({ ...settingsOptions, home: paths.home });
 					const loaded = yield* Ref.get(pool);
 					// Reload is process-wide. Include modules discovered lazily from every linked
 					// session, not only the project the server happened to start in.

diff --git a/packages/harness/test/plugin.passes.test.ts b/packages/harness/test/plugin.passes.test.ts
@@ -1,7 +1,7 @@
 import "./utils/env.ts";
 import { Effect, Option } from "effect";
 import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vite-plus/test";
@@ -465,10 +465,12 @@ describe("a running session and the store", () => {
 });
 
 describe("boot", () => {
-	it("reports a configured plugin whose bytes are missing, rather than fetching it", () =>
+	it("fails on a user-layer plugin whose bytes are missing, rather than fetching it", () =>
 		withProject(async ({ root, project }) => {
+			// The user layer is the process's own selection: an entry it cannot resolve fails the
+			// boot, never a fetch.
 			await writeFile(
-				join(project, ".codework", "settings.jsonc"),
+				join(root, "home", "settings.jsonc"),
 				JSON.stringify({ plugins: ["@acme/never-published-anywhere"] }),
 			);
 
@@ -489,6 +491,155 @@ describe("boot", () => {
 			// that puts bytes on disk, and this is the error that names it.
 			expect(failure).toMatchObject({ _tag: "PluginStoreError", reason: "plugin-not-installed" });
 		}));
+
+	it("leaves a project-layer entry to its session -- boot does not see it", () =>
+		withProject(async ({ root, project }) => {
+			await writeFile(
+				join(project, ".codework", "settings.jsonc"),
+				JSON.stringify({ plugins: ["@acme/never-published-anywhere"] }),
+			);
+
+			// The process starts in the project but reads no project layer: boot succeeds, and the
+			// entry is the session's drift report -- a warning at its exchange, not a startup
+			// failure and never a fetch.
+			const prompts: string[] = [];
+			const open = immediateOpen();
+			await Effect.runPromise(
+				Effect.gen(function* () {
+					const session = yield* Session.create({ directory: project, hostDir: project });
+					yield* session.prompt({ text: "go", delivery: "followUp" });
+					yield* session.resume();
+					yield* session.wait();
+				}).pipe(
+					Effect.provide(
+						Harness.layer({
+							home: join(root, "home"),
+							hostCwd: project,
+							database: ":memory:",
+							llm: (request, signal) => {
+								prompts.push(request.context.systemPrompt ?? "");
+								return open(request, signal);
+							},
+						}),
+					),
+					Effect.scoped,
+					Effect.timeout("20 seconds"),
+					Effect.orDie,
+				),
+			);
+			expect(prompts).toHaveLength(1);
+		}));
+
+	it("does not read a `.codework` found above the directory the process started in", () =>
+		withProject(async ({ root, project }) => {
+			// `project` holds the marker; the process launches from deep inside it, the way an
+			// installed binary in /var/usr would. Its ancestors must not configure the process.
+			const bin = join(project, "var", "usr", "bin");
+			await mkdir(bin, { recursive: true });
+			const sentinel = join(root, "imported.sentinel");
+			const module = join(project, "marker.mjs");
+			// A prompt marker alone would not prove the point: a boot that loaded the module into
+			// the process pool would still leave it out of this session's selection. The import
+			// side effect is the observation that matters -- if boot ever evaluates the module,
+			// the sentinel exists.
+			await writeFile(
+				module,
+				[
+					`import { writeFileSync } from "node:fs";`,
+					`writeFileSync(${JSON.stringify(sentinel)}, "loaded");`,
+					"export default {",
+					"  id: 'acme.prompt.marker',",
+					"  kind: 'prompt',",
+					"  setup: (ctx) => ctx.plugin.prompt.set(`${ctx.plugin.prompt.get() ?? ''}marker`),",
+					"};",
+				].join("\n"),
+			);
+			await writeFile(join(project, ".codework", "settings.jsonc"), JSON.stringify({ plugins: [module] }));
+
+			// A session in a plain directory gets only the user layer: nothing of the startup
+			// directory's project leaks into either the boot pool or the exchange.
+			const plain = join(root, "plain");
+			await mkdir(plain);
+			const prompts: string[] = [];
+			const open = immediateOpen();
+			await Effect.runPromise(
+				Effect.gen(function* () {
+					const session = yield* Session.create({ directory: plain, hostDir: plain });
+					yield* session.prompt({ text: "go", delivery: "followUp" });
+					yield* session.resume();
+					yield* session.wait();
+				}).pipe(
+					Effect.provide(
+						Harness.layer({
+							home: join(root, "home"),
+							hostCwd: bin,
+							database: ":memory:",
+							llm: (request, signal) => {
+								prompts.push(request.context.systemPrompt ?? "");
+								return open(request, signal);
+							},
+						}),
+					),
+					Effect.scoped,
+					Effect.timeout("20 seconds"),
+					Effect.orDie,
+				),
+			);
+			expect(prompts).toHaveLength(1);
+			expect(prompts[0]).not.toContain("marker");
+			await expect(access(sentinel)).rejects.toThrow();
+		}));
+
+	it("resolves a relative --user-config-dir against the process directory, not the session's", () =>
+		withProject(async ({ root, project }) => {
+			// The process launches from `launch`; the override is `<launch>/myconf`. The session
+			// anchors at `project`, a different directory entirely -- if the flag resolved
+			// against the session's host, `project/myconf` would be read instead and the plugin
+			// would never appear.
+			const launch = join(root, "launch");
+			const custom = join(launch, "myconf");
+			await mkdir(custom, { recursive: true });
+			const module = join(root, "confplugin.mjs");
+			await writeFile(
+				module,
+				[
+					"export default {",
+					"  id: 'acme.prompt.conf',",
+					"  kind: 'prompt',",
+					"  setup: (ctx) => ctx.plugin.prompt.set(`${ctx.plugin.prompt.get() ?? ''}conf`),",
+					"};",
+				].join("\n"),
+			);
+			await writeFile(join(custom, "settings.jsonc"), JSON.stringify({ plugins: [module] }));
+
+			const prompts: string[] = [];
+			const open = immediateOpen();
+			await Effect.runPromise(
+				Effect.gen(function* () {
+					const session = yield* Session.create({ directory: project, hostDir: project });
+					yield* session.prompt({ text: "go", delivery: "followUp" });
+					yield* session.resume();
+					yield* session.wait();
+				}).pipe(
+					Effect.provide(
+						Harness.layer({
+							home: join(root, "home"),
+							hostCwd: launch,
+							userConfigDir: "myconf",
+							database: ":memory:",
+							llm: (request, signal) => {
+								prompts.push(request.context.systemPrompt ?? "");
+								return open(request, signal);
+							},
+						}),
+					),
+					Effect.scoped,
+					Effect.timeout("20 seconds"),
+					Effect.orDie,
+				),
+			);
+			expect(prompts[0]?.endsWith("conf")).toBe(true);
+		}));
 });
 
 describe("reload", () => {
@@ -698,23 +849,25 @@ describe("reload", () => {
 								: Effect.void,
 						);
 
-						// The boot load ran before `listen` attached, so the first notice is the reload's
-						// re-import -- a changed module instance is what `loaded` reports.
-						yield* state.reload;
+						// A project plugin is not a boot plugin: it loads at the session's first
+						// exchange, through `follow`'s union -- that is the `loaded` notice.
+						yield* run();
 						// The plugin leaves settings and its file is gone: the next rebuild drops the
 						// retained origin rather than failing on it.
 						yield* Effect.promise(() => writeFile(settings, JSON.stringify({ plugins: [] })));
 						yield* Effect.promise(() => rm(file));
 						yield* state.reload;
-						// Back in settings, but the module cannot be imported now.
-						yield* Effect.promise(() => writeFile(settings, JSON.stringify({ plugins: [file] })));
-						yield* Effect.promise(() => writeFile(file, "export default { nope: true };"));
+						// A process-level failure names no session: the broken entry sits in the user
+						// layer, which is the only layer `reload` reads.
+						const broken = join(project, "broken.mjs");
+						yield* Effect.promise(() =>
+							writeFile(join(root, "home", "settings.jsonc"), JSON.stringify({ plugins: [broken] })),
+						);
+						yield* Effect.promise(() => writeFile(broken, "export default { nope: true };"));
 						yield* state.reload;
 						// An exchange failure on a path the module registry has never seen names
-						// the session that ran it; a `reload` failure belongs to no session.
-						const broken = join(project, "broken.mjs");
+						// the session that ran it.
 						yield* Effect.promise(() => writeFile(settings, JSON.stringify({ plugins: [broken] })));
-						yield* Effect.promise(() => writeFile(broken, "export default { nope: true };"));
 						yield* run().pipe(Effect.ignore);
 
 						expect(seen.map((event) => event.status)).toEqual(["loaded", "dropped", "failed", "failed"]);
@@ -724,7 +877,8 @@ describe("reload", () => {
 						expect(seen[3]?.sessionId).toBeDefined();
 					}),
 			});
-			expect(prompts.length).toBe(0);
+			// The first exchange's lazy load ran the plugin: its marker made the prompt.
+			expect(prompts[0]?.endsWith("before")).toBe(true);
 		}));
 });