pi-squire 0.9.5 → 0.11.0

package/src/tmux.ts

@@ -13,6 +13,20 @@ export type WindowSpec = {
 /** 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 };
 
+/**
+ * Why a window could not be opened, and whether one may exist anyway:
+ * `not-opened` only when nothing was dispatched to tmux that could create it.
+ * Anything else, a timeout or a malformed answer included, is `unknown`.
+ */
+export class WindowOpenError extends Error {
+	readonly certainty: "not-opened" | "unknown";
+	constructor(message: string, certainty: "not-opened" | "unknown") {
+		super(message);
+		this.name = "WindowOpenError";
+		this.certainty = certainty;
+	}
+}
+
 export interface TmuxClient {
 	/** Whether this process runs in a tmux pane. */
 	insideTmux(): boolean;
@@ -65,11 +79,24 @@ export function createTmuxClient(options: { timeoutMs?: number } = {}): TmuxClie
 		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}`);
-			const session = await targetSession();
+			let session: string | undefined;
+			try {
+				session = await targetSession();
+			} 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);
-			const windowId = (await run(args)).trim();
-			if (windowId === "") throw new Error("tmux reported no window id");
+			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 windowId = out.trim();
+			if (!/^@[0-9]+$/.test(windowId)) throw new WindowOpenError("tmux reported an invalid window id", "unknown");
 			return windowId;
 		},
 

package/src/tracking-attempt.ts

@@ -0,0 +1,65 @@
+import { Type } from "typebox";
+import { WorktreePlanSchema } from "./workspace.ts";
+
+const ATTEMPT_PHASES = ["planned", "created", "rolled-back", "retained", "interrupted"] as const;
+
+const ResourceSchema = Type.Union(
+	[
+		Type.Object({ kind: Type.Literal("none") }),
+		Type.Object({ kind: Type.Literal("branch"), branch: Type.String(), head: Type.String() }),
+		Type.Object({ kind: Type.Literal("worktree"), cwd: Type.String(), branch: Type.String(), head: Type.String() }),
+		Type.Object({
+			kind: Type.Literal("unknown"),
+			reason: Type.String(),
+			observedPaths: Type.Array(Type.String()),
+			observedRefs: Type.Array(Type.String()),
+		}),
+	],
+	{ description: "What is known to exist for a launch that has no window, as facts." },
+);
+
+const AttemptStateSchema = Type.Union([
+	Type.Object({ phase: Type.Literal("planned"), resources: ResourceSchema }),
+	Type.Object({ phase: Type.Literal("created"), resources: ResourceSchema }),
+	Type.Object({
+		phase: Type.Literal("rolled-back"),
+		resources: Type.Object({ kind: Type.Literal("none") }),
+		cause: Type.String(),
+	}),
+	Type.Object({
+		phase: Type.Literal("retained"),
+		resources: ResourceSchema,
+		cause: Type.String(),
+		recovery: Type.Array(Type.String(), {
+			description: "Non-forced commands that remove exactly the resources known to remain.",
+		}),
+	}),
+	Type.Object({
+		phase: Type.Literal("interrupted"),
+		resources: ResourceSchema,
+		lastPhase: Type.Union([Type.Literal("planned"), Type.Literal("created")]),
+		reason: Type.String(),
+	}),
+]);
+
+/** A managed launch that has no window: never running, never closable, with no window id. */
+export const AttemptSchema = Type.Object({
+	kind: Type.Literal("workspace-attempt"),
+	id: Type.String(),
+	parentId: Type.String(),
+	agent: Type.String(),
+	model: Type.String(),
+	thinking: Type.String(),
+	name: Type.Optional(Type.String()),
+	sessionDir: Type.String(),
+	plan: WorktreePlanSchema,
+	attempt: AttemptStateSchema,
+	requestId: Type.Optional(Type.String({ description: "The task's request id, only when mail really returned one." })),
+	state: Type.Union(
+		ATTEMPT_PHASES.map((phase) => Type.Literal(phase)),
+		{
+			description:
+				"planned, created: a launch in progress. rolled-back: failed before a window and everything was removed. retained: failed before a window and something remains (see attempt.recovery). interrupted: the parent ended mid-launch; what exists is unknown. No window was opened.",
+		},
+	),
+});

package/src/tracking-text.ts

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

package/src/tracking.ts

@@ -8,18 +8,26 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 
 import { type Mark, readMarks } from "./limits.ts";
-import { modelLabel } from "./render.ts";
+import { attemptLines, cwdLine, modelLabel, snapshotLines, workspaceLine } from "./render.ts";
 import {
 	type DelegationState,
 	deriveState,
-	findSession,
+	isStarted,
+	locateSession,
 	type Recorded,
 	type Results,
 	recordedName,
+	type StartedRecorded,
+	sessionIdOf,
 	type WindowState,
+	type WorkspaceAttempt,
 } from "./results.ts";
+import { inspectWorkspace, type WorkspaceSnapshot, WorkspaceSnapshotSchema } from "./snapshot.ts";
 import type { TmuxClient, TmuxWindow } from "./tmux.ts";
+import { AttemptSchema } from "./tracking-attempt.ts";
+import { ago, autoExitLine, stateLine } from "./tracking-text.ts";
 import type { ReadingError } from "./usage.ts";
+import { WorkspaceSchema } from "./workspace.ts";
 
 /** The hook a tick emits so the provider claims waiting replies before windows are checked. */
 const SCAN = "message:scan";
@@ -49,10 +57,11 @@ export function toolResult(
 /** Every tool here touches only local state: tmux, the session's entries and files under the agent directory. */
 const CLOSED_WORLD = { openWorldHint: false } as const;
 
-const DELEGATION_STATES: readonly DelegationState[] = ["closed", "done", "gone", "running", "window-closed", "unknown"];
+const STARTED_STATES = ["closed", "done", "gone", "running", "window-closed", "unknown"] as const;
 
-/** One delegation in `delegation_status`'s structured result; `viewDetails` builds it. */
-const DelegationSchema = Type.Object({
+/** One started delegation in `delegation_status`'s structured result; `viewDetails` builds it. */
+const StartedSchema = Type.Object({
+	kind: Type.Literal("started"),
 	id: Type.String(),
 	name: Type.String(),
 	agent: Type.String(),
@@ -62,13 +71,20 @@ const DelegationSchema = Type.Object({
 	),
 	thinking: Type.String(),
 	autoExit: Type.Boolean(),
+	resumedFrom: Type.Optional(Type.String({ description: "The delegation whose session this one reopened." })),
 	windowId: Type.String(),
 	windowName: Type.String(),
+	cwd: Type.Optional(
+		Type.String({ description: "The directory its window opened in; absent for records from before it was kept." }),
+	),
+	sessionDir: Type.Optional(Type.String({ description: "The session-storage directory it was told to use." })),
+	workspace: Type.Optional(WorkspaceSchema),
+	workspaceSnapshot: WorkspaceSnapshotSchema,
 	state: Type.Union(
-		DELEGATION_STATES.map((state) => Type.Literal(state)),
+		STARTED_STATES.map((state) => Type.Literal(state)),
 		{
 			description:
-				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final; gone and window-closed turn done if a late reply arrives.",
+				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final, though a later delegation_resume continues one as a new delegation; gone and window-closed turn done if a late reply arrives.",
 		},
 	),
 	closed: Type.Boolean(),
@@ -81,6 +97,8 @@ const DelegationSchema = Type.Object({
 	),
 });
 
+const DelegationSchema = Type.Union([StartedSchema, AttemptSchema]);
+
 export const StatusSchema = Type.Object({
 	delegations: Type.Array(DelegationSchema),
 	marks: Type.Array(
@@ -104,7 +122,7 @@ export const CloseSchema = Type.Object({
 });
 
 /** A tool as registered; `execute` takes the tool's own parameters, which the registration call does not check. */
-type ToolDef = {
+export type ToolDef = {
 	name: string;
 	label: string;
 	description: string;
@@ -115,7 +133,7 @@ type ToolDef = {
 };
 
 /** Every window on the server, asked once; a failed ask is `undefined`, never an empty list. */
-async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined> {
+export async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined> {
 	try {
 		return await tmux.listWindows();
 	} catch {
@@ -124,64 +142,40 @@ async function listWindows(tmux: TmuxClient): Promise<TmuxWindow[] | undefined>
 }
 
 /** The window a delegation owns: one with both its recorded id and its recorded name, since ids restart with every tmux server. */
-function ownWindow(windows: TmuxWindow[], record: Recorded): TmuxWindow | undefined {
+export function ownWindow(windows: TmuxWindow[], record: StartedRecorded): TmuxWindow | undefined {
 	return windows.find((window) => window.id === record.windowId && window.name === record.windowName);
 }
 
 /** What the listing says about a delegation's window; a matching window whose program exited counts as gone. */
-function windowState(windows: TmuxWindow[] | undefined, record: Recorded): WindowState {
+export function windowState(windows: TmuxWindow[] | undefined, record: StartedRecorded): WindowState {
 	if (windows === undefined) return "unknown";
 	const own = ownWindow(windows, record);
 	return own !== undefined && !own.exited ? "open" : "gone";
 }
 
-/** Records from before auto-exit existed kept their windows open, so they read off. */
-function autoExitLine(record: Recorded): string {
-	return record.autoExit === true
-		? "on — the delegate closes its window after a normal completion unless the user took over there"
-		: "off — the window stays open after the result";
-}
-
-/** The state, worded for the `state:` line. */
-function stateLine(state: DelegationState, record: Recorded): string {
-	switch (state) {
-		case "running":
-			return "running — the window is open and no result has arrived";
-		case "gone":
-			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
-		case "done":
-			return `done — result status: ${record.result?.status ?? "unknown"}; the result reaches this session as a [delegate] message on its own`;
-		case "closed":
-			return "closed — delegation_close recorded it";
-		case "window-closed":
-			return "closed — the window is gone";
-		case "unknown":
-			return "unknown — tmux could not be asked whether the window is open";
-	}
-}
-
 /** One delegation as `delegation_status` reports it; its text and details both read from this. */
 type View = {
-	record: Recorded;
+	record: StartedRecorded;
 	state: DelegationState;
 	name: string;
 	sessionPath: string | undefined;
 	/** When the session file was last written; set only for a running delegation with a file. */
 	lastActive: Date | undefined;
+	/** The checkout observed for this status call; the recorded result keeps its own. */
+	snapshot: WorkspaceSnapshot;
+	/** The delegation that resumed this one, if any. */
+	resumedAs: string | undefined;
 };
 
-/** How long ago, worded for the `state:` line: `just now`, `N min ago` or `N h M min ago`. */
-function ago(ms: number): string {
-	const minutes = Math.floor(ms / 60_000);
-	if (minutes < 1) return "just now";
-	if (minutes < 60) return `${minutes} min ago`;
-	return `${Math.floor(minutes / 60)} h ${minutes % 60} min ago`;
-}
-
 /** The view of a delegation: its state and the fields the text and details share. */
-function view(record: Recorded, windows: TmuxWindow[] | undefined, ctx: ExtensionContext): View {
+function view(
+	record: StartedRecorded,
+	windows: TmuxWindow[] | undefined,
+	ctx: ExtensionContext,
+	resumedAs: string | undefined,
+): View {
 	const state = deriveState(record, windowState(windows, record));
-	const sessionPath = record.result?.sessionPath ?? findSession(ctx.sessionManager.getSessionDir(), record.id);
+	const sessionPath = locateSession(record, ctx.sessionManager.getSessionDir());
 	let lastActive: Date | undefined;
 	if (state === "running" && sessionPath !== undefined) {
 		try {
@@ -190,27 +184,36 @@ function view(record: Recorded, windows: TmuxWindow[] | undefined, ctx: Extensio
 			// a failed stat counts as no file
 		}
 	}
-	return { record, state, name: recordedName(record), sessionPath, lastActive };
+	const snapshot = inspectWorkspace(record.workspace?.cwd, record.workspace?.git);
+	return { record, state, name: recordedName(record), sessionPath, lastActive, snapshot, resumedAs };
 }
 
 /** The text block for one delegation. */
-function viewText({ record, state, name, sessionPath, lastActive }: View): string {
+function viewText({ record, state, name, sessionPath, lastActive, snapshot, resumedAs }: View): string {
+	const [checkout, ...categories] = snapshotLines(snapshot);
 	const seen = lastActive === undefined ? "" : ` (last active ${ago(Date.now() - lastActive.getTime())})`;
 	const lines = [
 		`${record.id} ${record.agent} (${modelLabel(record.model, record.result?.finishedModel)}, thinking ${record.thinking})`,
 		`  name: ${name}`,
+		...(record.resumedFrom === undefined ? [] : [`  resumed from ${record.resumedFrom}`]),
+		...(resumedAs === undefined ? [] : [`  resumed as ${resumedAs}`]),
 		`  state: ${stateLine(state, record)}${seen}`,
 		`  window: ${record.windowName} (${record.windowId})`,
+		`  cwd: ${cwdLine(record.cwd)}`,
+		...(record.workspace === undefined ? [] : [`  workspace: ${workspaceLine(record.workspace)}`]),
+		`  checkout now: ${checkout}`,
+		...categories.map((line) => `    ${line}`),
 		`  auto-exit: ${autoExitLine(record)}`,
-		`  session: ${sessionPath ?? `${record.id} (no session file yet)`}`,
+		`  session: ${sessionPath ?? `${sessionIdOf(record)} (no session file yet)`}`,
 	];
 	if (record.result !== undefined) lines.push(`  envelope: ${record.result.envelopePath}`);
 	return lines.join("\n");
 }
 
 /** The structured details for one delegation. */
-function viewDetails({ record, state, name, sessionPath, lastActive }: View): Record<string, unknown> {
+function viewDetails({ record, state, name, sessionPath, lastActive, snapshot }: View): Record<string, unknown> {
 	return {
+		kind: "started",
 		id: record.id,
 		name,
 		agent: record.agent,
@@ -218,8 +221,13 @@ function viewDetails({ record, state, name, sessionPath, lastActive }: View): Re
 		...(record.result?.finishedModel === undefined ? {} : { finishedModel: record.result.finishedModel }),
 		thinking: record.thinking,
 		autoExit: record.autoExit === true,
+		...(record.resumedFrom === undefined ? {} : { resumedFrom: record.resumedFrom }),
 		windowId: record.windowId,
 		windowName: record.windowName,
+		...(record.cwd === undefined ? {} : { cwd: record.cwd }),
+		...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
+		...(record.workspace === undefined ? {} : { workspace: record.workspace }),
+		workspaceSnapshot: snapshot,
 		state,
 		closed: record.closed === true,
 		closedWithoutResult: record.gone === true && record.result === undefined && record.closed !== true,
@@ -230,6 +238,16 @@ function viewDetails({ record, state, name, sessionPath, lastActive }: View): Re
 	};
 }
 
+/** One unstarted attempt as the status text words it. */
+function attemptText(record: WorkspaceAttempt): string {
+	return [
+		`${record.id} ${record.agent} (${modelLabel(record.model, undefined)}, thinking ${record.thinking})`,
+		`  name: ${recordedName(record)}`,
+		`  state: ${record.attempt.phase} — no window id/start was recorded; a window may still exist (close requires a verified window id)`,
+		...attemptLines(record).map((line) => `  ${line}`),
+	].join("\n");
+}
+
 /** The usage-limit marks in force now, as `delegation_status` reports them. */
 function activeMarks(): { scope: string; source: Mark["source"]; reason: string; clearsAt: string }[] {
 	const now = Date.now();
@@ -325,7 +343,7 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		name: "delegation_status",
 		label: "Delegation status",
 		description:
-			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
+			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, working directory, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
 		parameters: Type.Object({
 			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
 		}),
@@ -340,10 +358,19 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		): Promise<ReturnType<typeof toolResult>> {
 			const records = selectRecords(results, params.id);
 			const windows = await listWindows(tmux);
-			const views = records.map((record) => view(record, windows, ctx));
+			const resumedAs = (id: string) => results.list().find((item) => isStarted(item) && item.resumedFrom === id)?.id;
+			const views = records.map((record) =>
+				isStarted(record) ? view(record, windows, ctx, resumedAs(record.id)) : record,
+			);
 			const marks = activeMarks();
 			const errors = readingErrors();
-			const details = { delegations: views.map(viewDetails), marks, readingErrors: errors };
+			const details = {
+				delegations: views.map((item) =>
+					"record" in item ? viewDetails(item) : { ...item, state: item.attempt.phase },
+				),
+				marks,
+				readingErrors: errors,
+			};
 			const block =
 				marks.length === 0 && errors.length === 0
 					? []
@@ -358,7 +385,10 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 			const parts =
 				views.length === 0
 					? ["No delegations are recorded in this session.", ...block]
-					: [`${heading}\n\n${views.map(viewText).join("\n\n")}`, ...block];
+					: [
+							`${heading}\n\n${views.map((item) => ("record" in item ? viewText(item) : attemptText(item))).join("\n\n")}`,
+							...block,
+						];
 			return toolResult(parts.join("\n\n"), details);
 		},
 	};
@@ -385,6 +415,11 @@ function closeTool(results: Results, tmux: TmuxClient): ToolDef {
 			_ctx: ExtensionContext,
 		): Promise<ReturnType<typeof toolResult>> {
 			const [record] = selectRecords(results, params.id);
+			if (!isStarted(record)) {
+				throw new Error(
+					`delegation ${record.id} is a workspace attempt (${record.attempt.phase}): no verified window id was recorded; a window may still exist, so close is unavailable`,
+				);
+			}
 			const closed = (alreadyClosed: boolean, killed: boolean) => ({
 				id: record.id,
 				windowId: record.windowId,