@ian-pascoe/pi-codemode 0.1.0 → 0.2.0

package/README.md

@@ -62,11 +62,38 @@ codemode_cancel({ sessionId: string });
 Stops the session process and frees its capacity. The cancel call succeeds;
 subsequent polling returns the retained `cancellation` failure.
 
-All three tools return:
+### `codemode_sessions`
+
+```ts
+codemode_sessions({});
+```
+
+Lists every live Session, with idle Sessions first in least-recently-used order,
+then running Sessions in least-recently-used order. Listing does not refresh
+Session recency.
+
+```ts
+type CodeModeSessionsResult = {
+  result: "success";
+  sessions: Array<{
+    sessionId: string;
+    state: "idle" | "running";
+    cellCount: number;
+    lastActivityAtMs: number;
+  }>;
+};
+```
+
+The execute, result, and cancel tools return:
 
 ```ts
 type CodeModeResult =
-  | { result: "success"; sessionId: string; data?: JsonValue }
+  | {
+      result: "success";
+      sessionId: string;
+      data?: JsonValue;
+      reclaimedSessionId?: string;
+    }
   | { result: "pending"; sessionId: string }
   | {
       result: "failed";
@@ -76,6 +103,7 @@ type CodeModeResult =
           | "unknown"
           | "busy"
           | "capacity"
+          | "eviction"
           | "script"
           | "serialization"
           | "timeout"
@@ -93,7 +121,7 @@ Snapshots in tool-result details for Transcript replay and the TUI.
 
 ## Transcript and Observer UI
 
-The CodeMode Transcript gives all three tools semantic collapsed and expanded
+The CodeMode Transcript gives all four tools semantic collapsed and expanded
 rendering. Collapsed rows prioritize Cell lifecycle, a short Session ID, Cell
 Ordinal, returned-value shape, nested-tool count, and elapsed time. Expanded
 rows show the full Session ID, explicit call arguments, TypeScript source,
@@ -105,15 +133,17 @@ Status always uses a symbol and text together:
 
 ```text
 ◉ running   ○ idle   ✓ completed
