pi-sessions 0.8.0 → 0.10.0

package/extensions/shared/session-index/lineage.ts

@@ -30,7 +30,6 @@ const SESSION_LINEAGE_QUERY_ROW_SCHEMA = Type.Object({
   parentSessionId: NULLABLE_STRING_SCHEMA,
   sessionOrigin: Type.Union([SESSION_ORIGIN_SCHEMA, Type.Null()]),
   handoffGoal: NULLABLE_STRING_SCHEMA,
-  handoffNextTask: NULLABLE_STRING_SCHEMA,
 });
 
 const SESSION_RELATED_QUERY_ROW_SCHEMA = Type.Intersect([
@@ -66,7 +65,6 @@ function sessionLineageColumns(alias?: string): string {
     `${prefix}parent_session_id as parentSessionId`,
     `${prefix}session_origin as sessionOrigin`,
     `${prefix}handoff_goal as handoffGoal`,
-    `${prefix}handoff_next_task as handoffNextTask`,
   ].join(",\n          ");
 }
 
@@ -85,7 +83,6 @@ function buildSessionLineageRow(
     parentSessionId: row.parentSessionId ?? undefined,
     sessionOrigin: row.sessionOrigin ?? undefined,
     handoffGoal: row.handoffGoal ?? undefined,
-    handoffNextTask: row.handoffNextTask ?? undefined,
   };
 }
 

package/extensions/shared/session-index/schema.ts

