@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/{lib/claims → extensions/session-bus}/overlap.ts

@@ -1,20 +1,23 @@
 /**
  * Claim overlap (pure).
  *
- * Two things in this package need the same answer to "do these paths collide?":
- * `session-bus` when a session claims a path, and plan approval when a proposed
- * split names its units. They must agree, because a split that passes validation
- * and then conflicts at claim time — or the reverse — teaches the user that a
- * claim is arbitrary. So the predicate lives here once and both call it.
+ * The bus's one answer to "do these paths collide?": the runtime checks it before
+ * a claim is written, and the store checks it when a claim is read back. Two
+ * copies would let a claim succeed here and read back as a conflict there, which
+ * teaches the user that a claim is arbitrary.
+ *
+ * One export. `normalizeClaimPath` is the predicate's own step — a spellings rule
+ * with a single caller, inside this module — so a caller cannot normalize a path
+ * one way and compare it another.
  *
  * A claim on a directory covers every file below it, in either direction, and a
- * claim is always a repository-relative, posix-separated path: the caller
- * normalizes first, because a Windows spelling (`a\b`) and a posix one (`a/b`)
+ * claim is always a repository-relative, posix-separated path: both sides are
+ * normalized here, because a Windows spelling (`a\b`) and a posix one (`a/b`)
  * naming the same file must not read as two claims.
  */
 
 /** A repository-relative path with one separator and no trailing slash. */
