pi-squire 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-11-01
+
+### Changed
+
+- New root companion sessions deliberately default to `<project>-delegates`
+  instead of `<project>-delegate-session`. Set `companionSuffix` in
+  `<agent dir>/squire/settings.json` to use another suffix, such as `playpen`.
+  Existing companions and saved identities keep their names, including for
+  nested launches and resumes.
+
 ## [0.17.0] - 2026-11-01
 
 ### Breaking
@@ -998,7 +1008,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.17.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/gvanderclay/pi-squire/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/gvanderclay/pi-squire/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/gvanderclay/pi-squire/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/gvanderclay/pi-squire/compare/v0.14.0...v0.15.0

package/README.md

@@ -358,14 +358,14 @@ same-id Squire owner and obsolete local/shared resume chains are refused.
 ## Where delegate windows open
 
 By default a delegate's window opens in a shared **project companion session**
-named `<project>-delegate-session` on your existing tmux server. The owning
+named `<project>-delegates` on your existing tmux server. The owning
 root Pi session's project chooses it, not the parent tmux session or the
 delegate's working directory. Launching into another repository or creating a
 worktree there still uses the root's companion; resuming a delegate does too.
 
 Nested launches inherit the original root project: A → coordinator in B →
 worker in C all select A's companion. The preferred base name (for example,
-`A-delegate-session`) is saved as `rootPlacement` in the existing durable
+`A-delegates`) is saved as `rootPlacement` in the existing durable
 delegation identity and shared tree records, not recomputed from B/C or the
 containing tmux session. Reopening the **same** coordinator session without its
 launch environment restores that preference; it can launch or directly resume
@@ -384,7 +384,7 @@ uses the root working-directory basename instead.
 Project names preserve ASCII letters (including case), digits, hyphens and
 underscores. Runs of other characters become one hyphen, edge hyphens are
 trimmed, and an empty name becomes `project`: `Client API` uses
-`Client-API-delegate-session`.
+`Client-API-delegates`.
 
 Multiple roots share a companion even across parent tmux sessions. Distinct
 paths with the same basename, separate clones named alike, and names that
@@ -394,12 +394,13 @@ each root.
 
 pi-squire verifies the tmux session option `@squire-companion` before reusing
 an occupied name. An unmarked session is left untouched; numbered alternatives
-start at `<project>-delegate-session-2`, skipping unmarked alternatives too.
+start at `<project>-<suffix>-2`, skipping unmarked alternatives too.
 Later launches reuse an existing managed alternative even if a lower name
 becomes free. Unexpected duplicate managed candidates use the first in numeric
-order, without moving windows or repairing sessions. Existing legacy companions
-and live windows are neither renamed nor migrated; only new launches and
-resumes use project naming.
+order, without moving windows or repairing sessions. Existing companions,
+live windows and saved identities keep their names, including the former
+`<project>-delegate-session` default. Nested launches and resumes retain the
+saved preference; companions are not renamed or migrated.
 
 - 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.
@@ -416,6 +417,22 @@ resumes use project naming.
   up each time, so it follows a window you move to another session, which is
   still found, closed and resumed.
 
+To use a different suffix, set `companionSuffix` in
+`<agent dir>/squire/settings.json`:
+
+```json
+{ "companionSuffix": "playpen" }
+```
+
+This names a new root's companion `<project>-playpen`. The default suffix is
+`delegates`. A suffix must contain 1 to 32 ASCII letters, digits, underscores
+or hyphens, with no leading or trailing hyphen. It cannot be entirely numeric
+or end in a hyphen followed by digits, such as `2` or `x-10`, because those
+names overlap with numbered alternatives. An invalid suffix refuses the launch
+with an error naming the file, before the task is sent or a window opens.
+The suffix is read with `windowPlacement` at launch. It does not replace a
+saved root preference for nested launches or resumes.
+
 To open windows in your own session, as before, set `windowPlacement` in
 `<agent dir>/squire/settings.json`, beside `worktreeRoot`:
 
