docs: retire registrations at whole-session closeout

CHANGELOG.md

@@ -4,6 +4,9 @@ Notable changes to Swarmail. Versions follow [semantic versioning](https://semve
 
 ## Unreleased
 
+- Require agents to record whole-session closeouts and retire their own project
+  registrations, with read-only verification and task/pause boundaries.
+
 - A prompt no longer retries a pending registration whose edit checkout has been deleted. The server refuses a
   worktree that is gone, so the hook warned on every prompt until the session ended. The pending entry is dropped;
   the session's next edit registers it again.

docs/usage.md

@@ -56,6 +56,32 @@ checkout, unless a project already exists under that exact path.
   later does not change old inbox entries. Messages predating this field have
   a null location.
 
+## Ending the entire session
+
+Record the closeout when the user ends the entire session or accepts an option
+that closes it. Do the same when you conclude that the entire session is finished
+with nothing remaining. Retire your own registration in every project you joined.
+Completing one task, waiting for an answer, pausing or deferring a
+candidate while continuing the session does not trigger retirement.
+
+1. Release resources you own and send any still-required dependency notices.
+2. Save completed work, deferred items or blockers, and resource-release results
+   in the session's durable record.
+3. Call `retire_agent` for your own name in each registered project.
+4. Check the `retired:true` result, then confirm your name is absent from the
+   read-only `list_agents` result. Use a limit that covers the complete roster;
+   a full result can omit agents and cannot verify absence.
+
+If the roster remains full at the maximum limit of 1000, record absence
+verification as incomplete. Keep the `retired:true` result as evidence of the
+retirement call; it does not establish subsequent roster absence.
+
+Finish mail, registration and file-reservation operations before retiring.
+Registering, sending, reading mail or reserving files as yourself can reactivate
+the registration.
+Retirement retains existing messages and rejects new mail to that registration;
+it does not archive the host conversation or delete its checkout.
+
 ## Status evidence
 
 `list_agents` and `whois` return recorded metadata and activity timestamps.
@@ -64,8 +90,8 @@ acknowledgment timestamps are observations, not proof that a model accepted work
 
 `swarmail ping` observes a pong generated while the recipient wake hook waits.
 Success establishes that response at that time, not a model reply or future
-delivery. A timeout does not prove the session ended. Confirm session state
-with the owning host before retiring an agent.
+delivery. A timeout does not prove the session ended. Before retiring another
+agent, confirm with its owning host that its session has ended.
 
 ## When to send mail
 

src/guidance.ts

@@ -16,6 +16,10 @@ export const AGENT_GUIDANCE =
   "Before shared work, check your inbox and roster; an empty roster does not prove a checkout is unused. " +
   "After a mail notice, fetch unread bodies and mark each page read; repeat only after a full page. " +
   "The CLI equivalent is swarmail inbox --session.\n\n" +
+  "When the user ends the entire session, accepts a whole-session All done option, or you conclude that the entire session is finished with nothing remaining, record the closeout and retire your own registration in each project you joined. " +
+  "First release your owned resources and send any still-required dependency notices. Record completed work, deferred items or blockers, and the resource-release result in the session's durable record. " +
+  "Call retire_agent and check its retired:true result, then confirm your name is absent from list_agents without a truncating limit. If the roster result is full, record absence verification as incomplete. Finish mail, registration and file-reservation operations before retiring; they can reactivate you. A completed task, an unanswered offer, a wait or a pause does not end the entire session.\n\n" +
+  "Before retiring another agent, confirm with its owning host that its session has ended; roster data or a ping timeout is insufficient.\n\n" +
   SENDING_GUIDANCE +
   "\n\nUse quiet delivery only for normal/low informational mail without an acknowledgement request. " +
   "Keep actionable handoffs, requested results, blockers and urgent mail on wake delivery. " +

src/tools.ts

@@ -338,6 +338,8 @@ export const TOOLS: Tool[] = [
   {
     name: "retire_agent",
     description:
+      "At an agreed whole-session closeout or a whole-session completion with nothing remaining, record the closeout, release owned resources and finish required dependency notices, then retire your own registration in every project you joined. " +
+      "Before retiring another agent, confirm with its owning host that its session has ended; roster data or a ping timeout is insufficient. " +
       "Retire an agent whose session has ended, so it no longer appears in list_agents and " +
       "new messages to it fail. Its messages stay. unretire_agent reverses it, and so does " +
       "the agent registering again or sending, reading mail or reserving files as itself. " +