@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/lib/env.ts

@@ -12,24 +12,82 @@ export const ENV_ROOT = "PI_WORKTREE_ROOT";
 
 /**
  * Env var listing extension names to skip. Entries are separated by commas
- * and/or whitespace. Unset or empty means every extension loads.
+ * and/or whitespace. Unset or empty means every extension loads except the
+ * opt-in ones.
  */
 export const ENV_DISABLED_EXTENSIONS = "PI_DISABLED_EXTENSIONS";
 
+/**
+ * Env var listing the opt-in extensions to load. Entries are separated by
+ * commas and/or whitespace. Only `OPT_IN_EXTENSIONS` reads it; it never
+ * switches off an extension that loads by default.
+ */
+export const ENV_ENABLED_EXTENSIONS = "PI_ENABLED_EXTENSIONS";
+
 /** Env var that turns off Pi's automatic network activity, including our own. */
 export const ENV_OFFLINE = "PI_OFFLINE";
 
-/** False when `name` appears in `PI_DISABLED_EXTENSIONS`, true otherwise. */
-export function isExtensionEnabled(name: string): boolean {
-	const raw = process.env[ENV_DISABLED_EXTENSIONS];
-	if (!raw) return true;
-	const disabled = new Set(
+/**
+ * Extensions that stay unloaded unless `PI_ENABLED_EXTENSIONS` names them.
+ *
+ * `board` and `team` are one workflow — a work list, and the lead's half of it
+ * — so a session opts into both or neither. They stay independent at runtime:
+ * naming one never loads the other.
+ *
+ * They are declared in the package manifest like every other extension, so Pi
+ * still discovers them and their docs stay in the pack; the surface is simply
+ * not registered until the session asks for it. `new Set` rather than an array
+ * literal because `test/boundaries.test.ts` rejects a module-level array in
+ * `lib/`, and a fixed keyword table is the one container that rule allows.
+ */
+export const OPT_IN_EXTENSIONS: ReadonlySet<string> = new Set(["board", "team"]);
+
+/** What the environment says about one extension this session. */
+export type ExtensionEnablement = "on" | "disabled" | "opt-in";
+
+/** The names in an extension-list variable, lowercased; empty when it is unset. */
+function listedExtensions(variable: string): Set<string> {
+	const raw = process.env[variable];
+	if (!raw) return new Set();
+	return new Set(
 		raw
 			.split(/[\s,]+/)
 			.map((entry) => entry.trim().toLowerCase())
 			.filter(Boolean),
 	);
-	return !disabled.has(name.toLowerCase());
+}
+
+/**
+ * How this session treats `name`: `disabled` when `PI_DISABLED_EXTENSIONS`
+ * names it, `opt-in` when only `PI_ENABLED_EXTENSIONS` can switch it on and has
+ * not, and `on` otherwise. An explicit disable wins over an opt-in name.
+ */
+export function extensionEnablement(name: string): ExtensionEnablement {
+	const key = name.toLowerCase();
+	if (listedExtensions(ENV_DISABLED_EXTENSIONS).has(key)) return "disabled";
+	if (OPT_IN_EXTENSIONS.has(key) && !listedExtensions(ENV_ENABLED_EXTENSIONS).has(key)) return "opt-in";
+	return "on";
+}
+
+/** Whether `name` loads this session, i.e. {@link extensionEnablement} says `on`. */
+export function isExtensionEnabled(name: string): boolean {
+	return extensionEnablement(name) === "on";
+}
+
+/**
+ * What a report says about `name`: why this session is not loading it, or
+ * undefined when it is. One call answers both, so the state and the sentence
+ * cannot disagree, and the switch it names is the one that would change it.
+ */
+export function extensionDisabledReason(name: string): string | undefined {
+	switch (extensionEnablement(name)) {
+		case "on":
+			return undefined;
+		case "opt-in":
+			return `an opt-in extension; load it with \`${ENV_ENABLED_EXTENSIONS}=${name.toLowerCase()}\``;
+		case "disabled":
+			return `disabled through \`${ENV_DISABLED_EXTENSIONS}\``;
+	}
 }
 
 /**

package/lib/format.ts

@@ -38,6 +38,19 @@ export function formatCount(count: number): string {
 	return sign + out;
 }
 
+/**
+ * A list in a sentence: `a, b, or c`, or the same with `and`.
+ *
+ * One body, because a refusal that names the lanes a card may move to, one that names the
+ * fields a contract needs, and one that names the lanes a tool accepts are the same
+ * sentence, and a second copy drifts on the comma.
+ */
+export function listOf(entries: readonly string[], conjunction: "or" | "and" = "or"): string {
+	if (entries.length === 0) return "nothing";
+	if (entries.length === 1) return entries[0] ?? "nothing";
+	return `${entries.slice(0, -1).join(", ")}, ${conjunction} ${entries[entries.length - 1]}`;
+}
+
 /**
  * Compact duration: `450ms`, `3.2s`, `1m05s`, `2h03m`. Non-finite or
  * negative input reads `0ms`, so a missing timestamp never prints `NaN`.

package/lib/http/index.ts

@@ -1,17 +1,19 @@
 /**
- * The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: the
- * response shape, the header policy, the request-envelope helpers and the
- * guards built on them, the one server entry, the socket seam behind it, and the
- * mount contract a page uses to claim a prefix on the session's one port.
+ * The served-page kit: the loopback HTTP layer `file-browse`, `plan`, and `board`
+ * answer on — the response shape, the header policy, the request-envelope
+ * helpers and the guards built on them, the one server entry, the socket seam
+ * behind it, and the port band it draws from.
  *
- * Import from here rather than a leaf module, so the layer reads as one kit. The
- * `serve` extension imports {@link serveHttp} and never `./server.ts`; every other
- * extension imports {@link requestMount} and never binds a socket at all — a
- * hand-built `node:http` server beside this one is how the close path and the idle
- * grace start to differ again. The same rule covers the guards: `plan` and `board`
- * both serve a page that can write, so the `Host`, origin, and JSON rules are
- * {@link envelopeRefusal} and {@link requireJsonBody} rather than two copies, and
- * the credential a page carries is {@link mintToken} / {@link tokenMatches}.
+ * Import from here rather than a leaf module, so the layer reads as one kit. This
+ * barrel is deliberately *not* on a registration path: it is 978 lines that only
+ * a page that is actually served needs, so an extension reaches it from the
+ * handler that mounts one, never from its factory. The one exception is the
+ * mount contract itself — {@link requestMount} and {@link HTTP_MOUNT_CHANNEL},
+ * which live in `./mount.ts` — because asking for a prefix is what a command does
+ * before any page exists. `board` and `plan` import that leaf directly; `serve`
+ * imports it for the channel and loads this barrel on the first bind; a new
+ * `lib/http/` leaf imported from a factory puts the whole kit back on every start,
+ * which `test/dependencies.test.ts` fails.
  *
  * Value-only, like the rest of `lib/`: the only state is what a returned closure
  * carries (`createCloser`, `serveHttp`).

package/lib/http/port.ts

@@ -1,25 +1,30 @@
 /**
- * The per-session port band the loopback pages share.
+ * The port band the loopback pages share, and the number a project keeps in it.
  *
- * `serve` draws the session's one port from it, so every page that session serves
+ * `serve` takes a session's one port from here, so every page that session serves
  * clusters where a person's bookmarks already point. The band is one product decision,
  * stated here once: a number repeated in each extension's config is several chances to
  * move one of them, and nothing would notice until a bookmark landed outside the range.
  *
+ * A project's number is its repository key hashed into the band rather than a fresh
+ * draw, so a session that starts again lands on the port its bookmark names; two
+ * repositories take two numbers without a setting. `serve.port` overrides it.
+ *
  * A pick is a guess, not a reservation. `serveHttp` binds it and falls back to whatever
- * free port the OS gives, so a port another process holds costs a retry rather than a
- * start.
+ * free port the OS gives, so a port another process holds — or another project's hash
+ * landing in the same slot — costs a retry rather than a start.
  */
 
-import { randomInt } from "node:crypto";
+import { createHash } from "node:crypto";
 
-/** Base of the per-session port range. */
+/** Base of the per-project port range. */
 export const PORT_BASE = 4780;
 
-/** Number of ports in the per-session range. */
+/** Number of ports in the per-project range. */
 export const PORT_RANGE = 1000;
 
-/** A random port in the per-session range `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
-export function randomPort(): number {
-	return PORT_BASE + randomInt(PORT_RANGE);
+/** The port a project prefers: its repository key hashed into `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
+export function projectPort(repoKey: string): number {
+	const digest = createHash("sha256").update(repoKey).digest();
+	return PORT_BASE + (digest.readUInt32BE(0) % PORT_RANGE);
 }

package/lib/lazy.ts

@@ -0,0 +1,45 @@
+/**
+ * One async load, run at most once.
+ *
+ * A surface a command needs but registration does not — a browser page, a
+ * review server, a screen — is imported through this: `get()` runs the loader
+ * and remembers the value, and `peek()` answers the value already loaded, or
+ * `undefined`, so a shutdown path never starts a load the session never used.
+ *
+ * A rejected load is not remembered. A transient failure can be retried, and a
+ * caller that sees the error can ask again; the alternative would make one bad
+ * import permanent for the process.
+ *
+ * State lives in this closure, not at module scope, because `lib/` is loaded
+ * with isolated module caches and is value-only.
+ */
+
+/** A value loaded on first use, with a way to ask whether it is already here. */
+export interface Lazy<T> {
+	/** Load the value, or return the one already loaded; concurrent calls share one load. */
+	get(): Promise<T>;
+	/** The loaded value, or `undefined` before a load and after a failed one. */
+	peek(): T | undefined;
+}
+
+export function lazy<T>(load: () => Promise<T>): Lazy<T> {
+	let loaded = false;
+	let value: T;
+	let pending: Promise<T> | undefined;
+	const get = (): Promise<T> => {
+		if (loaded) return Promise.resolve(value);
+		pending ??= load().then(
+			(result) => {
+				loaded = true;
+				value = result;
+				return result;
+			},
+			(error: unknown) => {
+				pending = undefined;
+				throw error;
+			},
+		);
+		return pending;
+	};
+	return { get, peek: () => (loaded ? value : undefined) };
+}

package/lib/plan-entry.ts

@@ -18,20 +18,24 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type BusAnswer, requestOverBus } from "./bus-request.ts";
 import { isPlanModeEnabled } from "./plan-state.ts";
-import { PLAN_ENTER_TOOL } from "./tool-names.ts";
+import { PLAN_TOOL } from "./tool-names.ts";
 
 /** EventBus channel on which a caller asks `plan` to enable plan mode. */
 export const PLAN_ENTER_REQUEST = "my-pi-agent/plan-mode/enter";
 
+/** EventBus channel on which a caller asks `plan` to flip the mode. */
+export const PLAN_TOGGLE_REQUEST = "my-pi-agent/plan-mode/toggle";
+
 /** One clause describing the read-only guarantee, reused across prompts. */
 export const READ_ONLY_SUMMARY =
 	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
-	"subagent delegation is forced read-only, and the only file write is write_plan (a plan file in the agent " +
-	"directory)";
+	"subagent delegation is forced read-only, and the only file write is the plan file, saved by the `plan` tool's " +
+	"`write` action in the agent directory";
 
 /**
- * The consent question, as the user sees it. Shown by `enter_plan_mode` and by
- * any caller that offers plan mode itself, so both describe the same guarantee.
+ * The consent question, as the user sees it. Shown by the `plan` tool's `enter`
+ * action and by any caller that offers plan mode itself, so both describe the same
+ * guarantee.
  */
 export const PLAN_CONSENT =
 	`Plan mode is read-only exploration: ${READ_ONLY_SUMMARY}. ` +
@@ -53,12 +57,19 @@ export function planModeRefusal(action: string): string {
 	return `Plan mode is read-only. Approve the plan before ${action}.`;
 }
 
-/** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
-export interface PlanEnterRequest {
+/** What a caller sends on {@link PLAN_ENTER_REQUEST} or {@link PLAN_TOGGLE_REQUEST}. */
+export interface PlanModeRequest {
 	/** The caller's context; `plan` uses it for the footer status. */
 	ctx: ExtensionContext;
 	/** Claimed once, with whether plan mode is on; the caller settles on that claim. */
-	respond(entered: BusAnswer<boolean>): void;
+	respond(enabled: BusAnswer<boolean>): void;
+}
+
+/**
+ * Whether the `plan` extension registered its tool in this session.
+ */
+export function isPlanExtensionLoaded(pi: Pick<ExtensionAPI, "getAllTools">): boolean {
+	return pi.getAllTools().some((tool) => tool.name === PLAN_TOOL);
 }
 
 /**
@@ -74,10 +85,28 @@ export function requestPlanMode(
 	ctx: ExtensionContext,
 ): Promise<boolean> {
 	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) return Promise.resolve(true);
-	if (!pi.getAllTools().some((tool) => tool.name === PLAN_ENTER_TOOL)) return Promise.resolve(false);
-	return requestOverBus<boolean, PlanEnterRequest>(pi, {
+	if (!isPlanExtensionLoaded(pi)) return Promise.resolve(false);
+	return requestOverBus<boolean, PlanModeRequest>(pi, {
 		channel: PLAN_ENTER_REQUEST,
 		payload: (respond) => ({ ctx, respond }),
 		unclaimed: () => false,
 	});
 }
+
+/**
+ * Ask `plan` to flip the mode, and report the state it left behind.
+ *
+ * A toggle has no branch precondition: the owner reads the flag it persisted and
+ * resolves the opposite. `undefined` means nothing is listening (the `plan`
+ * extension is not loaded), so the caller can leave its own key alone.
+ */
+export function requestPlanToggle(
+	pi: Pick<ExtensionAPI, "events">,
+	ctx: ExtensionContext,
+): Promise<boolean | undefined> {
+	return requestOverBus<boolean | undefined, PlanModeRequest>(pi, {
+		channel: PLAN_TOGGLE_REQUEST,
+		payload: (respond) => ({ ctx, respond }),
+		unclaimed: () => undefined,
+	});
+}

package/lib/plans/paths.ts

@@ -0,0 +1,82 @@
+/**
+ * Where a plan lives, and which paths may be read or written as one.
+ *
+ * A plan file is the artifact a card is executed against, so two extensions have to
+ * agree about it: `plan` writes and reads the store, and `board` records the file a
+ * card promises. The store is `<agent-dir>/plans/<repo-key>` for a repository and
+ * `<agent-dir>/plans` outside one — the key is the same one `repo-key.ts` hands
+ * every other per-repository store, which is why the keyed branch lives here rather
+ * than in either caller.
+ *
+ * The rules are one body for the same reason: a copy of `isContainedPlan` that
+ * dropped the symlink half would look identical at a glance and would be the one
+ * that let a link inside the store point outside it. `plan` passes a path here
+ * before it writes; `board` passes the path it is about to record, and asks whether
+ * it is a plan of this repository.
+ *
+ * Value-only: no module state, and the only I/O is the `lstat` a symlink check needs.
+ */
+
+import { lstatSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isInside, isInsideReal } from "../path.ts";
+import type { RepoKey } from "../repo-key.ts";
+
+/** The agent-directory entry plans are filed under. */
+export const PLANS_DIR_NAME = "plans";
+
+/** The plan store: `<agent-dir>/plans`, or `<agent-dir>/plans/<key>` inside a repository. */
+export function plansDir(agentDir: string, key?: string): string {
+	return key === undefined ? join(agentDir, PLANS_DIR_NAME) : join(agentDir, PLANS_DIR_NAME, key);
+}
+
+/**
+ * The store for a resolved repository: keyed when git answered, unkeyed outside one.
+ *
+ * The `fromGit` branch lives here and nowhere else — that is the line a copy gets wrong,
+ * and both the plan tool and the board reach it through this one function.
+ */
+export function plansDirFor(agentDir: string, repo: Pick<RepoKey, "key" | "fromGit">): string {
+	return plansDir(agentDir, repo.fromGit ? repo.key : undefined);
+}
+
+/** A plan file name: markdown and not a dotfile, so the self-ignore file is never a target. */
+export function isPlanFileName(path: string): boolean {
+	const name = basename(path);
+	return name.toLowerCase().endsWith(".md") && !name.startsWith(".");
+}
+
+/**
+ * Whether `path` may be read, written, or deleted as a plan. Beyond lexical
+ * containment (shared with the other path guards through `lib/path.ts`), this
+ * rejects dotfiles (including the directory's own `.gitignore`) and resolves
+ * symlinks, so a link placed inside the plans directory cannot redirect a read
+ * or write outside it.
+ */
+export function isContainedPlan(dir: string, path: string): boolean {
+	if (!isInside(dir, path) || !isPlanFileName(path)) return false;
+	try {
+		// A symlink itself must never be the target; a missing file is a new plan.
+		if (lstatSync(path).isSymbolicLink()) return false;
+	} catch {
+		// Missing (ENOENT) is expected; any other error falls through to the
+		// real-path check, which rejects the path if it cannot be resolved.
+	}
+	return isInsideReal(dir, dirname(path));
+}
+
+/**
+ * Resolve a `plan_path` argument against the store.
+ *
+ * A plan lives outside the project, so a path relative to the working directory
+ * can no longer name one. Absolute paths and the `~/…` form the tools display are
+ * accepted, and a bare name resolves inside the store — which is what a reader of
+ * a tool result has in hand.
+ */
+export function resolvePlanArg(dir: string, planPath: string): string {
+	const text = planPath.trim();
+	if (text === "~") return homedir();
+	if (text.startsWith("~/") || text.startsWith(`~${sep}`)) return resolve(homedir(), text.slice(2));
+	return isAbsolute(text) ? resolve(text) : resolve(dir, text);
+}

package/lib/policy.ts

@@ -10,24 +10,27 @@
  * `write`/`edit` being the only mutators.
  *
  * No host dependency beyond the annotation type: the caller supplies the
- * annotation lookup, and the one reader name comes from `tool-names.ts`, so this
- * module stays value-only.
+ * annotation lookup, the one reader name comes from `tool-names.ts`, and which board
+ * actions read comes from `board/actions.ts`, so this module stays value-only.
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import { BOARD_READ_ACTION, READ_DOC_TOOL } from "./tool-names.ts";
+import { isBoardReadAction } from "./board/actions.ts";
+import { READ_DOC_TOOL } from "./tool-names.ts";
 
 /**
  * Whether a call to the `board` tool only reads it.
  *
- * The board is one tool over ten actions, so its `readOnlyHint` says "may write" and
+ * The board is one tool over many actions, so its `readOnlyHint` says "may write" and
  * cannot answer this. The action can, and it travels in the call's input — and in the
  * result's `details`, which is all a `tool_execution_end` event carries. Plan mode
- * asks before the call and the todo nudge after it, so the answer lives here once.
+ * asks before the call and the todo nudge after it, so the answer lives here once —
+ * and the answer is the board's own table, because an action list kept here is a list
+ * that drifts.
  */
 export function isBoardRead(call: unknown): boolean {
 	if (typeof call !== "object" || call === null) return false;
-	return (call as { action?: unknown }).action === BOARD_READ_ACTION;
+	return isBoardReadAction((call as { action?: unknown }).action);
 }
 
 /**

package/lib/report.ts

@@ -147,8 +147,9 @@ export interface PendingChannelOptions {
  * The order inside `session_start` is the contract: the reporter forgets the
  * previous session's busy window, the runtime loads the records, and only then
  * is the report trigger armed — a reload or a replaced session reuses the same
- * runtime. A shutdown clears the trigger before the runtime releases the table it
- * was calling into.
+ * runtime, so a runtime that can settle an outcome while loading holds what it
+ * settled until this arms. A shutdown clears the trigger before the runtime
+ * releases the table it was calling into.
  */
 export function registerPendingChannel(
 	pi: Pick<ExtensionAPI, "on">,

package/lib/requirements.ts

@@ -322,8 +322,8 @@ export interface ProbeSeams {
 	readJson: (path: string) => JsonReadResult;
 	dirs: DirSeams;
 	platform: NodeJS.Platform;
-	/** Whether the package will actually load this extension this session. */
-	isEnabled: (extension: string) => boolean;
+	/** Why this session is not loading the extension, or undefined when it loads it. */
+	disabledReason: (extension: string) => string | undefined;
 	/** Load an optional package; defaults to a real dynamic import. */
 	loadModule?: (name: string) => Promise<unknown>;
 	/** Resolve the nested-pi command; defaults to {@link getPiInvocation}. */
@@ -718,11 +718,11 @@ function configFindings(extension: string, spec: ExtensionRequirements, seams: P
 /** Probe one extension against its declaration and the current environment. */
 export async function probeExtension(extension: string, seams: ProbeSeams): Promise<ExtensionReport> {
 	const spec = REQUIREMENTS[extension];
-	const enabled = seams.isEnabled(extension);
+	const disabledReason = seams.disabledReason(extension);
 	if (!spec) {
 		return {
 			extension,
-			enabled,
+			enabled: disabledReason === undefined,
 			findings: [
 				{
 					extension,
@@ -733,16 +733,16 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 			],
 		};
 	}
-	if (!enabled) {
+	if (disabledReason !== undefined) {
 		return {
 			extension,
-			enabled,
+			enabled: false,
 			findings: [
 				{
 					extension,
 					check: "state",
 					severity: "info",
-					detail: "disabled through PI_DISABLED_EXTENSIONS",
+					detail: disabledReason,
 				},
 			],
 		};
@@ -755,7 +755,7 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 	for (const note of spec.notes ?? []) {
 		findings.push({ extension, check: "platform", severity: "info", detail: note });
 	}
-	return { extension, enabled, findings };
+	return { extension, enabled: true, findings };
 }
 
 /** Probes in flight at once: enough to hide spawn latency, not a burst. */

package/lib/session-label.ts

@@ -4,11 +4,11 @@
  * Two vocabularies share this module, and neither copies the other. `session-bus`
  * settles its own label for a session that did not ask for one — the Pi session name,
  * else the working directory's basename, else the id. The board names a session for
- * the team instead: the page's seat, or `team-agent-` and the id's tail, which is the
- * same name on every surface and cannot drift when a user renames a session. The rules
- * are here rather than in either extension because a label is a shared vocabulary: it
- * is displayed, it is a send target, and it is stored in a card file that outlives one
- * session.
+ * the team instead: the page's seat, or a preset teammate name drawn from the id, or
+ * `team-agent-` and the id's tail when every preset one is taken — one name on every
+ * surface, and one that cannot drift on a rename. The rules are here rather than in
+ * either extension because a label is a shared vocabulary: it is displayed, it is a
+ * send target, and it is stored in a card file that outlives one session.
  *
  * Value-only: no state, no I/O.
  */
@@ -64,6 +64,70 @@ export function agentLabel(id: string): string {
 	return normalizeLabel(`${TEAM_AGENT_PREFIX}${shortId(id)}`, "team-agent");
 }
 
+/**
+ * The preset teammate names a session with no name of its own draws from.
+ *
+ * Familiar English names, one or two syllables each, short enough to type as a `to`
+ * target: a teammate should read as a person, and `lily` says more than
+ * `team-agent-9f21ac` to the lead who hands it a card.
+ */
+export const TEAMMATE_NAMES = [
+	"tom",
+	"amy",
+	"lily",
+	"jack",
+	"lucy",
+	"mike",
+	"kate",
+	"sam",
+	"bob",
+	"anna",
+	"helen",
+	"peter",
+	"alice",
+	"emma",
+	"jenny",
+	"mary",
+	"linda",
+	"susan",
+	"tina",
+	"ben",
+	"may",
+	"rose",
+	"david",
+	"leo",
+] as const;
+
+/** A 32-bit FNV-1a hash, so one id always starts the draw at the same name. */
+function hashOf(text: string): number {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < text.length; index += 1) {
+		hash ^= text.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return hash >>> 0;
+}
+
+/**
+ * The preset name a session with none of its own joins under.
+ *
+ * Its id hashes to a starting point in the list, and a name in `taken` walks on to the
+ * next free one; every name taken is `undefined`, so the caller keeps a fallback that
+ * cannot collide. Drawn from the id rather than at random, because the board writes a
+ * card before it joins: one session has to draw one name on every call and after a
+ * restart, so the card, the join, and the roster say the same word. `taken` is
+ * compared case-insensitively, the way a label is addressed.
+ */
+export function presetNameFor(id: string, taken: Iterable<string> = []): string | undefined {
+	const held = new Set([...taken].map((label) => label.toLowerCase()));
+	const start = hashOf(id) % TEAMMATE_NAMES.length;
+	for (let step = 0; step < TEAMMATE_NAMES.length; step += 1) {
+		const name = TEAMMATE_NAMES[(start + step) % TEAMMATE_NAMES.length];
+		if (!held.has(name)) return name;
+	}
+	return undefined;
+}
+
 /**
  * Pi's session name, which is the first choice for a label.
  *
@@ -78,3 +142,45 @@ export function sessionNameOf(ctx: Pick<ExtensionContext, "sessionManager">): st
 		return undefined;
 	}
 }
+
+/**
+ * The session's id, or undefined when the host does not report one.
+ *
+ * Read beside the name because they are the same fact from two sides: a name is how a
+ * person reads a session, an id is how one is filed — a bus record, a card's owner, a
+ * resume. A host that refuses the call is a session with no id, not an error.
+ */
+export function sessionIdOf(ctx: Pick<ExtensionContext, "sessionManager">): string | undefined {
+	try {
+		const id = ctx.sessionManager.getSessionId();
+		return typeof id === "string" && id !== "" ? id : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * `pi.events` channel: a session settled the label its peers address it by.
+ *
+ * Here rather than in `lib/events.ts`, the way `lib/plan-entry.ts` and `lib/http/mount.ts`
+ * keep their own: a label is this module's vocabulary, and both sides of the channel — the
+ * bus that settles one and the footer that draws it — already load this module, so the
+ * literal costs a registration graph nothing and cannot be re-typed on one side.
+ */
+export const SESSION_LABEL_CHANNEL = "my-pi-agent/session-label";
+
+/**
+ * Payload on {@link SESSION_LABEL_CHANNEL}: one session's name on the bus.
+ *
+ * Emitted by `session-bus` whenever it settles or yields a label, and read by bytefly's
+ * footer, which draws it instead of Pi's own session name: the two part company the moment
+ * the board seats a session under a preset teammate name, or a collision appends an id. The
+ * id rides along because the channel reaches every session in the process, and only the one
+ * named here is the reader's own.
+ */
+export interface SessionLabelEvent {
+	/** Pi session id the label belongs to. */
+	id: string;
+	/** The name another session addresses this one by. */
+	label: string;
+}