@@ -1076,7 +1093,7 @@ add one.
 
 `<agent dir>/squire/` holds the optional parent guidance file and
 `settings.json` (`maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`,
-`windowPlacement`, `worktreeRoot`, `delegateTools`, `toolBundles`,
+`windowPlacement`, `companionSuffix`, `worktreeRoot`, `delegateTools`, `toolBundles`,
 `delegateWidgetPlacement` and `delegateWidgetMaxEntries`); the
 agents live in `<agent dir>/agents/` (see [Agents](#agents)).
 `delegation_prompt.md` is Markdown, inserted unchanged as the
@@ -1967,7 +1984,7 @@ Other extensions may rely on:
   `<agent dir>/agents/<name>.md` and, in a trusted project,
   `<cwd>/.pi/agents/<name>.md`;
 - the `maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`, `delegateTools`, `toolBundles`,
-  `windowPlacement`, `worktreeRoot`, `delegateWidgetPlacement` and
+  `windowPlacement`, `companionSuffix`, `worktreeRoot`, `delegateWidgetPlacement` and
   `delegateWidgetMaxEntries` settings in
   `<agent dir>/squire/settings.json`;
 - the optional `<agent dir>/squire/delegation_prompt.md` file and the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.17.0",
+	"version": "0.18.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

@@ -100,7 +100,7 @@ import { registerTrustControl } from "./trust-control.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
 import { registerDelegateWidget } from "./widget.ts";
 import { registerActivityRuntime } from "./widget-activity-runtime.ts";
-import { assertRootPlacement, placementProject, type WindowPlacement, windowPlacement } from "./window-placement.ts";
+import { assertRootPlacement, placementProject, type WindowPlacement, windowSettings } from "./window-placement.ts";
 import {
 	normalizeWorkspaceValue,
 	prepareDirectory,
@@ -1147,11 +1147,11 @@ export default function delegate(
 		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
 		await requireTmuxVersion(tmux);
 		// Read once, before anything is created or mailed; the launch keeps these values.
-		const placement = windowPlacement(getAgentDir());
+		const { placement, companionSuffix } = windowSettings(getAgentDir());
 		const parentIdentity = identity.current();
 		const project = parentIdentity
 			? { companion: parentIdentity.rootPlacement, notices: [] }
-			: placementProject(ctx.cwd);
+			: placementProject(ctx.cwd, companionSuffix);
 		assertRootPlacement(project.companion);
 		const own = identity.child(start.agent, ctx, project.companion);
 		if (parentIdentity) assertParentPlacement(readTree(own.root), own);
@@ -1366,7 +1366,7 @@ export default function delegate(
 		delegateSchema: DelegateSchema,
 		notInTmux: NOT_IN_TMUX,
 		startPolling: tracking.startPolling,
-		placement: () => windowPlacement(getAgentDir()),
+		placement: () => windowSettings(getAgentDir()).placement,
 		roster: rosterFor,
 		admit: (agent, ctx) => admit(agent, currentRoster(ctx)),
 		authorize: (id, ctx) => {

package/src/window-placement.ts

@@ -1,6 +1,6 @@
 // Call-time choice of where delegate windows open. `companion` (the default)
-// opens them in a shared project session; `current`
-// opens them in the parent's own session, as before. Read from
+// opens them in a shared project session named `<project>-<companionSuffix>`
+// (default suffix `delegates`); `current` opens in the parent's own session. Read from
 // `<agent dir>/squire/settings.json` at every launch, like `worktreeRoot`.
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
@@ -9,21 +9,25 @@ import { inspectGit } from "./git.ts";
 
 export type WindowPlacement = "companion" | "current";
 
+const DEFAULT_SUFFIX = "delegates";
+const safeName = /^[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?$/;
+const numberedEnding = /(^|-)[0-9]+$/;
+
 /** A preferred base, never a selected numbered companion or a tmux locator. */
 export function assertRootPlacement(value: unknown): asserts value is string {
-	if (typeof value !== "string" || !/^[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?-delegate-session$/.test(value))
+	if (typeof value !== "string" || !safeName.test(value) || !value.includes("-") || numberedEnding.test(value))
 		throw new Error(
 			"invalid or missing rootPlacement in delegation identity; original root companion preference is required",
 		);
 }
 
 /** The owning root's project, never the delegate's chosen working directory. */
-export function placementProject(cwd: string): { companion: string; notices: string[] } {
+export function placementProject(cwd: string, suffix = DEFAULT_SUFFIX): { companion: string; notices: string[] } {
 	const git = inspectGit(cwd);
 	const project = basename(git.kind === "git" ? git.identity.mainRoot : cwd);
 	const normalized = project.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 	return {
-		companion: `${normalized}-delegate-session`,
+		companion: `${normalized}-${suffix}`,
 		notices:
 			git.kind === "unknown"
 				? [
@@ -38,19 +42,32 @@ export function placementProject(cwd: string): { companion: string; notices: str
  * This reader defaults malformed/unreadable files to companion; mandatory
  * tree-cap admission separately refuses those files for every launch/resume.
  */
-export function windowPlacement(agentDir: string): WindowPlacement {
+export function windowSettings(agentDir: string): { placement: WindowPlacement; companionSuffix: string } {
 	const file = join(agentDir, "squire", "settings.json");
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(readFileSync(file, "utf8"));
 	} catch {
-		return "companion";
+		return { placement: "companion", companionSuffix: DEFAULT_SUFFIX };
 	}
-	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)}`,
-	);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+		return { placement: "companion", companionSuffix: DEFAULT_SUFFIX };
+	const { windowPlacement: placement = "companion", companionSuffix = DEFAULT_SUFFIX } = parsed as Record<
+		string,
+		unknown
+	>;
+	if (placement !== "companion" && placement !== "current")
+		throw new Error(
+			`invalid window placement settings ${file}: windowPlacement must be "companion" or "current", not ${JSON.stringify(placement)}`,
+		);
+	if (
+		typeof companionSuffix !== "string" ||
+		companionSuffix.length > 32 ||
+		!safeName.test(companionSuffix) ||
+		numberedEnding.test(companionSuffix)
+	)
+		throw new Error(
+			`invalid window placement settings ${file}: companionSuffix must be 1 to 32 ASCII letters, digits, underscores or hyphens, with no edge hyphen or numeric final segment, not ${JSON.stringify(companionSuffix)}`,
+		);
+	return { placement, companionSuffix };
 }