Add sessionIdleTimeoutMs option to CopilotClientOptions

Add a new optional sessionIdleTimeoutMs field to CopilotClientOptions that
allows consumers to configure the server-wide session idle timeout. When set
to a positive value, the SDK passes --session-idle-timeout to the CLI process.

Sessions have no idle timeout by default (infinite lifetime). The minimum
configurable value is 300000ms (5 minutes).

Also updates the session persistence documentation to reflect the new
default behavior and configuration option.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: MackinnonBuck

docs/features/session-persistence.md

@@ -433,14 +433,26 @@ await client.deleteSession("user-123-task-456");
 
 ## Automatic Cleanup: Idle Timeout
 
-The CLI has a built-in 30-minute idle timeout. Sessions without activity are automatically cleaned up:
+By default, sessions have **no idle timeout** and live indefinitely until explicitly disconnected or deleted. You can optionally configure a server-wide idle timeout via `CopilotClientOptions.sessionIdleTimeoutMs`:
+
+```typescript
+const client = new CopilotClient({
+  sessionIdleTimeoutMs: 30 * 60 * 1000, // 30 minutes
+});
+```
+
+When a timeout is configured, sessions without activity for that duration are automatically cleaned up. The minimum value is 5 minutes (300,000ms). Set to `0` or omit to disable.
+
+> **Note:** This option only applies when the SDK spawns the runtime process. When connecting to an existing server via `cliUrl`, the server's own timeout configuration applies.
 
 ```mermaid
 flowchart LR
-    A["⚡ Last Activity"] --> B["⏳ 25 min<br/>timeout_warning"] --> C["🧹 30 min<br/>destroyed"]
+    A["⚡ Last Activity"] --> B["⏳ ~5 min before<br/>timeout_warning"] --> C["🧹 Timeout<br/>destroyed"]
 ```
 
-Listen for idle events to know when work completes:
+Sessions with active work (running commands, background agents) are always protected from idle cleanup, regardless of the timeout setting.
+
+Listen for idle events to react to session inactivity:
 
 ```typescript
 session.on("session.idle", (event) => {

nodejs/src/client.ts

@@ -339,6 +339,7 @@ export class CopilotClient {
             // Default useLoggedInUser to false when githubToken is provided, otherwise true
             useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),
             telemetry: options.telemetry,
+            sessionIdleTimeoutMs: options.sessionIdleTimeoutMs ?? 0,
         };
     }
 
@@ -1385,6 +1386,10 @@ export class CopilotClient {
                 args.push("--no-auto-login");
             }
 
+            if (this.options.sessionIdleTimeoutMs !== undefined && this.options.sessionIdleTimeoutMs > 0) {
+                args.push("--session-idle-timeout", this.options.sessionIdleTimeoutMs.toString());
+            }
+
             // Suppress debug/trace output that might pollute stdout
             const envWithoutNodeDebug = { ...this.options.env };
             delete envWithoutNodeDebug.NODE_DEBUG;

nodejs/src/types.ts

@@ -182,6 +182,15 @@ export interface CopilotClientOptions {
      * instead of the server's default local filesystem storage.
      */
     sessionFs?: SessionFsConfig;
+
+    /**
+     * Server-wide idle timeout for sessions in milliseconds.
+     * Sessions without activity for this duration are automatically cleaned up.
+     * Set to 0 or omit to disable (sessions live indefinitely).
+     * Minimum value: 300000 (5 minutes).
+     * @default 0 (disabled)
+     */
+    sessionIdleTimeoutMs?: number;
 }
 
 /**