-export function normalizeClaimPath(raw: string): string {
+function normalizeClaimPath(raw: string): string {
 	const posix = raw.trim().replace(/\\/g, "/");
 	const trimmed = posix
 		.replace(/^\.\//, "")
@@ -31,13 +34,3 @@ export function claimsConflict(a: string, b: string): boolean {
 	if (left === "" || right === "") return true;
 	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }
-
-/** The first two prefixes in `paths` that collide, if any. */
-export function findClaimOverlap(paths: readonly string[]): [string, string] | undefined {
-	for (let i = 0; i < paths.length; i++) {
-		for (let j = i + 1; j < paths.length; j++) {
-			if (claimsConflict(paths[i], paths[j])) return [paths[i], paths[j]];
-		}
-	}
-	return undefined;
-}

package/extensions/session-bus/protocol.ts

@@ -6,63 +6,41 @@
  */
 
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { sanitizeLine } from "../../lib/format.ts";
+import { MAX_MESSAGE_TEXT } from "../../lib/session-tool.ts";
+import { SESSION_TOOL } from "../../lib/tool-names.ts";
 
-export const TOOL_NAME = "session";
+/**
+ * The label rules live in `lib/` because a label is shared vocabulary: the board
+ * records one on a card it claims, and `session-bus` settles the one it is
+ * addressed by. Re-exported here so every module in this extension keeps
+ * importing its rules from the protocol they belong to.
+ */
+export { defaultLabel, MAX_LABEL, normalizeLabel, shortId } from "../../lib/session-label.ts";
+
+export const TOOL_NAME = SESSION_TOOL;
 export const COMMAND_NAME = "sessions";
-export const MAX_TEXT = 4_000;
+/**
+ * The text cap, from `lib/session-tool.ts`, where the callers that clip to it live.
+ * Re-exported the way the label rules are, so this extension imports its protocol's
+ * constants from one place and two extensions cannot drift apart on the number.
+ */
+export const MAX_TEXT = MAX_MESSAGE_TEXT;
 export const MAX_PATHS = 20;
-export const MAX_LABEL = 40;
 export const DEFAULT_LIMIT = 20;
 export const MAX_LIMIT = 50;
 
 export type SessionMode = "tui" | "rpc" | "json" | "print" | "unknown";
-export type SessionAction = "status" | "send" | "inbox" | "claim" | "release" | "join" | "leave" | "watch" | "name";
+export type SessionAction = "status" | "send" | "inbox" | "claim" | "release" | "join";
 export type MessageKind = "message" | "event" | "ask" | "handoff";
 
-const ACTIONS: readonly SessionAction[] = [
-	"status",
-	"send",
-	"inbox",
-	"claim",
-	"release",
-	"join",
-	"leave",
-	"watch",
-	"name",
-];
+const ACTIONS: readonly SessionAction[] = ["status", "send", "inbox", "claim", "release", "join"];
 const KINDS: readonly MessageKind[] = ["message", "event", "ask", "handoff"];
 
-/** Only a terminal session is visible on the bus before it asks to join. */
-export function isAutoJoinMode(mode: string | undefined): boolean {
-	return mode === "tui";
-}
-
 /** The session mode as the record stores it. */
 export function sessionMode(mode: string | undefined): SessionMode {
 	return mode === "tui" || mode === "rpc" || mode === "json" || mode === "print" ? mode : "unknown";
 }
 
-/** A safe label, used both for display and as a target. */
-export function normalizeLabel(raw: string | undefined, fallback: string): string {
-	const text = sanitizeLine(raw ?? "")
-		.replace(/\s+/g, " ")
-		.trim();
-	return (text || fallback).slice(0, MAX_LABEL);
-}
-
-/** A short, display-only suffix for a session id. */
-export function shortId(id: string): string {
-	const clean = id.replace(/[^a-zA-Z0-9]/g, "");
-	return (clean || id).slice(-6);
-}
-
-/** The automatic label before uniqueness is applied. */
-export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
-	const base = normalizeLabel(sessionName, normalizeLabel(cwd.split(/[\\/]/).filter(Boolean).at(-1), "session"));
-	return normalizeLabel(base, `session-${shortId(id)}`);
-}
-
 /** An action, or undefined when the model sent an unknown one. */
 export function normalizeAction(raw: unknown): SessionAction | undefined {
 	return typeof raw === "string" && ACTIONS.includes(raw as SessionAction) ? (raw as SessionAction) : undefined;
@@ -105,14 +83,6 @@ export function normalizePaths(repoRoot: string, cwd: string, raw: unknown): { p
 	return { paths };
 }
 
-/**
- * Whether one claim covers the other path in either direction.
- *
- * The predicate is `lib/claims/overlap.ts`, because plan approval validates a
- * split with the same question; a second copy here is how the two answers drift.
- */
-export { claimsConflict } from "../../lib/claims/overlap.ts";
-
 /** Resolve `to` to active sessions; `*` is broadcast and excludes the sender. */
 export function resolveRecipients(
 	sessions: readonly { id: string; label: string }[],

package/extensions/session-bus/resolve.ts

@@ -0,0 +1,67 @@
+/**
+ * A claim path as the store keeps it: repository-relative, posix, canonical.
+ *
+ * A path is data — it is resolved against the repository root, and canonicalised
+ * through its real target before it is compared or stored — so a symlinked
+ * spelling inside the repository and the file it names are one claim, and a path
+ * that leaves the repository is refused before anything is written.
+ *
+ * `lib/path.ts` owns the containment predicates; this owns the claim's shape.
+ */
+
+import { isAbsolute, join, relative, sep } from "node:path";
+import { isInside, realPathOfNearest } from "../../lib/path.ts";
+
+/** A path this module declined, with the reason a caller can print. */
+export interface ClaimPathError {
+	/** The path as the caller passed it, so a refusal names what it read. */
+	path: string;
+	/** Why it cannot be a claim. */
+	reason: string;
+}
+
+/** Every path resolved and deduplicated, or the first one refused. */
+export type ResolvedClaimPaths = { paths: string[] } | { error: ClaimPathError };
+
+/**
+ * The wording of the one refusal, shared so approval and the bus cannot phrase it
+ * two ways: the caller prefixes the subject it knows (a unit, or a session's call).
+ */
+export function claimPathMessage(error: ClaimPathError): string {
+	return `path "${error.path}" ${error.reason}.`;
+}
+
+/**
+ * What the root itself resolves to, which is never a claim: it would cover every
+ * file in the repository, so a unit that lists it owns the repository.
+ */
+const ROOT_ITSELF = "is the repository, not a path in it";
+
+/** What a path outside the root resolves to. */
+const OUTSIDE = "does not resolve to a file in the repository";
+
+/** What an absolute path is refused for: it is not the claim's to place. */
+const ABSOLUTE = "is absolute; a claim is relative to the repository root";
+
+/**
+ * Resolve `paths` against `root`, or refuse the first one that is not in it.
+ *
+ * A path that does not exist yet is accepted: `realPathOfNearest` resolves the
+ * nearest existing ancestor, so a unit may name the directory its work creates.
+ */
+export function resolveClaimPaths(root: string, paths: readonly string[]): ResolvedClaimPaths {
+	const realRoot = realPathOfNearest(root);
+	const canonical: string[] = [];
+	for (const path of paths) {
+		// `join` would re-root an absolute path under the repository, which is not what
+		// a caller meant: refuse it rather than claim a directory it never named.
+		if (isAbsolute(path)) return { error: { path, reason: ABSOLUTE } };
+		const target = realPathOfNearest(join(root, path));
+		const rel = relative(realRoot, target);
+		if (rel === "") return { error: { path, reason: ROOT_ITSELF } };
+		if (!isInside(realRoot, target)) return { error: { path, reason: OUTSIDE } };
+		const normalized = rel.split(sep).join("/");
+		if (!canonical.includes(normalized)) canonical.push(normalized);
+	}
+	return { paths: canonical };
+}

package/extensions/session-bus/result.ts

@@ -97,21 +97,7 @@ export function resultSections(details: SessionDetails): TailResultInput<BusRow>
 				],
 			};
 		}
-		case "join": {
-			const conflicts = details.conflicts ?? [];
-			const claimed = details.claimed ?? [];
-			const rows: BusRow[] = [
-				...conflicts.map((claim) => ({ kind: "claim" as const, claim })),
-				...claimed.map((label) => ({ kind: "result" as const, label, tone: "ok" as const })),
-			];
-			if (rows.length === 0) return undefined;
-			return {
-				kind: "sections",
-				sections: [section(rows, conflicts.length > 0 ? "Conflicts" : "Claimed")],
-			};
-		}
-		case "release":
-		case "leave": {
+		case "release": {
 			const released = details.released ?? [];
 			const notOwned = details.notOwned ?? [];
 			const sections: TailSection<BusRow>[] = [];
@@ -141,9 +127,7 @@ export function resultSections(details: SessionDetails): TailResultInput<BusRow>
 				sections: [section(delivered.map((label) => ({ kind: "result", label, tone: "ok" })))],
 			};
 		}
-		case "watch":
-			return undefined;
-		case "name":
+		case "join":
 			return undefined;
 	}
 }
