pi-squire 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-26
+
+### Changed
+
+- Delegates open in a companion tmux session, `<your session>-squire`, instead
+  of your own session, created on demand and removed by tmux with its last
+  window. pi-squire marks the session it creates (tmux session option
+  `@squire-companion`), so only a marked session counts as a companion: your
+  own session called `pi-squire` gets `pi-squire-squire`. Set
+  `"windowPlacement": "current"` in `<agent dir>/squire/settings.json` to open
+  them in your session as before; any other value refuses the launch.
+  The start message, `delegation_status` and the delegate card name the session,
+  and the `delegate` and `delegation_resume` results and the status details gain
+  an optional `windowSession`. `session:launch` is unchanged.
+- tmux 3.2 or later is now required (it was 3.0); `/delegate`, `/delegate-resume`
+  and the tools refuse an older tmux with its version.
+
 ## [0.11.0] - 2026-10-26
 
 ### Added
@@ -474,7 +491,8 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/gvanderclay/pi-squire/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/gvanderclay/pi-squire/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/gvanderclay/pi-squire/compare/v0.9.5...v0.10.0
 [0.9.5]: https://github.com/gvanderclay/pi-squire/compare/v0.9.4...v0.9.5

package/README.md

@@ -16,9 +16,11 @@ You need:
   options the parent guidance uses, and the extension APIs the package relies
   on. Pi supplies the peer dependencies `@earendil-works/pi-coding-agent` and
   `typebox`.
