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

[Copilot]

Ports upstream commit 4e1499d — clarifies the distinction between closing a session (releases in-memory resources, preserves disk state) and deleting a session (permanent, irreversible removal of all data from disk).

---

Before the change?

• stop() Javadoc said "Stops the client and closes all sessions" with no mention of disk persistence
• deleteSession() Javadoc said "permanently removes the session and its conversation history" with no contrast against close()
• CopilotSession class Javadoc had no lifecycle guidance on AutoCloseable semantics
• The "Clean Up Sessions" section in documentation.md only showed deleteSession() with no mention of close()

After the change?

• CopilotClient.stop() — updated Javadoc clarifies sessions are closed (in-memory resources released), disk data is preserved for later resumption, and directs users to deleteSession() for permanent removal
• CopilotClient.deleteSession() — updated Javadoc explicitly contrasts with close(): deletes conversation history, planning state, and artifacts from disk; irreversible
• CopilotSession class Javadoc — new paragraph explaining AutoCloseable semantics: close() preserves disk state; use deleteSession() to permanently remove data
• documentation.md — "Clean Up Sessions" section now shows both operations with explanatory prose:

// 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();

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• mvn spotless:apply has been run to format the code
• mvn clean verify passes locally

Does this introduce a breaking change?

• Yes
• No

---

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• checkstyle.org
  • Triggering command: /opt/hostedtoolcache/CodeQL/2.24.2/x64/codeql/tools/linux64/java/bin/java /opt/hostedtoolcache/CodeQL/2.24.2/x64/codeql/tools/linux64/java/bin/java -jar /opt/hostedtoolcache/CodeQL/2.24.2/x64/codeql/xml/tools/xml-extractor.jar --fileList=/tmp/codeql-scratch-a0b8ba07f7cabbfc/dbs/java/working/files-to-index10455151215928970412.list --sourceArchiveDir=/tmp/codeql-scratch-a0b8ba07f7cabbfc/dbs/java/src --outputDir=/tmp/codeql-scratch-a0b8ba07f7cabbfc/dbs/java/trap/java which .0.18-8/x64/bin/git (dns block)
• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh gh pr list --head copilot/sync-upstream-changes-c4886a91-010c-45c9-8dcc-6c8f8229fe9a --json number,title va/copilot-sdk-java/target/copilot-sdk/test/harness/node_modules/@github/copilot-linux-x64/copilot /tmp/copilot-tesgit remote nfig/composer/veb5e56efe8253000b3a050623ebaa22b739fc7d16:src/test/java/com/github/copilot/sdk/CopilotSessionTest.java va/copilot-sdk-java/target/copilot-sdk/test/harness/node_modules/@github/copilot-linux-x64/copilot git git which k/copilot-sdk-java/copilot-sdk-java/target/node_modules/.bin/sh (http block)
  • Triggering command: /usr/bin/gh gh pr edit 177 --repo copilot-community-sdk/copilot-sdk-java --add-label upstream-sync _ _ _ _ gh /.bin/tsx /usr/lib/jvm/temremote sh 43:44:46 which tnet/tools/which-Dcodeql.chainer.v2=/tmp/codeql.RTE3SeP2 which (http block)
• https://api.github.com/repos/copilot-community-sdk/copilot-sdk-java/issues/177/labels
  • Triggering command: /usr/bin/curl curl -s -X POST -H Authorization: ****** Content-Type: application/json -d {"labels":["upstream-sync"]} REDACTED git -C b/copilot/sdk/CopilotClient.java remote /lib/jspawnhelper tsx server.ts which ot-sdk/test/harncopilot/sync-upstream-changes-c4886a91-010c-45c9-8dcc-6c8f8229fe9a /lib/jspawnhelper (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.