docs: clarify session close vs delete semantics (upstream sync #599)

.lastmerge

@@ -1 +1 @@
-4246289e484d42155c75267660d448d9ac4f9158
+4e1499dd23709022c720eaaa5457d00bf0cb3977

src/main/java/com/github/copilot/sdk/CopilotClient.java

@@ -208,7 +208,18 @@ private void verifyProtocolVersion(Connection connection) throws Exception {
     }
 
     /**
-     * Stops the client and closes all sessions.
+     * Disconnects from the Copilot server and closes all active sessions.
+     * <p>
+     * This method performs graceful cleanup:
+     * <ol>
+     * <li>Closes all active sessions (releases in-memory resources)</li>
+     * <li>Closes the JSON-RPC connection</li>
+     * <li>Terminates the CLI server process (if spawned by this client)</li>
+     * </ol>
+     * <p>
+     * Note: session data on disk is preserved, so sessions can be resumed later. To
+     * permanently remove session data before stopping, call
+     * {@link #deleteSession(String)} for each session first.
      *
      * @return A future that completes when the client is stopped
      */
@@ -469,9 +480,12 @@ public CompletableFuture<String> getLastSessionId() {
     }
 
     /**
-     * Deletes a session by ID.
+     * Permanently deletes a session and all its data from disk, including
+     * conversation history, planning state, and artifacts.
      * <p>
-     * This permanently removes the session and its conversation history.
+     * Unlike {@link CopilotSession#close()}, which only releases in-memory
+     * resources and preserves session data for later resumption, this method is
+     * irreversible. The session cannot be resumed after deletion.
      *
      * @param sessionId
      *            the ID of the session to delete

src/main/java/com/github/copilot/sdk/CopilotSession.java

@@ -58,6 +58,13 @@
  * A session maintains conversation state, handles events, and manages tool
  * execution. Sessions are created via {@link CopilotClient#createSession} or
  * resumed via {@link CopilotClient#resumeSession}.
+ * <p>
+ * {@code CopilotSession} implements {@link AutoCloseable}. Use the
+ * try-with-resources pattern for automatic cleanup, or call {@link #close()}
+ * explicitly. Closing a session releases in-memory resources but preserves
+ * session data on disk — the conversation can be resumed later via
+ * {@link CopilotClient#resumeSession}. To permanently delete session data, use
+ * {@link CopilotClient#deleteSession}.
  *
  * <h2>Example Usage</h2>
  *

src/site/markdown/documentation.md

@@ -617,8 +617,14 @@ See [ResumeSessionConfig](apidocs/com/github/copilot/sdk/json/ResumeSessionConfi
 
 ### Clean Up Sessions
 
+Closing a session releases its in-memory resources but **preserves session data on disk**, so
+it can be resumed later. Use `deleteSession()` to permanently remove session data from disk:
+
 ```java
-// Delete a specific session
+// Close a session (releases in-memory resources; session can be resumed later)
+session.close();
+
+// Permanently delete a session and all its data from disk (cannot be resumed)
 client.deleteSession(sessionId).get();
 ```
 

src/test/java/com/github/copilot/sdk/CopilotSessionTest.java

@@ -60,7 +60,7 @@ static void teardown() throws Exception {
     }
 
     /**
-     * Verifies that a session can be created and destroyed properly.
+     * Verifies that a session can be created and closed properly.
      *
      * @see Snapshot: session/should_receive_session_events
      */