-- tmux 3.0 or later, with the Pi session running in a tmux pane. That is the
-  first version with `new-window -e`. A window is opened in the pane's
-  session, so a client attached elsewhere does not matter.
+- tmux 3.2 or later, with the Pi session running in a tmux pane. That is the
+  first version with `new-session -e` and `display-popup`. Windows are placed
+  relative to the pane's session (see [Where delegate windows
+  open](#where-delegate-windows-open)), so a client attached elsewhere does
+  not matter.
 - A provider of `message:*`;
   [pi-session-mail](https://github.com/gvanderclay/pi-session-mail) is one
   example. Without a provider there is no way to send the task or get an
@@ -130,6 +132,39 @@ temporary folder, not as text on the command line.
   missing. In print mode (`pi -p`) Pi does not show the refusal notices, so
   the refusal is silent there.
 
+## Where delegate windows open
+
+By default a delegate's window opens in a **companion session** named after
+yours with `-squire` added: from the session `work`, delegates go to
+`work-squire`. Your own session stays as it is, even when its name already
+ends in `-squire`: a session called `pi-squire` gets `pi-squire-squire`.
+pi-squire marks each companion session it creates with the tmux session
+option `@squire-companion`; a parent that runs in a marked session uses it, so
+a delegate that delegates does not make `work-squire-squire`.
+
+- The session is created on demand, by the launch that needs it, and tmux
+  removes it with its last window, so it does not outlive its delegates.
+- `detach-on-destroy` is set to `off` (and the mark set) on that session only: if you are
+  looking at it when its last delegate exits, tmux moves you to your most
+  recent other session instead of detaching you. Your sessions and tmux's
+  global options are never changed.
+- The start message, the delegate card and the `delegate` and
+  `delegation_resume` results show the session the window opened in, as the
+  optional `windowSession`; they keep that name. `delegation_status` looks it
+  up each time, so it follows a window you move to another session, which is
+  still found, closed and resumed.
+
+To open windows in your own session, as before, set `windowPlacement` in
+`<agent dir>/squire/settings.json`, beside `worktreeRoot`:
+
+```json
+{ "windowPlacement": "current" }
+```
+
+The values are `companion` (the default when the setting is absent) and
+`current`. The file is read at each launch. Any other value refuses the launch
+with an error naming the file, before the task is sent or a window opens.
+
 ## Working directory
 
 `--cwd <dir>` (the `delegate` tool's `cwd`) runs the delegate in an existing

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",

package/src/index.ts

@@ -56,9 +56,10 @@ import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
 import { dirtyNotice, renderDelegateCall, renderDelegateResult, resourceLine } from "./render.ts";
 import { createResults, delegateName, type WorkspaceAttempt } from "./results.ts";
 import { createResume, type ResumeRequest, resumableIds, startedLine } from "./resume.ts";
-import { createTmuxClient, type TmuxClient, WindowOpenError } from "./tmux.ts";
+import { createTmuxClient, type OpenedWindow, requireTmuxVersion, type TmuxClient, WindowOpenError } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
+import { type WindowPlacement, windowPlacement } from "./window-placement.ts";
 import {
 	normalizeWorkspaceValue,
 	prepareDirectory,
@@ -149,6 +150,9 @@ export const DelegateSchema = Type.Object({
 	autoExit: Type.Boolean(),
 	windowId: Type.String(),
 	windowName: Type.String(),
+	windowSession: Type.Optional(
+		Type.String({ description: "The tmux session the window opened in, as tmux named it then." }),
+	),
 	cwd: Type.String({ description: "The directory the delegate's window opened in." }),
 	sessionDir: Type.String({ description: "The session-storage directory the delegate was told to use." }),
 	workspace: WorkspaceSchema,
@@ -216,6 +220,8 @@ type Launched = {
 	name: string;
 	windowId: string;
 	windowName: string;
+	/** The session the window opened in; undefined when tmux could not say. */
+	windowSession: string | undefined;
 	requestId: string;
 	cwd: string;
 	sessionDir: string;
@@ -640,7 +646,7 @@ export default function delegate(
 
 	/**
 	 * Build the delegate's command line and environment, emit `session:launch`
-	 * and open its window; returns the window id. A launch and a resume share
+	 * and open its window; returns the window id and session. A launch and a resume share
 	 * it and differ only in `session`, the arguments that choose the session:
 	 * `--session-id <id> --name <name>` for a new one, `--session <path>` to reopen.
 	 */
@@ -656,9 +662,24 @@ export default function delegate(
 		/** The tool call that started this launch or resume; undefined from a command. */
 		toolCallId: string | undefined;
 		ctx: ExtensionContext;
+		/** Chosen once, when the launch or resume began, so no later settings change can refuse it after mail. */
+		placement: WindowPlacement;
 		onWindowOpened?: () => void;
-	}): Promise<string> {
-		const { id, name, session, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, onWindowOpened } = input;
+	}): Promise<OpenedWindow> {
+		const {
+			id,
+			name,
+			session,
+			workspace,
+			trusted,
+			cwd,
+			sessionDir,
+			start,
+			toolCallId,
+			ctx,
+			placement,
+			onWindowOpened,
+		} = input;
 		const parent = ctx.sessionManager.getSessionId();
 		const managedContext =
 			workspace.mode === "managed"
@@ -699,9 +720,9 @@ export default function delegate(
 		// Listeners may only append to `args` and add to `env`; there is no veto.
 		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name, cwd, toolCallId };
 		pi.events.emit(LAUNCH, payload);
-		let windowId: string;
+		let opened: OpenedWindow;
 		try {
-			windowId = await tmux.openWindow({ name, cwd, argv: payload.args, env: payload.env });
+			opened = await tmux.openWindow({ name, cwd, argv: payload.args, env: payload.env }, placement);
 			onWindowOpened?.();
 		} catch (err) {
 			if (err instanceof WindowOpenError) {
@@ -709,7 +730,7 @@ export default function delegate(
 			}
 			throw new WindowOpenError(`could not open window ${name} for ${id}: ${(err as Error).message}`, "unknown");
 		}
-		return windowId;
+		return opened;
 	}
 
 	async function launchWindow(input: {
@@ -722,11 +743,13 @@ export default function delegate(
 		start: Start;
 		toolCallId: string | undefined;
 		ctx: ExtensionContext;
+		placement: WindowPlacement;
 		onWindowOpened: () => void;
 	}): Promise<Launched> {
-		const { id, requestId, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, onWindowOpened } = input;
+		const { id, requestId, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, placement, onWindowOpened } =
+			input;
 		const name = delegateName(start.agent.name, id, start.label);
-		const windowId = await openChild({
+		const { id: windowId, session: windowSession } = await openChild({
 			id,
 			name,
 			session: ["--session-id", id, "--name", name],
@@ -737,6 +760,7 @@ export default function delegate(
 			start,
 			toolCallId,
 			ctx,
+			placement,
 			onWindowOpened,
 		});
 		// No task text in the record: the request copy in `sent/` has it.
@@ -758,7 +782,7 @@ export default function delegate(
 			ctx,
 		);
 		tracking.startPolling();
-		return { id, name, windowId, windowName: name, requestId, cwd, sessionDir, workspace };
+		return { id, name, windowId, windowName: name, windowSession, requestId, cwd, sessionDir, workspace };
 	}
 
 	async function launch(
@@ -768,6 +792,9 @@ export default function delegate(
 		toolCallId?: string,
 	): Promise<Launched> {
 		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
+		await requireTmuxVersion(tmux);
+		// Read once, before anything is created or mailed; the launch keeps this value.
+		const placement = windowPlacement(getAgentDir());
 		const sessionDir = ctx.sessionManager.getSessionDir();
 		if (!isAbsolute(sessionDir))
 			throw new Error(
@@ -878,6 +905,7 @@ export default function delegate(
 				start,
 				toolCallId,
 				ctx,
+				placement,
 				onWindowOpened: () => {
 					windowOpened = true;
 				},
@@ -949,12 +977,13 @@ export default function delegate(
 		delegateSchema: DelegateSchema,
 		notInTmux: NOT_IN_TMUX,
 		startPolling: tracking.startPolling,
+		placement: () => windowPlacement(getAgentDir()),
 		roster: rosterFor,
 		chooseModel: (explicit, agent, models, preferred) => chooseModel(explicit, agent, models, proactive, preferred),
 		thinkingProblem,
 		prepareDirectory: (cwd, ctx, signal) => prepareDirectory({ cwd, signal }, ctx, getAgentDir()),
 		sendTask,
-		open: ({ id, name, sessionPath, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx }) =>
+		open: ({ id, name, sessionPath, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, placement }) =>
 			openChild({
 				id,
 				name,
@@ -966,15 +995,19 @@ export default function delegate(
 				start,
 				toolCallId,
 				ctx,
+				placement,
 			}),
 	});
 
+	/** The session a window opened in, for the start text. */
+	const inSession = (session: string | undefined): string => (session === undefined ? "" : ` in session ${session}`);
+
 	/** Where a selected directory put the delegate, for the start text; inherited starts stay compact. */
 	const placedIn = (launched: Launched): string =>
 		launched.workspace.mode !== "inherited" ? ` in ${launched.cwd}` : "";
 
 	const started = (launched: Launched, start: Start): string =>
-		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
+		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
 	async function command(input: string, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
@@ -1115,7 +1148,7 @@ export default function delegate(
 			const launched = await launch(start, ctx, signal, toolCallId);
 			ctx.ui.notify(started(launched, start), "info");
 			return toolResult(
-				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}${placedIn(launched)}.${launched.workspace.mode === "managed" ? ` Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""} It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
+				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}.${launched.workspace.mode === "managed" ? ` Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""} It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
 				{
 					outcome: "started",
 					id: launched.id,
@@ -1127,6 +1160,7 @@ export default function delegate(
 					autoExit: start.autoExit,
 					windowId: launched.windowId,
 					windowName: launched.windowName,
+					...(launched.windowSession === undefined ? {} : { windowSession: launched.windowSession }),
 					cwd: launched.cwd,
 					sessionDir: launched.sessionDir,
 					workspace: launched.workspace,

package/src/render.ts

@@ -282,7 +282,7 @@ export function renderDelegateResult(
 	const lines = [
 		`${theme.fg("accent", "●")} ${theme.fg("toolTitle", theme.bold(started.windowName))}${theme.fg(
 			"dim",
-			` (${started.model}) — started`,
+			`${started.windowSession === undefined ? "" : ` in session ${started.windowSession}`} (${started.model}) — started`,
 		)}`,
 	];
 	const task = taskLine(context.args.task, theme);
@@ -293,7 +293,7 @@ export function renderDelegateResult(
 			...[
 				...started.notices,
 				`delegation ${started.id}`,
-				`window ${started.windowName} (${started.windowId})`,
+				`window ${started.windowName} (${started.windowId})${started.windowSession === undefined ? "" : ` in session ${started.windowSession}`}`,
 				// Results saved before cwd was recorded have none.
 				`cwd ${(started.cwd as string | undefined) === undefined ? cwdLine(undefined) : tilde(started.cwd)}`,
 				// Results saved before workspaces were recorded have none.

package/src/resume.ts

@@ -22,8 +22,9 @@ import {
 	recordedName,
 	type StartedRecorded,
 } from "./results.ts";
-import type { TmuxClient } from "./tmux.ts";
+import { type OpenedWindow, requireTmuxVersion, type TmuxClient } from "./tmux.ts";
 import { listWindows, ownWindow, type ToolDef, toolResult, windowState } from "./tracking.ts";
+import type { WindowPlacement } from "./window-placement.ts";
 import type { Workspace } from "./workspace.ts";
 
 /** What a resume asks for; the fields after `task` are optional overrides. */
@@ -49,6 +50,8 @@ export type ResumeDeps = {
 	/** The refusal text for a session outside tmux. */
 	notInTmux: string;
 	startPolling(): void;
+	/** The window placement for this call; throws on an invalid setting. */
+	placement(): WindowPlacement;
 	roster(ctx: ExtensionContext): Roster;
 	chooseModel(
 		explicit: string | undefined,
@@ -65,7 +68,7 @@ export type ResumeDeps = {
 	): Promise<{ workspace: Workspace; trusted: boolean }>;
 	/** Mail the task to a session id; returns the request id. */
 	sendTask(to: string, task: string): string;
-	/** Open the window with `--session <path>`; returns its id. */
+	/** Open the window with `--session <path>`; returns its id and session. */
 	open(input: {
 		id: string;
 		name: string;
@@ -77,7 +80,8 @@ export type ResumeDeps = {
 		start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean };
 		toolCallId: string | undefined;
 		ctx: ExtensionContext;
-	}): Promise<string>;
+		placement: WindowPlacement;
+	}): Promise<OpenedWindow>;
 };
 
 /** A started resume: what the tool and the command report. */
@@ -92,6 +96,8 @@ export type Resumed = {
 	autoExit: boolean;
 	windowId: string;
 	windowName: string;
+	/** The session the window opened in, when tmux could say. */
+	windowSession?: string;
 	cwd: string;
 	sessionDir: string;
 	workspace: Workspace;
@@ -273,15 +279,22 @@ async function mailTask(deps: ResumeDeps, windowId: string, sessionId: string, t
 
 async function startResume(
 	deps: ResumeDeps,
-	input: { record: StartedRecorded; session: SessionFile; plan: Plan; task: string; toolCallId: string | undefined },
+	input: {
+		record: StartedRecorded;
+		session: SessionFile;
+		plan: Plan;
+		task: string;
+		toolCallId: string | undefined;
+		placement: WindowPlacement;
+	},
 	ctx: ExtensionContext,
 ): Promise<Resumed> {
-	const { record, session, plan, task, toolCallId } = input;
+	const { record, session, plan, task, toolCallId, placement } = input;
 	const { start, chosen, workspace } = plan;
 	const id = randomUUID();
 	const sessionId = sessionIdOf(record);
 	const name = recordedName(record);
-	const windowId = await deps.open({
+	const { id: windowId, session: windowSession } = await deps.open({
 		id,
 		name,
 		sessionPath: session.path,
@@ -292,6 +305,7 @@ async function startResume(
 		start,
 		toolCallId,
 		ctx,
+		placement,
 	});
 	const requestId = await mailTask(deps, windowId, sessionId, task);
 	deps.results.recordStart(
@@ -325,6 +339,7 @@ async function startResume(
 		autoExit: start.autoExit,
 		windowId,
 		windowName: name,
+		...(windowSession === undefined ? {} : { windowSession }),
 		cwd: workspace.cwd,
 		sessionDir: session.dir,
 		workspace,
@@ -346,6 +361,8 @@ async function resume(
 	signal: AbortSignal | undefined,
 ): Promise<Resumed> {
 	if (!deps.tmux.insideTmux()) throw new Error(deps.notInTmux);
+	await requireTmuxVersion(deps.tmux);
+	const placement = deps.placement(); // read once, before the exited window is killed or anything is mailed
 	if (request.task.trim() === "") throw new Error("a task is required");
 	const record = newestStarted(deps.results, request.id);
 	await ensureExited(record, deps.tmux);
@@ -360,15 +377,22 @@ async function resume(
 	inFlight.add(record.id);
 	try {
 		const plan = await planResume(deps, { record, agent, session, request }, ctx, signal);
-		return await startResume(deps, { record, session, plan, task: request.task, toolCallId: request.toolCallId }, ctx);
+		return await startResume(
+			deps,
+			{ record, session, plan, task: request.task, toolCallId: request.toolCallId, placement },
+			ctx,
+		);
 	} finally {
 		inFlight.delete(record.id);
 	}
 }
 
+/** The session a window opened in, for the start text. */
+const inSession = (session: string | undefined): string => (session === undefined ? "" : ` in session ${session}`);
+
 /** The one line the command and the tool tell the user. */
 export function startedLine(resumed: Resumed): string {
-	return `delegate: resumed ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} in window ${resumed.windowName}${resumed.fallbackNote === "" ? "" : `. ${resumed.fallbackNote}`}${resumed.notices.map((line) => `. ${line}`).join("")}`;
+	return `delegate: resumed ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} in window ${resumed.windowName}${inSession(resumed.windowSession)}${resumed.fallbackNote === "" ? "" : `. ${resumed.fallbackNote}`}${resumed.notices.map((line) => `. ${line}`).join("")}`;
 }
 
 /** The `delegation_resume` tool. */
@@ -410,7 +434,7 @@ function resumeTool(deps: ResumeDeps): ToolDef {
 			const { fallbackNote, ...details } = resumed;
 			ctx.ui.notify(startedLine(resumed), "info");
 			return toolResult(
-				`Resumed delegation ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} (${resumed.model}, thinking ${resumed.thinking}) in window ${resumed.windowName}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${fallbackNote === "" ? "" : ` ${fallbackNote}`}${resumed.notices.map((line) => ` ${line}`).join("")}`,
+				`Resumed delegation ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} (${resumed.model}, thinking ${resumed.thinking}) in window ${resumed.windowName}${inSession(resumed.windowSession)}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${fallbackNote === "" ? "" : ` ${fallbackNote}`}${resumed.notices.map((line) => ` ${line}`).join("")}`,
 				{ outcome: "started", ...details },
 			);
 		},

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.ts

@@ -74,6 +74,9 @@ const StartedSchema = Type.Object({
 	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." }),
 	),
@@ -165,6 +168,8 @@ type View = {
 	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;
 };
 
 /** The view of a delegation: its state and the fields the text and details share. */
@@ -185,11 +190,12 @@ function view(
 		}
 	}
 	const snapshot = inspectWorkspace(record.workspace?.cwd, record.workspace?.git);
-	return { record, state, name: recordedName(record), sessionPath, lastActive, snapshot, resumedAs };
+	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, resumedAs }: 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 = [
@@ -198,7 +204,7 @@ function viewText({ record, state, name, sessionPath, lastActive, snapshot, resu
 		...(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}`,
@@ -211,7 +217,15 @@ function viewText({ record, state, name, sessionPath, lastActive, snapshot, resu
 }
 
 /** 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,
@@ -224,6 +238,7 @@ function viewDetails({ record, state, name, sessionPath, lastActive, snapshot }:
 		...(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 }),

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)}`,
+	);
+}