pi-squire 0.10.0 → 0.12.0

package/src/tmux.ts

@@ -2,6 +2,8 @@
 // fake. This client talks to tmux with `execFile` and no shell.
 import { execFile } from "node:child_process";
 
+import type { WindowPlacement } from "./window-placement.ts";
+
 /** One window to open: its name, working directory, command and environment. */
 export type WindowSpec = {
 	name: string;
@@ -10,8 +12,41 @@ export type WindowSpec = {
 	env: Readonly<Record<string, string>>;
 };
 
-/** One window as tmux lists it: its id, its name, and whether the program in its pane has exited. */
-export type TmuxWindow = { id: string; name: string; exited: boolean };
+/** One window as tmux lists it: its id, its session's name, its name, and whether the program in its pane has exited. */
+export type TmuxWindow = { id: string; session: string; name: string; exited: boolean };
+
+/** A window just opened: its id and the name of the session it is in, when known. */
+export type OpenedWindow = { id: string; session: string | undefined };
+
+/** The oldest tmux delegate windows need: `new-session -e` and `display-popup` arrived in 3.2. */
+export const MIN_TMUX = { major: 3, minor: 2 } as const;
+
+export type TmuxVersion = { text: string; major: number; minor: number };
+
+/** Parse `tmux -V` output such as `tmux 3.7b` or `tmux next-3.4`; a build with no number (`tmux master`) counts as current. */
+export function parseTmuxVersion(output: string): TmuxVersion {
+	const text = output.trim();
+	const match = /(\d+)\.(\d+)/.exec(text);
+	if (match === null) return { text, major: Number.POSITIVE_INFINITY, minor: 0 };
+	return { text, major: Number(match[1]), minor: Number(match[2]) };
+}
+
+/** Refuse a tmux older than `MIN_TMUX`, naming the version found. */
+export async function requireTmuxVersion(tmux: { version(): Promise<TmuxVersion> }): Promise<void> {
+	const found = await tmux.version();
+	if (found.major < MIN_TMUX.major || (found.major === MIN_TMUX.major && found.minor < MIN_TMUX.minor)) {
+		throw new Error(`delegate windows need tmux ${MIN_TMUX.major}.${MIN_TMUX.minor} or later; this is ${found.text}`);
+	}
+}
+
+/**
+ * The companion session for a parent in `parentSession`: its own when that is
+ * a companion session (marked by pi-squire when it made it), else the name
+ * plus `-squire`. The name alone says nothing: a user's session may end in it.
+ */
+export function companionName(parentSession: string, isCompanion: boolean): string {
+	return isCompanion ? parentSession : `${parentSession}-squire`;
+}
 
 /**
  * Why a window could not be opened, and whether one may exist anyway:
@@ -19,7 +54,7 @@ export type TmuxWindow = { id: string; name: string; exited: boolean };
  * Anything else, a timeout or a malformed answer included, is `unknown`.
  */
 export class WindowOpenError extends Error {
-	readonly certainty: "not-opened" | "unknown";
+	certainty: "not-opened" | "unknown";
 	constructor(message: string, certainty: "not-opened" | "unknown") {
 		super(message);
 		this.name = "WindowOpenError";
@@ -30,8 +65,14 @@ export class WindowOpenError extends Error {
 export interface TmuxClient {
 	/** Whether this process runs in a tmux pane. */
 	insideTmux(): boolean;
-	/** Open a detached window and return its id (for example `@3`). */
-	openWindow(spec: WindowSpec): Promise<string>;
+	/** The tmux version, asked once. */
+	version(): Promise<TmuxVersion>;
+	/**
+	 * Open a detached window and return its id (for example `@3`) and session.
+	 * `current` opens it in the parent's session; `companion` in
+	 * `<parent's session>-squire`, created when it does not exist.
+	 */
+	openWindow(spec: WindowSpec, placement: WindowPlacement): Promise<OpenedWindow>;
 	/** Every window on the server, in one tmux call. */
 	listWindows(): Promise<TmuxWindow[]>;
 	/** Kill a window. */
@@ -56,59 +97,142 @@ function runTmux(args: string[], timeout: number): Promise<string> {
 	});
 }
 
+type Run = (args: string[]) => Promise<string>;
+type Parent = { id: string; name: string; companion: boolean };
+
+/** The user option that marks a session pi-squire made for delegate windows. */
+const COMPANION_OPTION = "@squire-companion";
+
+/** The id, name and companion mark of the session the pane in `TMUX_PANE` belongs to, when known. */
+async function parentSession(run: Run): Promise<Parent | undefined> {
+	const pane = process.env.TMUX_PANE;
+	if (pane === undefined || pane === "") return undefined;
+	// Only the line's terminator goes: trailing spaces are legal in a session name.
+	const format = `#{session_id}\t#{${COMPANION_OPTION}}\t#{session_name}`;
+	const out = (await run(["display-message", "-p", "-t", pane, "-F", format])).replace(/\r?\n$/, "");
+	// The name comes last, so it is whatever follows the second tab.
+	const [id, marker, ...name] = out.split("\t");
+	return id.trim() === "" ? undefined : { id: id.trim(), name: name.join("\t"), companion: marker === "1" };
+}
+
+const envArgs = (spec: WindowSpec): string[] =>
+	Object.entries(spec.env).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+
+/** Dispatch one create; after dispatch even an error or timeout may have left a window. */
+async function create(run: Run, args: string[]): Promise<string> {
+	let out: string;
+	try {
+		out = await run(args);
+	} catch (err) {
+		throw new WindowOpenError((err as Error).message, "unknown");
+	}
+	const windowId = out.trim();
+	if (!/^@[0-9]+$/.test(windowId)) throw new WindowOpenError("tmux reported an invalid window id", "unknown");
+	return windowId;
+}
+
+const failedWith = (err: unknown, text: string): boolean =>
+	err instanceof WindowOpenError && err.message.includes(text);
+
 /**
- * The real client. A window is opened in the session of the pane in
- * `TMUX_PANE`, not in whatever session a client happens to have attached, so
- * it works with several clients on one server.
+ * Open a window in the companion session: `new-window`, then on a missing
+ * session one `new-session` that makes the delegate its first window and sets
+ * `detach-on-destroy off` and the companion mark on that session only, then `new-window` again when
+ * another launch created the session first.
+ */
+async function openCompanion(run: Run, spec: WindowSpec, session: string): Promise<string> {
+	const newWindow = [
+		"new-window",
+		"-d",
+		"-P",
+		"-F",
+		"#{window_id}",
+		"-n",
+		spec.name,
+		"-c",
+		spec.cwd,
+		...envArgs(spec),
+		"-t",
+		`=${session}:`,
+		"--",
+		...spec.argv,
+	];
+	try {
+		return await create(run, newWindow);
+	} catch (err) {
+		// tmux resolves the target before it creates anything, so nothing was dispatched that could create a window.
+		if (!failedWith(err, "can't find session")) throw err;
+		(err as WindowOpenError).certainty = "not-opened";
+	}
+	const newSession = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+	newSession.push("-P", "-F", "#{window_id}", "--", ...spec.argv);
+	newSession.push(";", "set-option", "-t", `=${session}:`, "detach-on-destroy", "off");
+	newSession.push(";", "set-option", "-t", `=${session}:`, COMPANION_OPTION, "1");
+	try {
+		return await create(run, newSession);
+	} catch (err) {
+		if (!failedWith(err, "duplicate session")) throw err;
+	}
+	return create(run, newWindow);
+}
+
+/** Open a window in the parent's own session, as delegates always did. */
+function openCurrent(run: Run, spec: WindowSpec, parent: Parent | undefined): Promise<string> {
+	const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
+	if (parent !== undefined) args.push("-t", parent.id);
+	args.push("--", ...spec.argv);
+	return create(run, args);
+}
+
+/**
+ * The real client. A window is opened relative to the session of the pane in
+ * `TMUX_PANE`, not whatever session a client happens to have attached, so it
+ * works with several clients on one server.
  */
 export function createTmuxClient(options: { timeoutMs?: number } = {}): TmuxClient {
 	const timeoutMs = options.timeoutMs ?? 10_000;
-	const run = (args: string[]) => runTmux(args, timeoutMs);
-
-	/** The id of the session this pane belongs to, when known. */
-	async function targetSession(): Promise<string | undefined> {
-		const pane = process.env.TMUX_PANE;
-		if (pane === undefined || pane === "") return undefined;
-		const sessionId = (await run(["display-message", "-p", "-t", pane, "-F", "#{session_id}"])).trim();
-		return sessionId === "" ? undefined : sessionId;
-	}
+	const run: Run = (args) => runTmux(args, timeoutMs);
+	let cachedVersion: Promise<TmuxVersion> | undefined;
 
 	return {
 		insideTmux: () => (process.env.TMUX ?? "") !== "",
 
-		async openWindow(spec) {
-			const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd];
-			for (const [key, value] of Object.entries(spec.env)) args.push("-e", `${key}=${value}`);
-			let session: string | undefined;
+		version() {
+			// The in-flight ask is shared; a failed one is forgotten so the next call asks again.
+			cachedVersion ??= run(["-V"]).then(parseTmuxVersion, (err: unknown) => {
+				cachedVersion = undefined;
+				throw err;
+			});
+			return cachedVersion;
+		},
+
+		async openWindow(spec, placement) {
+			let parent: Parent | undefined;
 			try {
-				session = await targetSession();
+				parent = await parentSession(run);
 			} catch (err) {
 				// The lookup only reads; no window can exist yet.
 				throw new WindowOpenError((err as Error).message, "not-opened");
 			}
-			if (session !== undefined) args.push("-t", session);
-			args.push("--", ...spec.argv);
-			let out: string;
-			try {
-				out = await run(args);
-			} catch (err) {
-				// After dispatch even an error or timeout may have left a window.
-				throw new WindowOpenError((err as Error).message, "unknown");
+			const known = parent === undefined || parent.name === "" ? undefined : parent.name;
+			if (placement === "current") return { id: await openCurrent(run, spec, parent), session: known };
+			if (known === undefined) {
+				throw new WindowOpenError("could not tell which tmux session this pane is in (TMUX_PANE)", "not-opened");
 			}
-			const windowId = out.trim();
-			if (!/^@[0-9]+$/.test(windowId)) throw new WindowOpenError("tmux reported an invalid window id", "unknown");
-			return windowId;
+			const session = companionName(known, parent?.companion === true);
+			return { id: await openCompanion(run, spec, session), session };
 		},
 
 		async listWindows() {
-			// The name goes last: it is the one field that could hold a tab.
-			const out = await run(["list-windows", "-a", "-F", "#{window_id}\t#{pane_dead}\t#{window_name}"]);
+			// The window name goes last: it is the one field that could hold a tab.
+			const format = "#{window_id}\t#{pane_dead}\t#{session_name}\t#{window_name}";
+			const out = await run(["list-windows", "-a", "-F", format]);
 			return out
 				.split("\n")
 				.filter((line) => line.trim() !== "")
 				.map((line) => {
-					const [id, dead, ...name] = line.split("\t");
-					return { id, name: name.join("\t"), exited: dead === "1" };
+					const [id, dead, session, ...name] = line.split("\t");
+					return { id, session, name: name.join("\t"), exited: dead === "1" };
 				});
 		},
 

package/src/tracking-text.ts

@@ -0,0 +1,41 @@
+// How `delegation_status` words a delegation's state, auto-exit and age.
+import type { DelegationState, StartedRecorded } from "./results.ts";
+
+/** Records from before auto-exit existed kept their windows open, so they read off. */
+export function autoExitLine(record: StartedRecorded): string {
+	return record.autoExit === true
+		? "on — the delegate closes its window after a normal completion unless the user took over there"
+		: "off — the window stays open after the result";
+}
+
+/** The state, worded for the `state:` line. */
+export function stateLine(state: DelegationState, record: StartedRecorded): string {
+	switch (state) {
+		case "running":
+			return "running — the window is open and no result has arrived";
+		case "gone":
+			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
+		case "done":
+			return `done — result status: ${record.result?.status ?? "unknown"}; the result reaches this session as a [delegate] message on its own`;
+		case "closed":
+			return "closed — delegation_close recorded it";
+		case "window-closed":
+			return "closed — the window is gone";
+		case "unknown":
+			return "unknown — tmux could not be asked whether the window is open";
+		case "planned":
+		case "created":
+		case "rolled-back":
+		case "retained":
+		case "interrupted":
+			return `${state} — no window id/start was recorded; a window may still exist`;
+	}
+}
+
+/** How long ago, worded for the `state:` line: `just now`, `N min ago` or `N h M min ago`. */
+export function ago(ms: number): string {
+	const minutes = Math.floor(ms / 60_000);
+	if (minutes < 1) return "just now";
+	if (minutes < 60) return `${minutes} min ago`;
+	return `${Math.floor(minutes / 60)} h ${minutes % 60} min ago`;
+}

package/src/tracking.ts

@@ -18,12 +18,14 @@ import {
 	type Results,
 	recordedName,
 	type StartedRecorded,
+	sessionIdOf,
 	type WindowState,
 	type WorkspaceAttempt,
 } from "./results.ts";
 import { inspectWorkspace, type WorkspaceSnapshot, WorkspaceSnapshotSchema } from "./snapshot.ts";
 import type { TmuxClient, TmuxWindow } from "./tmux.ts";
 import { AttemptSchema } from "./tracking-attempt.ts";
+import { ago, autoExitLine, stateLine } from "./tracking-text.ts";
 import type { ReadingError } from "./usage.ts";
 import { WorkspaceSchema } from "./workspace.ts";
 
@@ -69,8 +71,12 @@ const StartedSchema = Type.Object({
 	),
 	thinking: Type.String(),
 	autoExit: Type.Boolean(),
+	resumedFrom: Type.Optional(Type.String({ description: "The delegation whose session this one reopened." })),
 	windowId: Type.String(),
 	windowName: Type.String(),
+	windowSession: Type.Optional(
+		Type.String({ description: "The tmux session its window is in now; absent when the window is gone." }),
+	),
 	cwd: Type.Optional(
 		Type.String({ description: "The directory its window opened in; absent for records from before it was kept." }),
 	),
@@ -81,7 +87,7 @@ const StartedSchema = Type.Object({
 		STARTED_STATES.map((state) => Type.Literal(state)),
 		{
 			description:
-				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final; gone and window-closed turn done if a late reply arrives.",
+				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final, though a later delegation_resume continues one as a new delegation; gone and window-closed turn done if a late reply arrives.",
 		},
 	),
 	closed: Type.Boolean(),
@@ -119,7 +125,7 @@ export const CloseSchema = Type.Object({
 });
 
 /** A tool as registered; `execute` takes the tool's own parameters, which the registration call does not check. */
-type ToolDef = {
+export type ToolDef = {
 	name: string;
 	label: string;
 	description: string;
@@ -130,7 +136,7 @@ type ToolDef = {
 };
 
 /** Every window on the server, asked once; a failed ask is `undefined`, never an empty list. */
-async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined> {
+export async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined> {
 	try {
 		return await tmux.listWindows();
 	} catch {
@@ -139,48 +145,17 @@ async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined>
 }
 
 /** The window a delegation owns: one with both its recorded id and its recorded name, since ids restart with every tmux server. */
-function ownWindow(windows: TmuxWindow[], record: StartedRecorded): TmuxWindow | undefined {
+export function ownWindow(windows: TmuxWindow[], record: StartedRecorded): TmuxWindow | undefined {
 	return windows.find((window) => window.id === record.windowId && window.name === record.windowName);
 }
 
 /** What the listing says about a delegation's window; a matching window whose program exited counts as gone. */
-function windowState(windows: TmuxWindow[] | undefined, record: StartedRecorded): WindowState {
+export function windowState(windows: TmuxWindow[] | undefined, record: StartedRecorded): WindowState {
 	if (windows === undefined) return "unknown";
 	const own = ownWindow(windows, record);
 	return own !== undefined && !own.exited ? "open" : "gone";
 }
 
-/** Records from before auto-exit existed kept their windows open, so they read off. */
-function autoExitLine(record: StartedRecorded): string {
-	return record.autoExit === true
-		? "on — the delegate closes its window after a normal completion unless the user took over there"
-		: "off — the window stays open after the result";
-}
-
-/** The state, worded for the `state:` line. */
-function stateLine(state: DelegationState, record: StartedRecorded): string {
-	switch (state) {
-		case "running":
-			return "running — the window is open and no result has arrived";
-		case "gone":
-			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
-		case "done":
-			return `done — result status: ${record.result?.status ?? "unknown"}; the result reaches this session as a [delegate] message on its own`;
-		case "closed":
-			return "closed — delegation_close recorded it";
-		case "window-closed":
-			return "closed — the window is gone";
-		case "unknown":
-			return "unknown — tmux could not be asked whether the window is open";
-		case "planned":
-		case "created":
-		case "rolled-back":
-		case "retained":
-		case "interrupted":
-			return `${state} — no window id/start was recorded; a window may still exist`;
-	}
-}
-
 /** One delegation as `delegation_status` reports it; its text and details both read from this. */
 type View = {
 	record: StartedRecorded;
@@ -191,18 +166,19 @@ type View = {
 	lastActive: Date | undefined;
 	/** The checkout observed for this status call; the recorded result keeps its own. */
 	snapshot: WorkspaceSnapshot;
+	/** The delegation that resumed this one, if any. */
+	resumedAs: string | undefined;
+	/** The session its window is in now, looked up; undefined when the window is gone or unknown. */
+	windowSession: string | undefined;
 };
 
-/** How long ago, worded for the `state:` line: `just now`, `N min ago` or `N h M min ago`. */
-function ago(ms: number): string {
-	const minutes = Math.floor(ms / 60_000);
-	if (minutes < 1) return "just now";
-	if (minutes < 60) return `${minutes} min ago`;
-	return `${Math.floor(minutes / 60)} h ${minutes % 60} min ago`;
-}
-
 /** The view of a delegation: its state and the fields the text and details share. */
-function view(record: StartedRecorded, windows: TmuxWindow[] | undefined, ctx: ExtensionContext): View {
+function view(
+	record: StartedRecorded,
+	windows: TmuxWindow[] | undefined,
+	ctx: ExtensionContext,
+	resumedAs: string | undefined,
+): View {
 	const state = deriveState(record, windowState(windows, record));
 	const sessionPath = locateSession(record, ctx.sessionManager.getSessionDir());
 	let lastActive: Date | undefined;
@@ -214,31 +190,42 @@ function view(record: StartedRecorded, windows: TmuxWindow[] | undefined, ctx: E
 		}
 	}
 	const snapshot = inspectWorkspace(record.workspace?.cwd, record.workspace?.git);
-	return { record, state, name: recordedName(record), sessionPath, lastActive, snapshot };
+	const windowSession = windows === undefined ? undefined : ownWindow(windows, record)?.session;
+	return { record, state, name: recordedName(record), sessionPath, lastActive, snapshot, resumedAs, windowSession };
 }
 
 /** The text block for one delegation. */
-function viewText({ record, state, name, sessionPath, lastActive, snapshot }: View): string {
+function viewText({ record, state, name, sessionPath, lastActive, snapshot, resumedAs, windowSession }: View): string {
 	const [checkout, ...categories] = snapshotLines(snapshot);
 	const seen = lastActive === undefined ? "" : ` (last active ${ago(Date.now() - lastActive.getTime())})`;
 	const lines = [
 		`${record.id} ${record.agent} (${modelLabel(record.model, record.result?.finishedModel)}, thinking ${record.thinking})`,
 		`  name: ${name}`,
+		...(record.resumedFrom === undefined ? [] : [`  resumed from ${record.resumedFrom}`]),
+		...(resumedAs === undefined ? [] : [`  resumed as ${resumedAs}`]),
 		`  state: ${stateLine(state, record)}${seen}`,
-		`  window: ${record.windowName} (${record.windowId})`,
+		`  window: ${record.windowName} (${record.windowId})${windowSession === undefined || windowSession === "" ? "" : ` in session ${windowSession}`}`,
 		`  cwd: ${cwdLine(record.cwd)}`,
 		...(record.workspace === undefined ? [] : [`  workspace: ${workspaceLine(record.workspace)}`]),
 		`  checkout now: ${checkout}`,
 		...categories.map((line) => `    ${line}`),
 		`  auto-exit: ${autoExitLine(record)}`,
-		`  session: ${sessionPath ?? `${record.id} (no session file yet)`}`,
+		`  session: ${sessionPath ?? `${sessionIdOf(record)} (no session file yet)`}`,
 	];
 	if (record.result !== undefined) lines.push(`  envelope: ${record.result.envelopePath}`);
 	return lines.join("\n");
 }
 
 /** The structured details for one delegation. */
-function viewDetails({ record, state, name, sessionPath, lastActive, snapshot }: View): Record<string, unknown> {
+function viewDetails({
+	record,
+	state,
+	name,
+	sessionPath,
+	lastActive,
+	snapshot,
+	windowSession,
+}: View): Record<string, unknown> {
 	return {
 		kind: "started",
 		id: record.id,
@@ -248,8 +235,10 @@ function viewDetails({ record, state, name, sessionPath, lastActive, snapshot }:
 		...(record.result?.finishedModel === undefined ? {} : { finishedModel: record.result.finishedModel }),
 		thinking: record.thinking,
 		autoExit: record.autoExit === true,
+		...(record.resumedFrom === undefined ? {} : { resumedFrom: record.resumedFrom }),
 		windowId: record.windowId,
 		windowName: record.windowName,
+		...(windowSession === undefined || windowSession === "" ? {} : { windowSession }),
 		...(record.cwd === undefined ? {} : { cwd: record.cwd }),
 		...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
 		...(record.workspace === undefined ? {} : { workspace: record.workspace }),
@@ -384,7 +373,10 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		): Promise<ReturnType<typeof toolResult>> {
 			const records = selectRecords(results, params.id);
 			const windows = await listWindows(tmux);
-			const views = records.map((record) => (isStarted(record) ? view(record, windows, ctx) : record));
+			const resumedAs = (id: string) => results.list().find((item) => isStarted(item) && item.resumedFrom === id)?.id;
+			const views = records.map((record) =>
+				isStarted(record) ? view(record, windows, ctx, resumedAs(record.id)) : record,
+			);
 			const marks = activeMarks();
 			const errors = readingErrors();
 			const details = {

package/src/window-placement.ts

@@ -0,0 +1,31 @@
+// Call-time choice of where delegate windows open. `companion` (the default)
+// opens them in a session of their own, `<parent's session>-squire`; `current`
+// opens them in the parent's own session, as before. Read from
+// `<agent dir>/squire/settings.json` at every launch, like `worktreeRoot`.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type WindowPlacement = "companion" | "current";
+
+/**
+ * The placement for this call. An unknown value refuses with the file named.
+ * A file that cannot be read or parsed is left to the worktree settings,
+ * which report it when a launch needs them: it does not stop the launches
+ * that never read it, so those keep the default.
+ */
+export function windowPlacement(agentDir: string): WindowPlacement {
+	const file = join(agentDir, "squire", "settings.json");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return "companion";
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return "companion";
+	const value = (parsed as Record<string, unknown>).windowPlacement;
+	if (value === undefined || value === "companion") return "companion";
+	if (value === "current") return "current";
+	throw new Error(
+		`invalid window placement settings ${file}: windowPlacement must be "companion" or "current", not ${JSON.stringify(value)}`,
+	);
+}