-× failed    ■ cancelled   ! timed out
+× failed    ■ cancelled   ■ reclaimed   ! timed out
 ```
 
 Awaited Cells publish a presentation update immediately and once per second.
-Source display is limited to 200 lines or 50 KB. Returned-data display uses
-Pi's 2,000-line/50-KB limit; complete oversized data is written to a private
-Result Spill while the model-facing result remains unchanged. Result Spill
-files last for the live Pi session. Replayed history falls back to its retained
-bounded data when a prior spill is no longer available.
+Collapsed calls show one highlighted line inline or the first eight highlighted
+lines of a multi-line Cell. Expanded calls show the complete TypeScript source.
+Returned-data display uses Pi's 2,000-line/50-KB limit; complete oversized data
+is written to a private Result Spill while the model-facing result remains
+unchanged. Result Spill files last for the live Pi session. Replayed history
+falls back to its retained bounded data when a prior spill is no longer
+available.
 
 In TUI mode, the read-only CodeMode Observer UI appears above the editor during
 Cell activity. It shows up to eight running, idle, or recently terminal
@@ -204,12 +234,18 @@ last match wins. Project `tools` replaces the global array, while project
 
 An unmatched active tool defaults to `direct-and-codemode`; an unmatched
 inactive tool remains unavailable. An explicit rule may expose an inactive tool
-or activate direct access. The three `codemode_*` tools are always direct-only.
+or activate direct access. The four `codemode_*` tools are always direct-only.
 Pi's global allowed/excluded registry remains authoritative. Invalid fields or
 patterns disable CodeMode for that session without changing Pi's active tools.
 
-`maxSessions` defaults to 8 and counts only live Deno processes. Up to 64 recent
-worker-free terminal or failed-admission records remain pollable.
+`maxSessions` defaults to 8 and counts only live Deno processes. When capacity
+is full, a new Session gracefully stops the least-recently-used idle Session
+before starting; its Notebook Bindings are discarded, the new success reports
+`reclaimedSessionId`, and polling the old ID returns `eviction`. Running Sessions
+are never reclaimed, so admission still returns `capacity` when every process is
+busy. Executing or polling refreshes recency; listing and Observer rendering do
+not. Up to 64 recent worker-free terminal or failed-admission records remain
+pollable.
 
 ## Isolation and limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-codemode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Process-isolated persistent TypeScript tool composition for Pi",
   "keywords": [
@@ -32,10 +32,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "deno": "2.9.5",
     "minimatch": "^10.2.5",
@@ -55,5 +51,9 @@
     "extensions": [
       "./src/index.ts"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/src/codemode-observer-ui.ts

@@ -72,7 +72,7 @@ export type CodeModeObserverRow = {
   /** Idle Session summary retained only during relevant Observer activity. */
   | { readonly state: "idle"; readonly cellCount: number }
   | {
-      readonly state: "failed" | "cancelled" | "timed_out";
+      readonly state: "failed" | "cancelled" | "reclaimed" | "timed_out";
       /** Most recent one-based Cell Ordinal, or Session Cell count when no final Cell exists. */
       readonly cellOrdinal: number;
     }
@@ -102,6 +102,7 @@ const CODEMODE_OBSERVER_STATE_PRESENTATION = {
   idle: { symbol: "○", label: "idle", color: "muted" },
   failed: { symbol: "×", label: "failed", color: "error" },
   cancelled: { symbol: "■", label: "cancelled", color: "warning" },
+  reclaimed: { symbol: "■", label: "reclaimed", color: "warning" },
   timed_out: { symbol: "!", label: "timed out", color: "error" },
 } satisfies Record<CodeModeObserverState, CodeModeObserverStatePresentation>;
 
@@ -153,10 +154,11 @@ function boundedElapsedMilliseconds(nowMs: number, startedAtMs: number): number
 
 function codeModeTerminalObserverState(
   session: CodeModeObservedSession,
-): Extract<CodeModeObserverState, "failed" | "cancelled" | "timed_out"> {
+): Extract<CodeModeObserverState, "failed" | "cancelled" | "reclaimed" | "timed_out"> {
   if (session.terminal_error_code === "cancellation" || session.last_cell?.state === "cancelled") {
     return "cancelled";
   }
+  if (session.terminal_error_code === "eviction") return "reclaimed";
   if (session.terminal_error_code === "timeout" || session.last_cell?.state === "timed_out") {
     return "timed_out";
   }

package/src/codemode-session-coordinator.ts

@@ -86,6 +86,15 @@ export type CodeModeObserverSnapshot = {
   readonly sessions: readonly CodeModeObservedSession[];
 };
 
+/** Read-only facts for one live CodeMode Session, ordered by admission priority. */
+export type CodeModeListedSession = {
+  readonly sessionId: CodeModeSessionId;
+  readonly state: "running" | "idle";
+  readonly cellCount: number;
+  /** Parent wall-clock time of the latest execution-visible transition in Unix-epoch milliseconds. */
+  readonly lastActivityAtMs: number;
+};
+
 /** One idle CodeMode worker failure not represented by an active Cell result. */
 export type CodeModeUnexpectedFailure = {
   readonly sessionId: CodeModeSessionId;
@@ -176,10 +185,16 @@ type MutableCodeModeOuterToolMetadata = {
   terminate?: boolean;
 };
 
+type CreateActiveCodeModeCellOptions = {
+  onUpdate?: (update: CodeModeNestedToolUpdate) => void;
+  reclaimedSessionId?: CodeModeSessionId;
+};
+
 type ActiveCodeModeCell = {
   readonly cellId: string;
   readonly ordinal: number;
   readonly startedAtMs: number;
+  readonly reclaimedSessionId?: CodeModeSessionId;
   readonly abortController: AbortController;
   readonly completion: Promise<CodeModeResult>;
   readonly resolveCompletion: (result: CodeModeResult) => void;
@@ -224,10 +239,12 @@ type TerminalCodeModeSession = {
 
 type CodeModeSessionRecord = LiveCodeModeSession | TerminalCodeModeSession;
 
-type LocateCodeModeSessionResult = {
-  readonly record?: CodeModeSessionRecord;
-  readonly failure: CodeModeResult;
-};
+type LocateCodeModeSessionResult =
+  | {
+      readonly record: CodeModeSessionRecord;
+      readonly reclaimedSessionId?: CodeModeSessionId;
+    }
+  | { readonly failure: CodeModeResult };
 
 type FatalCodeModeSessionFailure = {
   readonly code: Extract<CodeModeErrorCode, "timeout" | "cancellation" | "termination" | "runtime">;
@@ -325,6 +342,7 @@ export class CodeModeSessionCoordinator {
     (update: CodeModeNestedToolUpdate) => void
   >();
   private readonly pendingProcessStops = new Set<Promise<void>>();
+  private admissionQueue: Promise<void> = Promise.resolve();
 
   /** Creates one coordinator from its Pi bridge, limits, and parent runtime capabilities. */
   constructor(private readonly options: CodeModeSessionCoordinatorOptions) {
@@ -349,70 +367,80 @@ export class CodeModeSessionCoordinator {
         ),
       };
     }
-    let located: LocateCodeModeSessionResult;
-    if (input.sessionId === undefined) located = this.createLiveSession();
-    else {
-      const parsedSessionId = parseCodeModeSessionId(input.sessionId);
-      if (!parsedSessionId.ok) return invalidCodeModeSessionResult();
-      located = this.findSession(parsedSessionId.value);
-    }
-    if (located.record === undefined) return { result: located.failure };
-    const record = located.record;
-    this.touch(record);
-    if (record.state === "terminal")
-      return this.operationResult(
-        record.latestResult,
-        this.takeMetadata(record),
-        record.latestPresentation,
-      );
-    if (record.currentCell !== undefined) {
-      return {
-        result: createCodeModeFailure(
-          record.sessionId,
-          "busy",
-          "CodeMode Session already has an active Cell",
-        ),
-      };
-    }
+    let releaseAdmission =
+      input.sessionId === undefined ? await this.acquireSessionAdmission() : undefined;
+    try {
+      let located: LocateCodeModeSessionResult;
+      if (input.sessionId === undefined) located = await this.createLiveSession();
+      else {
+        const parsedSessionId = parseCodeModeSessionId(input.sessionId);
+        if (!parsedSessionId.ok) return invalidCodeModeSessionResult();
+        located = this.findSession(parsedSessionId.value);
+      }
+      if ("failure" in located) return { result: located.failure };
+      const record = located.record;
+      this.touch(record);
+      if (record.state === "terminal")
+        return this.operationResult(
+          record.latestResult,
+          this.takeMetadata(record),
+          record.latestPresentation,
+        );
+      if (record.currentCell !== undefined) {
+        return {
+          result: createCodeModeFailure(
+            record.sessionId,
+            "busy",
+            "CodeMode Session already has an active Cell",
+          ),
+        };
+      }
 
-    const shouldWait = input.wait !== false;
-    const cell = this.createActiveCell(
-      record,
-      shouldWait && onUpdate !== undefined ? { onUpdate } : {},
-    );
-    const priorMetadata = this.takeMetadata(record);
-    if (priorMetadata !== undefined) mergeCodeModeOuterMetadata(cell.metadata, priorMetadata);
-    record.currentCell = cell;
-    record.latestResult = createCodeModePending(record.sessionId);
-    record.lastActivityAtMs = cell.startedAtMs;
-    this.publishObserverSnapshot();
-    this.emitCellProgress(record, cell);
-    this.scheduleCellProgress(record, cell);
-    void this.startCell(record, cell, input);
+      const shouldWait = input.wait !== false;
+      const cellOptions: CreateActiveCodeModeCellOptions = {};
+      if (shouldWait && onUpdate !== undefined) cellOptions.onUpdate = onUpdate;
+      if (located.reclaimedSessionId !== undefined) {
+        cellOptions.reclaimedSessionId = located.reclaimedSessionId;
+      }
+      const cell = this.createActiveCell(record, cellOptions);
+      const priorMetadata = this.takeMetadata(record);
+      if (priorMetadata !== undefined) mergeCodeModeOuterMetadata(cell.metadata, priorMetadata);
+      record.currentCell = cell;
+      record.latestResult = createCodeModePending(record.sessionId);
+      record.lastActivityAtMs = cell.startedAtMs;
+      this.publishObserverSnapshot();
+      this.emitCellProgress(record, cell);
+      this.scheduleCellProgress(record, cell);
+      void this.startCell(record, cell, input);
+      releaseAdmission?.();
+      releaseAdmission = undefined;
 
-    const pending = createCodeModePending(record.sessionId);
-    if (!shouldWait) {
-      return this.operationResult(pending, undefined, this.runningCellPresentation(cell));
-    }
-    const abort = (): void => {
-      this.fatalizeSession(record, cell, {
-        code: "cancellation",
-        message: "CodeMode Cell was cancelled",
-      });
-    };
-    if (signal?.aborted === true) abort();
-    else signal?.addEventListener("abort", abort, { once: true });
-    try {
-      const result = await cell.completion;
-      const retainedRecord = this.records.get(record.sessionId) ?? record;
-      return this.operationResult(
-        result,
-        this.takeMetadata(retainedRecord),
-        retainedRecord.latestPresentation,
-      );
+      const pending = createCodeModePending(record.sessionId);
+      if (!shouldWait) {
+        return this.operationResult(pending, undefined, this.runningCellPresentation(cell));
+      }
+      const abort = (): void => {
+        this.fatalizeSession(record, cell, {
+          code: "cancellation",
+          message: "CodeMode Cell was cancelled",
+        });
+      };
+      if (signal?.aborted === true) abort();
+      else signal?.addEventListener("abort", abort, { once: true });
+      try {
+        const result = await cell.completion;
+        const retainedRecord = this.records.get(record.sessionId) ?? record;
+        return this.operationResult(
+          result,
+          this.takeMetadata(retainedRecord),
+          retainedRecord.latestPresentation,
+        );
+      } finally {
+        cell.acceptsUpdates = false;
+        signal?.removeEventListener("abort", abort);
+      }
     } finally {
-      cell.acceptsUpdates = false;
-      signal?.removeEventListener("abort", abort);
+      releaseAdmission?.();
     }
   }
 
@@ -437,6 +465,26 @@ export class CodeModeSessionCoordinator {
     return this.operationResult(result, this.takeMetadata(record), record.latestPresentation);
   }
 
+  /** Lists all live Sessions with idle least-recently-used entries before running entries. */
+  listSessions(): readonly CodeModeListedSession[] {
+    const sessions = [...this.records.values()]
+      .filter((record): record is LiveCodeModeSession => record.state === "live")
+      .toSorted((left, right) => {
+        const stateOrder =
+          Number(left.currentCell !== undefined) - Number(right.currentCell !== undefined);
+        return stateOrder === 0 ? left.lastAccess - right.lastAccess : stateOrder;
+      })
+      .map((record) =>
+        Object.freeze({
+          sessionId: record.sessionId,
+          state: record.currentCell === undefined ? "idle" : "running",
+          cellCount: record.cellCount,
+          lastActivityAtMs: record.lastActivityAtMs,
+        } satisfies CodeModeListedSession),
+      );
+    return Object.freeze(sessions);
+  }
+
   /** Returns immutable, non-authoritative facts for the ephemeral CodeMode Observer UI. */
   inspectObserverSnapshot(): CodeModeObserverSnapshot {
     const sessions = [...this.records.values()]
@@ -537,7 +585,15 @@ export class CodeModeSessionCoordinator {
     await Promise.all(this.pendingProcessStops);
   }
 
-  private createLiveSession(): LocateCodeModeSessionResult {
+  private async acquireSessionAdmission(): Promise<() => void> {
+    const previousAdmission = this.admissionQueue;
+    const admission = Promise.withResolvers<void>();
+    this.admissionQueue = previousAdmission.then(() => admission.promise);
+    await previousAdmission;
+    return admission.resolve;
+  }
+
+  private async createLiveSession(): Promise<LocateCodeModeSessionResult> {
     const parsedSessionId = parseCodeModeSessionId(this.runtime.createSessionId());
     if (!parsedSessionId.ok) {
       return {
@@ -549,13 +605,67 @@ export class CodeModeSessionCoordinator {
       };
     }
     const sessionId = parsedSessionId.value;
+    if (this.shuttingDown) {
+      const failure = createCodeModeFailure(
+        sessionId,
+        "runtime",
+        "CodeMode coordinator is shutting down",
+      );
+      this.retainTerminalFailure(sessionId, failure);
+      return { failure };
+    }
     this.evictTerminalRecords();
-    const liveCount = [...this.records.values()].filter((record) => record.state === "live").length;
-    if (liveCount >= this.options.maxSessions) {
+    const liveRecords = [...this.records.values()].filter(
+      (record): record is LiveCodeModeSession => record.state === "live",
+    );
+    let reclaimedSessionId: CodeModeSessionId | undefined;
+    if (liveRecords.length >= this.options.maxSessions) {
+      const reclaimedRecord = liveRecords
+        .filter((record) => record.currentCell === undefined)
+        .toSorted((left, right) => left.lastAccess - right.lastAccess)[0];
+      if (reclaimedRecord === undefined) {
+        const failure = createCodeModeFailure(
+          sessionId,
+          "capacity",
+          "CodeMode Session capacity is exhausted",
+        );
+        this.retainTerminalFailure(sessionId, failure);
+        return { failure };
+      }
+      reclaimedSessionId = reclaimedRecord.sessionId;
+      reclaimedRecord.lastActivityAtMs = this.runtime.now();
+      this.touch(reclaimedRecord);
+      if (reclaimedRecord.latestPresentation !== undefined) {
+        reclaimedRecord.latestPresentation = {
+          ...reclaimedRecord.latestPresentation,
+          session_state: "closed",
+        };
+      }
+      this.replaceWithTerminal(
+        reclaimedRecord,
+        createCodeModeFailure(
+          reclaimedRecord.sessionId,
+          "eviction",
+          "CodeMode Session was reclaimed to free capacity.",
+        ),
+      );
+      try {
+        await this.stopWorker(reclaimedRecord.worker, "shutdown");
+      } catch (cause) {
+        const message =
+          cause instanceof Error
+            ? `CodeMode Session reclamation failed: ${cause.message}`
+            : "CodeMode Session reclamation failed: Deno process did not stop cleanly";
+        const failure = createCodeModeFailure(sessionId, "runtime", message);
+        this.retainTerminalFailure(sessionId, failure);
+        return { failure };
+      }
+    }
+    if (this.shuttingDown) {
       const failure = createCodeModeFailure(
         sessionId,
-        "capacity",
-        "CodeMode Session capacity is exhausted",
+        "runtime",
+        "CodeMode coordinator is shutting down",
       );
       this.retainTerminalFailure(sessionId, failure);
       return { failure };
@@ -585,22 +695,22 @@ export class CodeModeSessionCoordinator {
       cellCount: 0,
     };
     this.records.set(sessionId, record);
-    return { record, failure: createCodeModePending(sessionId) };
+    return reclaimedSessionId === undefined ? { record } : { record, reclaimedSessionId };
   }
 
   private findSession(sessionId: CodeModeSessionId): LocateCodeModeSessionResult {
     const record = this.records.get(sessionId);
     return record === undefined
       ? { failure: createCodeModeFailure(sessionId, "unknown", "Unknown CodeMode Session") }
-      : { record, failure: createCodeModePending(sessionId) };
+      : { record };
   }
 
   private createActiveCell(
     record: LiveCodeModeSession,
-    options: { readonly onUpdate?: (update: CodeModeNestedToolUpdate) => void },
+    options: CreateActiveCodeModeCellOptions,
   ): ActiveCodeModeCell {
     const completion = Promise.withResolvers<CodeModeResult>();
-    const cell: ActiveCodeModeCell = {
+    const cellBase: Omit<ActiveCodeModeCell, "reclaimedSessionId"> = {
       cellId: `cell-${++this.cellSequence}`,
       ordinal: ++record.cellCount,
       startedAtMs: this.runtime.now(),
@@ -617,6 +727,10 @@ export class CodeModeSessionCoordinator {
       acceptsUpdates: options.onUpdate !== undefined,
       settled: false,
     };
+    const cell: ActiveCodeModeCell =
+      options.reclaimedSessionId === undefined
+        ? cellBase
+        : { ...cellBase, reclaimedSessionId: options.reclaimedSessionId };
     if (options.onUpdate !== undefined) this.activeUpdateCallbacks.set(cell, options.onUpdate);
     return cell;
   }
@@ -1056,18 +1170,22 @@ export class CodeModeSessionCoordinator {
   ): void {
     if (!this.isCurrentCell(record, cell)) return;
     this.clearCellResources(cell);
-    const presentation = this.settledCellPresentation(cell, result, "live");
+    const retainedResult =
+      result.result === "success" && cell.reclaimedSessionId !== undefined
+        ? { ...result, reclaimedSessionId: cell.reclaimedSessionId }
+        : result;
+    const presentation = this.settledCellPresentation(cell, retainedResult, "live");
     const settledAtMs = this.runtime.now();
-    record.latestResult = result;
+    record.latestResult = retainedResult;
     record.latestPresentation = presentation;
-    record.lastCell = this.observeSettledCell(cell, result, settledAtMs);
+    record.lastCell = this.observeSettledCell(cell, retainedResult, settledAtMs);
     record.lastActivityAtMs = settledAtMs;
     const metadata = finalizeCodeModeMetadata(cell.metadata);
     if (metadata === undefined) delete record.availableMetadata;
     else record.availableMetadata = metadata;
     delete record.currentCell;
     cell.settled = true;
-    cell.resolveCompletion(result);
+    cell.resolveCompletion(retainedResult);
     this.touch(record);
     this.publishObserverSnapshot();
   }

package/src/codemode-tool-contract.ts

@@ -13,6 +13,7 @@ const CODEMODE_TOOL_NAMES = {
   execute: "codemode_execute",
   result: "codemode_result",
   cancel: "codemode_cancel",
+  sessions: "codemode_sessions",
 } as const;
 const RESERVED_CODEMODE_TOOL_NAMES = new Set<string>(Object.values(CODEMODE_TOOL_NAMES));
 
@@ -26,6 +27,7 @@ export const CODEMODE_ERROR_CODES = [
   "unknown",
   "busy",
   "capacity",
+  "eviction",
   "script",
   "serialization",
   "timeout",
@@ -116,12 +118,17 @@ export const CodeModeCancelParametersSchema = Type.Object(
   { additionalProperties: false },
 );
 
+/** Strict empty arguments accepted by the read-only `codemode_sessions` tool. */
+export const CodeModeSessionsParametersSchema = Type.Object({}, { additionalProperties: false });
+
 /** Parsed arguments for `codemode_execute`. */
 export type CodeModeExecuteParameters = Static<typeof CodeModeExecuteParametersSchema>;
 /** Parsed arguments for `codemode_result`. */
 export type CodeModeResultParameters = Static<typeof CodeModeResultParametersSchema>;
 /** Parsed arguments for `codemode_cancel`. */
 export type CodeModeCancelParameters = Static<typeof CodeModeCancelParametersSchema>;
+/** Parsed arguments for the read-only `codemode_sessions` tool. */
+export type CodeModeSessionsParameters = Static<typeof CodeModeSessionsParametersSchema>;
 
 /** A JSON object accepted in a successful CodeMode result. */
 export type CodeModeJsonObject = { readonly [key: string]: CodeModeJsonValue };
@@ -178,9 +185,34 @@ const CodeModeSuccessSchema = Type.Object(
     result: Type.Literal("success"),
     sessionId: SessionIdSchema,
     data: Type.Optional(CodeModeJsonValueSchema),
+    reclaimedSessionId: Type.Optional(SessionIdSchema),
   },
   { additionalProperties: false },
 );
+
+/** One live CodeMode Session with its Unix-epoch last-activity time. */
+export const CodeModeSessionListEntrySchema = Type.Object(
+  {
+    sessionId: SessionIdSchema,
+    state: Type.Union([Type.Literal("idle"), Type.Literal("running")]),
+    cellCount: NonNegativeSafeIntegerSchema,
+    lastActivityAtMs: NonNegativeSafeIntegerSchema,
+  },
+  { additionalProperties: false },
+);
+
+/** Idle-LRU-first, then running-LRU aggregate returned by `codemode_sessions`. */
+export const CodeModeSessionsResultSchema = Type.Object(
+  {
+    result: Type.Literal("success"),
+    sessions: Type.Array(CodeModeSessionListEntrySchema),
+  },
+  { additionalProperties: false },
+);
+
+/** Schema-derived live Session list ordered by reclamation priority. */
+export type CodeModeSessionsResult = Static<typeof CodeModeSessionsResultSchema>;
+
 const CodeModePendingSchema = Type.Object(
   {
     result: Type.Literal("pending"),
@@ -197,14 +229,14 @@ const CodeModeFailedSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/** Schema-derived result union shared by all three public CodeMode tools. */
+/** Schema-derived result union shared by the execute, result, and cancel tools. */
 export const CodeModeResultSchema = Type.Union([
   CodeModeSuccessSchema,
   CodeModePendingSchema,
   CodeModeFailedSchema,
 ]);
 
-/** Schema-derived result returned by every public CodeMode tool. */
+/** Schema-derived result returned by one session-scoped CodeMode operation. */
 export type CodeModeResult = Static<typeof CodeModeResultSchema>;
 
 const CodeModeSuccessDetailsSchema = Type.Object(
@@ -212,6 +244,7 @@ const CodeModeSuccessDetailsSchema = Type.Object(
     result: Type.Literal("success"),
     sessionId: SessionIdSchema,
     data: Type.Optional(CodeModeJsonValueSchema),
+    reclaimedSessionId: Type.Optional(SessionIdSchema),
     presentation: Type.Optional(CodeModePresentationSnapshotSchema),
   },
   { additionalProperties: false },
@@ -240,7 +273,7 @@ export const CodeModeResultDetailsSchema = Type.Union([
   CodeModePendingDetailsSchema,
   CodeModeFailedDetailsSchema,
 ]);
-/** Schema-derived details retained by every public CodeMode tool. */
+/** Schema-derived details retained by one session-scoped CodeMode operation. */
 export type CodeModeResultDetails = Static<typeof CodeModeResultDetailsSchema>;
 
 /** A successful result with optional JSON data. */
@@ -402,7 +435,7 @@ export type CodeModeToolOperationResult = {
   readonly presentation?: CodeModePresentationSnapshot;
 };
 
-/** Operations supplied by the session coordinator to build the three Pi tools. */
+/** Operations supplied by the session coordinator to build the four Pi tools. */
 export interface CodeModeToolOperations {
   execute(
     input: CodeModeExecuteParameters,
@@ -412,6 +445,7 @@ export interface CodeModeToolOperations {
   ): Promise<CodeModeToolOperationResult>;
   result(input: CodeModeResultParameters): Promise<CodeModeToolOperationResult>;
   cancel(input: CodeModeCancelParameters): Promise<CodeModeToolOperationResult>;
+  sessions(): Promise<CodeModeSessionsResult>;
 }
 
 function structuredCodeModeResult(
@@ -438,9 +472,19 @@ type CodeModeToolDefinitions = readonly [
   ToolDefinition<typeof CodeModeExecuteParametersSchema, CodeModeResultDetails>,
   ToolDefinition<typeof CodeModeResultParametersSchema, CodeModeResultDetails>,
   ToolDefinition<typeof CodeModeCancelParametersSchema, CodeModeResultDetails>,
+  ToolDefinition<typeof CodeModeSessionsParametersSchema, CodeModeSessionsResult>,
 ];
 
-/** Creates the three stable Pi definitions while leaving admission and session policy to the coordinator. */
+function structuredCodeModeSessionsResult(
+  result: CodeModeSessionsResult,
+): AgentToolResult<CodeModeSessionsResult> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    details: result,
+  };
+}
+
+/** Creates the four stable Pi definitions while leaving admission and session policy to the coordinator. */
 export function createCodeModeToolDefinitions(
   operations: CodeModeToolOperations,
   executeDescription = "Execute TypeScript in a persistent isolated Deno CodeMode Session.",
@@ -450,6 +494,13 @@ export function createCodeModeToolDefinitions(
       name: CODEMODE_TOOL_NAMES.execute,
       label: "CodeMode Execute",
       description: executeDescription,
+      promptSnippet:
+        "Batch, filter, and aggregate Pi tool calls in TypeScript with less latency and context usage.",
+      promptGuidelines: [
+        "Prefer codemode_execute when multiple Pi tool calls can be filtered, joined, aggregated, paginated, or used to drive later calls, or when one large result can be reduced before returning. Use direct parallel calls for a few small results needed verbatim.",
+        "Return only decision-relevant CodeMode data while preserving paths, line numbers, IDs, URLs, source names, and concise evidence needed for verification.",
+        "Reuse a CodeMode Session for related work. Prefer direct tools for simple one-off calls, full raw output, and confirmation-sensitive or destructive actions; use CodeMode mutations only when conditional sequencing is the point, and fall back to direct tools when the CodeMode boundary does not fit.",
+      ],
       parameters: CodeModeExecuteParametersSchema,
       executionMode: "sequential",
       async execute(_toolCallId, input, signal, onUpdate, context) {
@@ -469,12 +520,25 @@ export function createCodeModeToolDefinitions(
   const cancelTool: ToolDefinition<typeof CodeModeCancelParametersSchema, CodeModeResultDetails> = {
     name: CODEMODE_TOOL_NAMES.cancel,
     label: "CodeMode Cancel",
-    description: "Cancel a live CodeMode session and retain its terminal result.",
+    description: "Cancel a live CodeMode Session, free its capacity, and retain its result.",
     parameters: CodeModeCancelParametersSchema,
     executionMode: "sequential",
     async execute(_toolCallId, input) {
       return structuredCodeModeResult(await operations.cancel(input));
     },
   };
-  return [executeTool, resultTool, cancelTool];
+  const sessionsTool: ToolDefinition<
+    typeof CodeModeSessionsParametersSchema,
+    CodeModeSessionsResult
+  > = {
+    name: CODEMODE_TOOL_NAMES.sessions,
+    label: "List Sessions",
+    description: "List live CodeMode Sessions without changing their recency or state.",
+    parameters: CodeModeSessionsParametersSchema,
+    executionMode: "sequential",
+    async execute() {
+      return structuredCodeModeSessionsResult(await operations.sessions());
+    },
+  };
+  return [executeTool, resultTool, cancelTool, sessionsTool];
 }

package/src/codemode-tool-rendering.ts

@@ -1,5 +1,6 @@
 import {
   getMarkdownTheme,
+  highlightCode,
   keyText,
   truncateHead,
   type AgentToolResult,
@@ -25,6 +26,8 @@ import {
   CodeModeExecuteParametersSchema,
   CodeModeResultDetailsSchema,
   CodeModeResultParametersSchema,
+  CodeModeSessionsParametersSchema,
+  CodeModeSessionsResultSchema,
   createCodeModeToolDefinitions,
   type CodeModeCancelParameters,
   type CodeModeErrorCode,
@@ -34,17 +37,24 @@ import {
   type CodeModePresentationSnapshot,
   type CodeModeResultDetails,
   type CodeModeResultParameters,
+  type CodeModeSessionsParameters,
+  type CodeModeSessionsResult,
   type CodeModeToolOperations,
 } from "./codemode-tool-contract.js";
 
-/** Names of the three CodeMode tools with semantic Transcript rendering. */
-export type CodeModeRenderedToolName = "codemode_execute" | "codemode_result" | "codemode_cancel";
+/** Names of the four CodeMode tools with semantic Transcript rendering. */
+export type CodeModeRenderedToolName =
+  | "codemode_execute"
+  | "codemode_result"
+  | "codemode_cancel"
+  | "codemode_sessions";
 
-/** Parsed arguments accepted by one of the three CodeMode Transcript renderers. */
+/** Parsed arguments accepted by one of the four CodeMode Transcript renderers. */
 export type CodeModeRenderedToolParameters =
   | CodeModeExecuteParameters
   | CodeModeResultParameters
-  | CodeModeCancelParameters;
+  | CodeModeCancelParameters
+  | CodeModeSessionsParameters;
 
 /** Theme operations used by CodeMode Transcript renderers. */
 export type CodeModeRenderTheme = Pick<Theme, "bold" | "fg">;
@@ -62,7 +72,7 @@ const CODEMODE_STATUS_PRESENTATION = {
   cancelled: { color: "warning", label: "■ cancelled" },
   timed_out: { color: "error", label: "! timed out" },
 } satisfies Record<CodeModeCellState, CodeModeStatusPresentation>;
-const CODEMODE_SCRIPT_MAX_LINES = 200;
+const CODEMODE_COLLAPSED_SCRIPT_LINES = 8;
 const CODEMODE_PRESENTATION_MAX_BYTES = 50 * 1024;
 const CodeModeJsonStringSchema = Type.String();
 
@@ -82,14 +92,6 @@ function boundedCodeModePreview(text: string, width = 72): string {
   return `${sliceByColumn(singleLine, 0, width - 1, true).trimEnd()}…`;
 }
 
-function firstMeaningfulScriptLine(script: string): string | undefined {
-  const line = sanitizeCodeModeText(script)
-    .split("\n")
-    .map((candidate) => candidate.trim())
-    .find(Boolean);
-  return line === undefined ? undefined : boundedCodeModePreview(line);
-}
-
 function parseCodeModeRenderedToolParameters(
   toolName: CodeModeRenderedToolName,
   parameters: CodeModeJsonValue,
@@ -100,7 +102,10 @@ function parseCodeModeRenderedToolParameters(
   if (toolName === "codemode_result") {
     return Value.Check(CodeModeResultParametersSchema, parameters) ? parameters : undefined;
   }
-  return Value.Check(CodeModeCancelParametersSchema, parameters) ? parameters : undefined;
+  if (toolName === "codemode_cancel") {
+    return Value.Check(CodeModeCancelParametersSchema, parameters) ? parameters : undefined;
+  }
+  return Value.Check(CodeModeSessionsParametersSchema, parameters) ? parameters : undefined;
 }
 
 function shortCodeModeSessionId(sessionId: string): string {
@@ -139,6 +144,9 @@ function codeModeSessionLifecycle(
   toolName: CodeModeRenderedToolName,
   details: CodeModeResultDetails,
 ): "Session reusable" | "Session closed" | "No reusable Session" {
+  if (details.result === "failed" && details.error.code === "eviction") {
+    return "Session closed";
+  }
   if (details.presentation !== undefined) {
     return details.presentation.session_state === "live" ? "Session reusable" : "Session closed";
   }
@@ -192,6 +200,16 @@ function appendCodeModeBlock(container: Container, language: "ts" | "json", cont
   );
 }
 
+function highlightedCodeModeSource(source: string): string {
+  return highlightCode(source, "typescript")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+function appendHighlightedCodeModeSource(container: Container, source: string): void {
+  container.addChild(new Text(highlightedCodeModeSource(source), 0, 0));
+}
+
 function boundedCodeModeText(text: string, maxLines: number): string {
   const safe = sanitizeCodeModeText(text);
   const truncated = truncateHead(safe, {
@@ -235,7 +253,10 @@ function renderCodeModeSummary(
 ): string {
   const presentation = details.presentation;
   const state = codeModeCellState(toolName, details);
-  const status = CODEMODE_STATUS_PRESENTATION[state];
+  const status =
+    details.result === "failed" && details.error.code === "eviction"
+      ? { color: "warning" as const, label: "■ reclaimed" }
+      : CODEMODE_STATUS_PRESENTATION[state];
   const activeToolNames = presentation?.active_tool_names.slice(0, 3) ?? [];
   const omittedActiveToolCount = Math.max(
     0,
@@ -268,7 +289,7 @@ function renderCodeModeSummary(
   return parts.join("  ");
 }
 
-/** Render one CodeMode tool call as a semantic operation with bounded source detail. */
+/** Render one CodeMode tool call with a bounded collapsed preview or complete expanded source. */
 export function renderCodeModeToolCall(
   toolName: CodeModeRenderedToolName,
   parameters: CodeModeJsonValue,
@@ -281,7 +302,9 @@ export function renderCodeModeToolCall(
       ? "Run Cell"
       : toolName === "codemode_result"
         ? "Poll"
-        : "Cancel";
+        : toolName === "codemode_cancel"
+          ? "Cancel"
+          : "List Sessions";
   const parsedParameters = parseCodeModeRenderedToolParameters(toolName, parameters);
   const executeParameters =
     toolName === "codemode_execute" &&
@@ -289,11 +312,14 @@ export function renderCodeModeToolCall(
     "script" in parsedParameters
       ? parsedParameters
       : undefined;
-  const sessionId = parsedParameters?.sessionId;
-  const preview =
-    executeParameters === undefined
-      ? undefined
-      : firstMeaningfulScriptLine(executeParameters.script);
+  const sessionId =
+    parsedParameters !== undefined && "sessionId" in parsedParameters
+      ? parsedParameters.sessionId
+      : undefined;
+  const source =
+    executeParameters === undefined ? undefined : sanitizeCodeModeText(executeParameters.script);
+  const oneLineSource = source !== undefined && !source.includes("\n") ? source : undefined;
+  const expansionHint = `${keyText("app.tools.expand")} to expand`;
   const container = new Container();
   container.addChild(
     new Text(
@@ -301,7 +327,12 @@ export function renderCodeModeToolCall(
         theme.fg("toolTitle", theme.bold("CodeMode")),
         theme.fg("accent", operation),
         theme.fg("muted", sessionId === undefined ? "new" : formatSessionPrefix(sessionId)),
-        preview === undefined ? undefined : theme.fg("dim", preview),
+        !expanded && oneLineSource !== undefined
+          ? highlightCode(oneLineSource, "typescript")[0]
+          : undefined,
+        !expanded && oneLineSource !== undefined
+          ? theme.fg("dim", `·  ${expansionHint}`)
+          : undefined,
       ]
         .filter((part): part is string => part !== undefined)
         .join("  "),
@@ -309,7 +340,17 @@ export function renderCodeModeToolCall(
       0,
     ),
   );
-  if (!expanded) return container;
+  if (!expanded) {
+    if (source === undefined || oneLineSource !== undefined) return container;
+    const sourceLines = source.split("\n");
+    const visibleSource = sourceLines.slice(0, CODEMODE_COLLAPSED_SCRIPT_LINES).join("\n");
+    appendHighlightedCodeModeSource(container, visibleSource);
+    const omittedLines = Math.max(0, sourceLines.length - CODEMODE_COLLAPSED_SCRIPT_LINES);
+    const omitted =
+      omittedLines === 0 ? "" : `… ${pluralizedCodeModeCount(omittedLines, "line")} omitted  ·  `;
+    container.addChild(new Text(theme.fg("dim", `  ${omitted}${expansionHint}`), 0, 0));
+    return container;
+  }
   container.addChild(new Spacer(1));
   if (sessionId !== undefined) appendCodeModeField(container, theme, "Session", sessionId);
   if (executeParameters === undefined) return container;
@@ -319,8 +360,41 @@ export function renderCodeModeToolCall(
     appendCodeModeField(container, theme, "Timeout", `${executeParameters.timeoutMs}ms`);
   container.addChild(new Spacer(1));
   container.addChild(new Text(theme.fg("muted", theme.bold("TypeScript")), 0, 0));
-  const script = boundedCodeModeText(executeParameters.script, CODEMODE_SCRIPT_MAX_LINES);
-  appendCodeModeBlock(container, "ts", script);
+  appendHighlightedCodeModeSource(container, source ?? "");
+  return container;
+}
+
+function renderCodeModeSessionsResult(
+  result: AgentToolResult<unknown>,
+  options: ToolRenderResultOptions,
+  theme: CodeModeRenderTheme,
+): Component {
+  if (!Value.Check(CodeModeSessionsResultSchema, result.details)) {
+    return renderCodeModeFallback(result, options, theme, false);
+  }
+  const sessions: CodeModeSessionsResult = result.details;
+  const summary = `${theme.fg("success", "✓")} ${pluralizedCodeModeCount(sessions.sessions.length, "session")}`;
+  if (!options.expanded) {
+    const hint = options.isPartial ? "" : `  ·  ${keyText("app.tools.expand")} to expand`;
+    return new Text(`${summary}${hint}`, 0, 0);
+  }
+  const container = new Container();
+  container.addChild(new Text(summary, 0, 0));
+  if (sessions.sessions.length === 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", "No live Sessions"), 0, 0));
+    return container;
+  }
+  container.addChild(new Spacer(1));
+  for (const session of sessions.sessions) {
+    container.addChild(
+      new Text(
+        `${theme.fg(session.state === "running" ? "accent" : "muted", session.state)}  ${sanitizeCodeModeText(session.sessionId)}  ${pluralizedCodeModeCount(session.cellCount, "cell")}  ${session.lastActivityAtMs}`,
+        0,
+        0,
+      ),
+    );
+  }
   return container;
 }
 
@@ -330,10 +404,12 @@ export function renderCodeModeToolResult(
   result: AgentToolResult<unknown>,
   options: ToolRenderResultOptions,
   theme: CodeModeRenderTheme,
-  parameters: CodeModeRenderedToolParameters,
   isError: boolean,
   formatSessionPrefix: CodeModeSessionPrefixFormatter = shortCodeModeSessionId,
 ): Component {
+  if (toolName === "codemode_sessions") {
+    return renderCodeModeSessionsResult(result, options, theme);
+  }
   if (!Value.Check(CodeModeResultDetailsSchema, result.details)) {
     return renderCodeModeFallback(result, options, theme, isError);
   }
@@ -409,13 +485,13 @@ export function renderCodeModeToolResult(
   return container;
 }
 
-/** Create the three CodeMode tools with semantic call and result Transcript renderers. */
+/** Create the four CodeMode tools with semantic call and result Transcript renderers. */
 export function createRenderedCodeModeToolDefinitions(
   operations: CodeModeToolOperations,
   executeDescription?: string,
   formatSessionPrefix: CodeModeSessionPrefixFormatter = shortCodeModeSessionId,
 ): ReturnType<typeof createCodeModeToolDefinitions> {
-  const [executeTool, resultTool, cancelTool] = createCodeModeToolDefinitions(
+  const [executeTool, resultTool, cancelTool, sessionsTool] = createCodeModeToolDefinitions(
     operations,
     executeDescription,
   );
@@ -436,7 +512,6 @@ export function createRenderedCodeModeToolDefinitions(
           result,
           options,
           theme,
-          context.args,
           context.isError,
           formatSessionPrefix,
         ),
@@ -457,7 +532,6 @@ export function createRenderedCodeModeToolDefinitions(
           result,
           options,
           theme,
-          context.args,
           context.isError,
           formatSessionPrefix,
         ),
@@ -478,7 +552,26 @@ export function createRenderedCodeModeToolDefinitions(
           result,
           options,
           theme,
-          context.args,
+          context.isError,
+          formatSessionPrefix,
+        ),
+    },
+    {
+      ...sessionsTool,
+      renderCall: (_args, theme, context) =>
+        renderCodeModeToolCall(
+          "codemode_sessions",
+          {},
+          theme,
+          context.expanded,
+          formatSessionPrefix,
+        ),
+      renderResult: (result, options, theme, context) =>
+        renderCodeModeToolResult(
+          "codemode_sessions",
+          result,
+          options,
+          theme,
           context.isError,
           formatSessionPrefix,
         ),

package/src/pi-codemode-extension.ts

@@ -39,7 +39,7 @@ import {
 } from "./pi-tool-bridge.js";
 
 const CODEMODE_EXECUTE_DESCRIPTION =
-  "Execute a TypeScript Cell in a persistent isolated Deno CodeMode Session. Top-level declarations become Notebook Bindings. Use the read-only tools object for registered Pi tools.";
+  "Execute a TypeScript Cell in a persistent isolated Deno CodeMode Session. Reuse a Session ID to retain Notebook Bindings; a new Session reclaims the least-recently-used idle Session at capacity. Use the read-only tools object for registered Pi tools.";
 
 type PiCodeModeGeneration = {
   readonly captured: CapturedPiAgentSession;
@@ -207,6 +207,10 @@ class PiCodeModeLifecycleController {
       },
       result: async (input) => coordinator.result(input.sessionId),
       cancel: async (input) => coordinator.cancel(input.sessionId),
+      sessions: async () => ({
+        result: "success",
+        sessions: [...coordinator.listSessions()],
+      }),
     };
     generation = {
       captured,
@@ -253,13 +257,16 @@ class PiCodeModeLifecycleController {
       return;
     }
 
-    for (const definition of createRenderedCodeModeToolDefinitions(
-      operations,
-      generation.executeDescription,
-      (sessionId) => coordinator.formatSessionPrefix(sessionId),
-    )) {
-      this.pi.registerTool(definition);
-    }
+    const [executeTool, resultTool, cancelTool, sessionsTool] =
+      createRenderedCodeModeToolDefinitions(
+        operations,
+        generation.executeDescription,
+        (sessionId) => coordinator.formatSessionPrefix(sessionId),
+      );
+    this.pi.registerTool(executeTool);
+    this.pi.registerTool(resultTool);
+    this.pi.registerTool(cancelTool);
+    this.pi.registerTool(sessionsTool);
     generation.toolsRegistered = true;
     this.synchronizeGeneration(generation);
   }