@@ -47,7 +47,6 @@ export function initializeSchema(db: SessionIndexDatabase): void {
       parent_session_id TEXT,
       session_origin TEXT,
       handoff_goal TEXT,
-      handoff_next_task TEXT,
       indexed_file_size INTEGER,
       indexed_file_mtime_ms INTEGER,
       indexed_file_anchor TEXT,

package/extensions/shared/session-index/scoring.ts

@@ -6,8 +6,7 @@ const RECENCY_HALF_LIFE_DAYS = 21;
 
 const TEXT_SOURCE_WEIGHTS = new Map<string, number>([
   ["session_name", 360],
-  ["handoff_next_task", 300],
-  ["handoff_goal", 260],
+  ["handoff_goal", 300],
   ["user_text", 180],
   ["assistant_text", 150],
   ["bash_command", 140],

package/extensions/shared/session-index/search.ts

@@ -19,6 +19,7 @@ import {
   type SearchSessionsParams,
   type SearchSort,
   type SessionIndexDatabase,
+  type SessionKind,
   type SessionLineageRelation,
   sanitizeFilterValues,
   tokenizeSearchText,
@@ -51,7 +52,6 @@ const SESSION_LIST_ROW_SCHEMA = Type.Object({
   firstUserPrompt: NULLABLE_STRING_SCHEMA,
   sessionOrigin: Type.Union([SESSION_ORIGIN_SCHEMA, Type.Null()]),
   handoffGoal: NULLABLE_STRING_SCHEMA,
-  handoffNextTask: NULLABLE_STRING_SCHEMA,
 });
 
 type SessionListRow = Static<typeof SESSION_LIST_ROW_SCHEMA>;
@@ -88,6 +88,7 @@ interface SearchWhereFilters {
   repo: string | undefined;
   touched: string[];
   changed: string[];
+  kind: SessionKind | undefined;
   excludeSessionIds: string[];
   includeSessionIds: string[] | undefined;
 }
@@ -202,6 +203,7 @@ function buildSearchFilters(params: SearchSessionsParams): SearchFilters {
     repo: params.repo?.trim(),
     touched: sanitizeFilterValues(params.touched),
     changed: sanitizeFilterValues(params.changed),
+    kind: params.kind,
     limit: normalizeResultLimit(params.limit),
     sort: normalizeSort(params.sort),
     query: params.query?.trim() || undefined,
@@ -258,8 +260,7 @@ function getFilteredSessionCandidates(
             s.parent_session_id as parentSessionId,
             s.first_user_prompt as firstUserPrompt,
             s.session_origin as sessionOrigin,
-            s.handoff_goal as handoffGoal,
-            s.handoff_next_task as handoffNextTask
+            s.handoff_goal as handoffGoal
           FROM sessions s
           ${where.sql}
           ORDER BY s.modified_ts ${orderDirection}
@@ -445,6 +446,7 @@ function createSessionIdWhereFilters(sessionIds: string[] | undefined): SearchWh
     repo: undefined,
     touched: [],
     changed: [],
+    kind: undefined,
     excludeSessionIds: [],
     includeSessionIds: sessionIds === undefined ? undefined : sanitizeFilterValues(sessionIds),
   };
@@ -657,7 +659,6 @@ function buildSearchResult(
     firstUserPrompt: row.firstUserPrompt ?? undefined,
     sessionOrigin: row.sessionOrigin ?? undefined,
     handoffGoal: row.handoffGoal ?? undefined,
-    handoffNextTask: row.handoffNextTask ?? undefined,
     relation: relationBySessionId.get(row.sessionId),
     snippet: "",
     evidence: [...fileEvidence],
@@ -759,6 +760,12 @@ function buildSessionWhereClause(alias: string, filters: SearchWhereFilters): Sq
     args.push(filters.cwd, filters.cwdLike ?? `${escapeLikePrefix(filters.cwd)}%`);
   }
 
+  if (filters.kind === "subagent") {
+    conditions.push(`${alias}.session_origin = 'subagent'`);
+  } else if (filters.kind === "user") {
+    conditions.push(`(${alias}.session_origin IS NULL OR ${alias}.session_origin <> 'subagent')`);
+  }
+
   if (filters.excludeSessionIds.length > 0) {
     conditions.push(
       `${alias}.session_id NOT IN (${filters.excludeSessionIds.map(() => "?").join(", ")})`,

package/extensions/shared/session-index/store.ts

@@ -27,7 +27,6 @@ const SESSION_ROW_QUERY_SCHEMA = Type.Object({
   parentSessionId: NULLABLE_STRING_SCHEMA,
   sessionOrigin: Type.Union([SESSION_ORIGIN_SCHEMA, Type.Null()]),
   handoffGoal: NULLABLE_STRING_SCHEMA,
-  handoffNextTask: NULLABLE_STRING_SCHEMA,
   indexedFileSize: Type.Union([Type.Number(), Type.Null()]),
   indexedFileMtimeMs: Type.Union([Type.Number(), Type.Null()]),
   indexedFileAnchor: NULLABLE_STRING_SCHEMA,
@@ -49,7 +48,6 @@ function sessionRowBindings(row: SessionRow, indexSource: string) {
     row.parentSessionId ?? null,
     row.sessionOrigin ?? null,
     row.handoffGoal ?? null,
-    row.handoffNextTask ?? null,
     row.indexedFileSize ?? null,
     row.indexedFileMtimeMs ?? null,
     row.indexedFileAnchor ?? null,
@@ -70,10 +68,10 @@ export function insertSession(
         session_id, session_path, session_name, first_user_prompt, cwd, repo_roots_json,
         created_ts, modified_ts, message_count, entry_count,
         parent_session_path, parent_session_id, session_origin,
-        handoff_goal, handoff_next_task,
+        handoff_goal,
         indexed_file_size, indexed_file_mtime_ms, indexed_file_anchor,
         index_version, indexed_at_ts, index_source
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `,
   ).run(...sessionRowBindings(row, indexSource));
   syncSessionRepoRoots(db, row);
@@ -90,10 +88,10 @@ export function upsertSession(
         session_id, session_path, session_name, first_user_prompt, cwd, repo_roots_json,
         created_ts, modified_ts, message_count, entry_count,
         parent_session_path, parent_session_id, session_origin,
-        handoff_goal, handoff_next_task,
+        handoff_goal,
         indexed_file_size, indexed_file_mtime_ms, indexed_file_anchor,
         index_version, indexed_at_ts, index_source
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(session_id) DO UPDATE SET
         session_path = excluded.session_path,
         session_name = excluded.session_name,
@@ -108,7 +106,6 @@ export function upsertSession(
         parent_session_id = excluded.parent_session_id,
         session_origin = excluded.session_origin,
         handoff_goal = excluded.handoff_goal,
-        handoff_next_task = excluded.handoff_next_task,
         indexed_file_size = excluded.indexed_file_size,
         indexed_file_mtime_ms = excluded.indexed_file_mtime_ms,
         indexed_file_anchor = excluded.indexed_file_anchor,
@@ -142,7 +139,6 @@ export function getSessionRowByPath(
           parent_session_id as parentSessionId,
           session_origin as sessionOrigin,
           handoff_goal as handoffGoal,
-          handoff_next_task as handoffNextTask,
           indexed_file_size as indexedFileSize,
           indexed_file_mtime_ms as indexedFileMtimeMs,
           indexed_file_anchor as indexedFileAnchor
@@ -179,7 +175,6 @@ function buildSessionRow(row: Static<typeof SESSION_ROW_QUERY_SCHEMA>): SessionR
     parentSessionId: row.parentSessionId ?? undefined,
     sessionOrigin: row.sessionOrigin ?? undefined,
     handoffGoal: row.handoffGoal ?? undefined,
-    handoffNextTask: row.handoffNextTask ?? undefined,
     indexedFileSize: row.indexedFileSize ?? undefined,
     indexedFileMtimeMs: row.indexedFileMtimeMs ?? undefined,
     indexedFileAnchor: row.indexedFileAnchor ?? undefined,

package/extensions/shared/settings.ts

@@ -4,15 +4,41 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { KeyId } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
+import { isThinkingLevel } from "./thinking-levels.ts";
 import { parseTypeBoxValue } from "./typebox.ts";
 
 export const DEFAULT_AUTO_TITLE_REFRESH_TURNS = 4;
 export const DEFAULT_AUTO_TITLE_TIMEOUT_SECONDS = 15;
 export const DEFAULT_AUTO_TITLE_PROMPT = `Name this coding session (under 80 chars). Be specific to what is being discussed. Your exact output will be displayed to the user, so make sure that it contains ONLY the title itself and nothing else.`;
 const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
+  messaging: Type.Optional(
+    Type.Object({
+      enable: Type.Optional(Type.Boolean()),
+    }),
+  ),
+  subagents: Type.Optional(
+    Type.Object({
+      enable: Type.Optional(Type.Boolean()),
+      maxDepth: Type.Optional(Type.Integer({ minimum: 0 })),
+    }),
+  ),
   handoff: Type.Optional(
     Type.Object({
+      enable: Type.Optional(Type.Boolean()),
       pickerShortcut: Type.Optional(Type.String()),
+      persistRuns: Type.Optional(Type.Boolean()),
+      model: Type.Optional(Type.String()),
+      thinkingLevel: Type.Optional(Type.String()),
+      deferred: Type.Optional(
+        Type.Object({
+          copyToClipboard: Type.Optional(Type.Boolean()),
+        }),
+      ),
+    }),
+  ),
+  search: Type.Optional(
+    Type.Object({
+      enable: Type.Optional(Type.Boolean()),
     }),
   ),
   index: Type.Optional(
@@ -22,6 +48,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
   ),
   autoTitle: Type.Optional(
     Type.Object({
+      enable: Type.Optional(Type.Boolean()),
       refreshTurns: Type.Optional(Type.Integer({ minimum: 1 })),
       timeoutSecs: Type.Optional(Type.Integer({ minimum: 1 })),
       model: Type.Optional(Type.String()),
@@ -31,29 +58,24 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
   ),
   ask: Type.Optional(
     Type.Object({
+      enable: Type.Optional(Type.Boolean()),
       model: Type.Optional(Type.String()),
       thinkingLevel: Type.Optional(Type.String()),
       persistRuns: Type.Optional(Type.Boolean()),
     }),
   ),
+  hooks: Type.Optional(
+    Type.Object({
+      enable: Type.Optional(Type.Boolean()),
+    }),
+  ),
 });
 const ROOT_SETTINGS_SCHEMA = Type.Object({
   sessions: Type.Optional(SESSION_FILE_SETTINGS_SCHEMA),
 });
 
-export class ModelReference {
-  constructor(
-    readonly provider: string,
-    readonly modelId: string,
-  ) {}
-
-  toString(): string {
-    return `${this.provider}/${this.modelId}`;
-  }
-}
-
 export interface AgentModelSettings {
-  model?: ModelReference | undefined;
+  model?: string | undefined;
   thinkingLevel?: ThinkingLevel | undefined;
 }
 
@@ -67,10 +89,30 @@ export interface AskSettings extends AgentModelSettings {
   persistRuns: boolean;
 }
 
+export interface HandoffSettings extends AgentModelSettings {
+  pickerShortcut: KeyId;
+  persistRuns: boolean;
+  deferred: {
+    copyToClipboard: boolean;
+  };
+}
+
+export interface FeatureToggles {
+  messaging: boolean;
+  subagents: boolean;
+  handoff: boolean;
+  search: boolean;
+  ask: boolean;
+  autoTitle: boolean;
+  hooks: boolean;
+}
+
 export interface SessionSettings {
-  handoff: {
-    pickerShortcut: KeyId;
+  features: FeatureToggles;
+  subagents: {
+    maxDepth: number;
   };
+  handoff: HandoffSettings;
   index: {
     path: string;
   };
@@ -92,6 +134,10 @@ export function getDefaultSessionAskRunsDir(): string {
   return path.join(getDefaultIndexDir(), "session-ask");
 }
 
+export function getDefaultHandoffRunsDir(): string {
+  return path.join(getDefaultIndexDir(), "session-handoff");
+}
+
 function expandHome(rawPath: string): string {
   if (rawPath === "~") {
     return os.homedir();
@@ -127,33 +173,9 @@ function normalizePickerShortcut(value: string | undefined): KeyId {
   return (trimmed ? trimmed : "alt+o") as KeyId;
 }
 
-export function parseModelReference(value: string | undefined): ModelReference | undefined {
-  const trimmed = value?.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-
-  const slashIndex = trimmed.indexOf("/");
-  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) {
-    return undefined;
-  }
-
-  return new ModelReference(trimmed.slice(0, slashIndex), trimmed.slice(slashIndex + 1));
-}
-
 function parseThinkingLevel(value: string | undefined): ThinkingLevel | undefined {
   const trimmed = value?.trim();
-  switch (trimmed) {
-    case "off":
-    case "minimal":
-    case "low":
-    case "medium":
-    case "high":
-    case "xhigh":
-      return trimmed;
-    default:
-      return undefined;
-  }
+  return isThinkingLevel(trimmed) ? trimmed : undefined;
 }
 
 function resolveAgentModelSettings(
@@ -164,7 +186,7 @@ function resolveAgentModelSettings(
       }
     | undefined,
 ): AgentModelSettings {
-  const model = parseModelReference(value?.model);
+  const model = value?.model?.trim() || undefined;
   const thinkingLevel = parseThinkingLevel(value?.thinkingLevel);
   return {
     ...(model ? { model } : {}),
@@ -183,12 +205,33 @@ function loadSessionFileSettings(): SessionFileSettings {
   return parsed.sessions ?? {};
 }
 
+function resolveFeatureToggles(value: SessionFileSettings): FeatureToggles {
+  return {
+    messaging: value.messaging?.enable ?? true,
+    subagents: value.subagents?.enable ?? true,
+    handoff: value.handoff?.enable ?? true,
+    search: value.search?.enable ?? true,
+    ask: value.ask?.enable ?? true,
+    autoTitle: value.autoTitle?.enable ?? true,
+    hooks: value.hooks?.enable ?? true,
+  };
+}
+
 function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSettings {
   const indexDir = normalizeIndexDir(fileSettings.index?.dir);
 
   return {
+    features: resolveFeatureToggles(fileSettings),
+    subagents: {
+      maxDepth: fileSettings.subagents?.maxDepth ?? 2,
+    },
     handoff: {
+      ...resolveAgentModelSettings(fileSettings.handoff),
       pickerShortcut: normalizePickerShortcut(fileSettings.handoff?.pickerShortcut),
+      persistRuns: fileSettings.handoff?.persistRuns ?? false,
+      deferred: {
+        copyToClipboard: fileSettings.handoff?.deferred?.copyToClipboard ?? true,
+      },
     },
     index: {
       path: path.join(indexDir, "index.sqlite"),

package/extensions/shared/text.ts

@@ -18,6 +18,11 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+export function normalizeOptionalText(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized || undefined;
+}
+
 export function truncateInline(value: string, maxChars: number): string {
   const cleaned = value.replace(/\s+/g, " ").trim();
   if (cleaned.length <= maxChars) {

package/extensions/shared/thinking-levels.ts

@@ -0,0 +1,22 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+
+// Pi exports the ThinkingLevel type but no runtime list of its members
+// (getSupportedThinkingLevels requires a concrete model). This object is the
+// one local runtime definition; Record makes upstream additions a type error.
+const THINKING_LEVELS_BY_NAME = {
+  off: true,
+  minimal: true,
+  low: true,
+  medium: true,
+  high: true,
+  xhigh: true,
+  max: true,
+} satisfies Record<ThinkingLevel, true>;
+
+export const THINKING_LEVELS = Object.freeze(
+  Object.keys(THINKING_LEVELS_BY_NAME) as ThinkingLevel[],
+);
+
+export function isThinkingLevel(value: string | undefined): value is ThinkingLevel {
+  return value !== undefined && Object.hasOwn(THINKING_LEVELS_BY_NAME, value);
+}

package/extensions/shared/tmux.ts

@@ -0,0 +1,205 @@
+import type { ExecOptions, ExecResult } from "@earendil-works/pi-coding-agent";
+
+const TMUX_COMMAND = "tmux";
+const TMUX_TIMEOUT_MS = 15_000;
+const SESSION_ID_OPTION = "@pi_session_id";
+const WINDOW_FORMAT = "#{window_id}\t#{window_name}\t#{@pi_session_id}";
+
+export interface TmuxWindow {
+  windowId: string;
+  name: string;
+  piSessionId: string;
+}
+
+export interface CreateTmuxWindowOptions {
+  tmuxSession: string;
+  name: string;
+  cwd: string;
+  command: string;
+  piSessionId: string;
+}
+
+export interface TmuxExecutor {
+  exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+}
+
+export function isInsideTmux(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.TMUX);
+}
+
+export function tmuxSessionName(parentSessionId: string): string {
+  const hex = parentSessionId.replaceAll("-", "").match(/^[0-9a-fA-F]+/)?.[0] ?? "";
+  if (hex.length < 8) {
+    throw new Error(`Cannot derive tmux session name from session id: ${parentSessionId}`);
+  }
+  return `pi-${hex.slice(0, 12).toLowerCase()}`;
+}
+
+export async function isTmuxInstalled(executor: TmuxExecutor, cwd: string): Promise<boolean> {
+  const result = await executor.exec(TMUX_COMMAND, ["-V"], { cwd, timeout: TMUX_TIMEOUT_MS });
+  return result.code === 0;
+}
+
+export async function listTmuxWindows(
+  executor: TmuxExecutor,
+  tmuxSession: string,
+): Promise<TmuxWindow[]> {
+  const result = await executor.exec(
+    TMUX_COMMAND,
+    ["list-windows", "-t", tmuxSession, "-F", WINDOW_FORMAT],
+    { timeout: TMUX_TIMEOUT_MS },
+  );
+  if (result.code !== 0) {
+    if (isMissingSession(result)) {
+      return [];
+    }
+    throw tmuxError("list windows", result);
+  }
+
+  return result.stdout
+    .split("\n")
+    .filter(Boolean)
+    .map(parseWindow)
+    .filter((window): window is TmuxWindow => window !== undefined);
+}
+
+export async function hasAttachedTmuxClients(
+  executor: TmuxExecutor,
+  tmuxSession: string,
+): Promise<boolean> {
+  const result = await executor.exec(
+    TMUX_COMMAND,
+    ["list-clients", "-t", tmuxSession, "-F", "#{client_name}"],
+    { timeout: TMUX_TIMEOUT_MS },
+  );
+  if (result.code !== 0) {
+    if (isMissingSession(result)) {
+      return false;
+    }
+    throw tmuxError("list attached clients", result);
+  }
+  return result.stdout.split("\n").some((line) => line.trim().length > 0);
+}
+
+export async function createTmuxWindow(
+  executor: TmuxExecutor,
+  options: CreateTmuxWindowOptions,
+): Promise<TmuxWindow> {
+  const existing = (await listTmuxWindows(executor, options.tmuxSession)).find(
+    (window) => window.piSessionId === options.piSessionId,
+  );
+  if (existing) {
+    return existing;
+  }
+
+  const sessionExists = await hasTmuxSession(executor, options.tmuxSession);
+  const args = sessionExists
+    ? [
+        "new-window",
+        "-d",
+        "-P",
+        "-F",
+        "#{window_id}",
+        "-t",
+        options.tmuxSession,
+        "-n",
+        options.name,
+        "-c",
+        options.cwd,
+        options.command,
+      ]
+    : [
+        "new-session",
+        "-d",
+        "-P",
+        "-F",
+        "#{window_id}",
+        "-s",
+        options.tmuxSession,
+        "-n",
+        options.name,
+        "-c",
+        options.cwd,
+        options.command,
+      ];
+  const created = await executor.exec(TMUX_COMMAND, args, {
+    cwd: options.cwd,
+    timeout: TMUX_TIMEOUT_MS,
+  });
+  if (created.code !== 0) {
+    throw tmuxError("create window", created);
+  }
+
+  const windowId = created.stdout.trim();
+  if (!windowId) {
+    throw new Error("tmux created a window without returning its id.");
+  }
+  const stamped = await executor.exec(
+    TMUX_COMMAND,
+    ["set-option", "-w", "-t", windowId, SESSION_ID_OPTION, options.piSessionId],
+    { timeout: TMUX_TIMEOUT_MS },
+  );
+  if (stamped.code !== 0) {
+    await executor.exec(TMUX_COMMAND, ["kill-window", "-t", windowId], {
+      timeout: TMUX_TIMEOUT_MS,
+    });
+    throw tmuxError("stamp window", stamped);
+  }
+
+  return { windowId, name: options.name, piSessionId: options.piSessionId };
+}
+
+export async function killTmuxWindow(
+  executor: TmuxExecutor,
+  tmuxSession: string,
+  piSessionId: string,
+): Promise<boolean> {
+  const windows = await listTmuxWindows(executor, tmuxSession);
+  for (const window of windows.filter((candidate) => candidate.piSessionId === piSessionId)) {
+    await executor.exec(TMUX_COMMAND, ["kill-window", "-t", window.windowId], {
+      timeout: TMUX_TIMEOUT_MS,
+    });
+  }
+  return !(await listTmuxWindows(executor, tmuxSession)).some(
+    (window) => window.piSessionId === piSessionId,
+  );
+}
+
+export async function killTmuxSession(
+  executor: TmuxExecutor,
+  tmuxSession: string,
+): Promise<boolean> {
+  const result = await executor.exec(TMUX_COMMAND, ["kill-session", "-t", tmuxSession], {
+    timeout: TMUX_TIMEOUT_MS,
+  });
+  if (result.code !== 0 && !isMissingSession(result)) {
+    return false;
+  }
+  return !(await hasTmuxSession(executor, tmuxSession));
+}
+
+async function hasTmuxSession(executor: TmuxExecutor, tmuxSession: string): Promise<boolean> {
+  const result = await executor.exec(TMUX_COMMAND, ["has-session", "-t", tmuxSession], {
+    timeout: TMUX_TIMEOUT_MS,
+  });
+  return result.code === 0;
+}
+
+function parseWindow(line: string): TmuxWindow | undefined {
+  const [windowId, name, piSessionId] = line.split("\t");
+  if (!windowId || name === undefined || !piSessionId) {
+    return undefined;
+  }
+  return { windowId, name, piSessionId };
+}
+
+function isMissingSession(result: ExecResult): boolean {
+  return /can't find session|no server running|failed to connect to server|error connecting to .*no such file/i.test(
+    `${result.stderr}\n${result.stdout}`,
+  );
+}
+
+function tmuxError(action: string, result: ExecResult): Error {
+  const details = `${result.stderr || result.stdout}`.trim() || `exit code ${result.code}`;
+  return new Error(`Failed to ${action} with tmux: ${details}`);
+}