@@ -164,11 +148,14 @@ export function collapsedLine(theme: Theme, details: SessionDetails): string {
 			const cells = [count(board.length, "session")];
 			if (unread > 0) cells.push(`${unread} unread`);
 			cells.push(count(claims, "claim"));
-			const units = details.status?.units;
-			if (units) cells.push(`${units.joined}/${units.total} units`);
 			const watching = details.status?.watching;
 			if (watching) cells.push(watching.wake ? "watch wake" : "watch on");
-			return paint(theme, "meta", cells.join(sep));
+			const line = paint(theme, "meta", cells.join(sep));
+			// A reader that has not joined is looking at a bus it is not on.
+			if (details.status?.onBus === false) {
+				return `${line}${paint(theme, "faint", sep)}${paint(theme, "warn", "not on the bus \u2014 session join puts you on it")}`;
+			}
+			return line;
 		}
 		case "send": {
 			const delivered = details.delivered ?? [];
@@ -198,26 +185,7 @@ export function collapsedLine(theme: Theme, details: SessionDetails): string {
 			if (claimed.length === 0) return paint(theme, "meta", "Claimed nothing");
 			return paint(theme, "ok", `Claimed ${claimed.map((path) => sanitizeLine(path)).join(", ")}`);
 		}
-		case "join": {
-			const conflicts = details.conflicts ?? [];
-			const where = [details.team, details.unit]
-				.filter(Boolean)
-				.map((value) => sanitizeLine(value as string))
-				.join("/");
-			if (conflicts.length > 0) {
-				const [first] = conflicts;
-				const owner = first ? sanitizeLine(first.ownerLabel) : "a peer";
-				return paint(
-					theme,
-					"warn",
-					`Could not join ${where}${sep}${count(conflicts.length, "conflict")} held by ${owner}`,
-				);
-			}
-			const claimed = details.claimed ?? [];
-			return paint(theme, "ok", `Joined ${where}${sep}claimed ${claimed.map((path) => sanitizeLine(path)).join(", ")}`);
-		}
-		case "release":
-		case "leave": {
+		case "release": {
 			const released = details.released ?? [];
 			const notOwned = details.notOwned ?? [];
 			const parts: string[] = [];
@@ -228,16 +196,13 @@ export function collapsedLine(theme: Theme, details: SessionDetails): string {
 			}
 			return parts.length > 0 ? parts.join(paint(theme, "faint", sep)) : paint(theme, "meta", "Nothing to release");
 		}
-		case "watch": {
-			const armed = details.watching?.armed === true;
-			if (!armed) return paint(theme, "meta", "Inbox watch off");
-			return paint(
-				theme,
-				"ok",
-				details.watching?.wake === true ? "Inbox watch on: new mail wakes a turn" : "Inbox watch on",
-			);
+		case "join": {
+			const label = paint(theme, "ok", sanitizeLine(details.label ?? ""));
+			const state =
+				details.watching?.armed !== true
+					? paint(theme, "meta", "not listening")
+					: paint(theme, "meta", details.watching.wake === true ? "listening, wake" : "listening");
+			return `${label}${paint(theme, "faint", sep)}${state}`;
 		}
-		case "name":
-			return paint(theme, "ok", `Named this session "${sanitizeLine(details.label ?? "")}"`);
 	}
 }

package/extensions/session-bus/rows.ts

@@ -14,7 +14,8 @@ import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { listRow, statusRow } from "../../lib/tui/rows.ts";
 import type { TailRowLine } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
-import { shortId } from "./format.ts";
+import { idSuffix } from "./format.ts";
+import type { RosterState } from "../../lib/session-roster.ts";
 import type { BusMessage, ClaimRecord, SessionRecord, SessionStatus } from "./types.ts";
 
 /** Claim paths the focus block lists before it points at the pane. */
@@ -27,7 +28,7 @@ export function count(n: number, noun: string): string {
 
 /** One session on the board, with the claims it holds. */
 export interface SessionRow {
-	session: SessionRecord & { unread: number };
+	session: SessionRecord & { unread: number; state: RosterState };
 	/** Whether this row is the session reading the board. */
 	self: boolean;
 	claims: ClaimRecord[];
@@ -69,7 +70,7 @@ export function sessionRowLine(
 	options: { selected?: boolean; marker?: boolean } = {},
 ): string {
 	const label = `${sanitizeLine(row.session.label)}${row.self ? " · you" : ""}`;
-	const counts = [`${row.session.unread} unread`];
+	const counts = [row.session.state === "gone" ? "gone" : `${row.session.unread} unread`];
 	if (row.claims.length > 0) counts.push(count(row.claims.length, "claim"));
 	return listRow(theme, width, {
 		selected: options.selected === true,
@@ -143,13 +144,17 @@ export function summaryCells(
 	theme: Theme,
 	rows: readonly SessionRow[],
 	watching: { armed: boolean; wake: boolean } | undefined,
+	onBus = true,
 ): string[] {
 	const unread = rows.reduce((total, row) => total + row.session.unread, 0);
 	const claims = rows.reduce((total, row) => total + row.claims.length, 0);
+	const gone = rows.filter((row) => row.session.state === "gone").length;
 	const cells = [paint(theme, "meta", count(rows.length, "session"))];
+	if (gone > 0) cells.push(paint(theme, "bad", `${gone} gone`));
 	if (unread > 0) cells.push(paint(theme, "label", `${unread} unread`));
 	cells.push(paint(theme, "meta", count(claims, "claim")));
 	if (watching) cells.push(paint(theme, "ok", watching.wake ? "watch wake" : "watch on"));
+	if (!onBus) cells.push(paint(theme, "warn", "not on the bus"));
 	return cells;
 }
 
@@ -162,8 +167,9 @@ export function sessionDetailBlock(row: SessionRow, now: number): string[] {
 		lines.push(`claims: ${shown.join(", ")}${hidden > 0 ? ` +${hidden} more` : ""}`);
 	}
 	lines.push(
-		`mode: ${sanitizeLine(row.session.mode)}${SEPARATORS.item}id: ${shortId(row.session.id)}` +
-			`${SEPARATORS.item}last seen: ${formatDuration(Math.max(0, now - row.session.lastSeen))} ago`,
+		`mode: ${sanitizeLine(row.session.mode)}${SEPARATORS.item}id: ${idSuffix(row.session.id)}` +
+			`${SEPARATORS.item}last seen: ${formatDuration(Math.max(0, now - row.session.lastSeen))} ago` +
+			`${row.session.state === "gone" ? `${SEPARATORS.item}process gone` : ""}`,
 	);
 	return lines;
 }