primcli 1.67.0 → 1.69.0

package/dist/{machine-session-s6LvMvRd.js → machine-session-CKmn5bvB.js}

@@ -1,8 +1,8 @@
 import { S as __exportAll } from "./repeats-BL7ZC-_6-BZ-MphTV.js";
 import { B as parseOwnerMemberAddress, F as agentProfilesDirectory, I as connectedAgentIdentity, L as connectedApiBaseUrl, M as AgentConnectionSetupError, N as agentProfileDirectory, P as agentProfileName, R as loadConnectedAgentProfile, U as saveConnectedAgentProfile, V as profileAlreadyConnectedMessage, W as PrimitiveApiClient, j as AGENT_PROFILE_ENV, x as loadCliCredentials, z as parseConnectedAgentProfile } from "./cli-config-DMszFbGn.js";
-import { Ct as cliInvocation, Jn as putAgentContactPolicy, Jt as refreshStoredCliCredentials, Pn as listDomains, Tt as defaultConnectionName, Vn as listSentEmails, Yn as putContact, an as deleteAgentContact, ar as sendEmail, jn as listContacts, kn as listAgentContacts, mn as getContact, nr as searchEmails, on as deleteContact, pn as getAgentContactPolicy, qn as putAgentContact, vn as getEmail } from "./api-command-Dh4hs7kh.js";
+import { Ct as cliInvocation, Jn as putAgentContactPolicy, Jt as refreshStoredCliCredentials, Pn as listDomains, Tt as defaultConnectionName, Vn as listSentEmails, Yn as putContact, an as deleteAgentContact, ar as sendEmail, jn as listContacts, kn as listAgentContacts, mn as getContact, nr as searchEmails, on as deleteContact, pn as getAgentContactPolicy, qn as putAgentContact, vn as getEmail } from "./api-command-C58Oh38I.js";
 import { _ as acquireListenLock, c as mailTime, d as readMailJson, f as removeMailFile, g as ListenStateError, h as writeMailJson, i as mailId, l as privateMailDirectory, o as mailObject, r as mailAddress, s as mailString } from "./shared-mail-files-MwlVE90c.js";
-import { _ as detectAgentRuntime, a as NotificationRetryError, d as defaultSessionSocket, f as NativeSessionDisconnectedError, l as SESSION_UUID, t as notificationScope, u as connectNativeSession, v as installConnectSkill, x as readBundledConnectSkill } from "./notify-session-CeKAcPIX.js";
+import { _ as detectAgentRuntime, a as NotificationRetryError, d as defaultSessionSocket, f as NativeSessionDisconnectedError, l as SESSION_UUID, t as notificationScope, u as connectNativeSession, v as installConnectSkill, x as readBundledConnectSkill } from "./notify-session-CVZtEboh.js";
 import { a as scopedChatSenderTrust } from "./scoped-chat-Dsark9hm.js";
 import { l as stopBackgroundListen, r as backgroundListenStatus } from "./listen-background--0peztKE.js";
 import { t as readSharedMailOwner } from "./shared-mail-watch-DtKpsgg8.js";
@@ -1674,8 +1674,9 @@ function readSessionRecord(configDir, session) {
 			agentInfo: row.agentInfo === "created" || row.agentInfo === "already_present" ? row.agentInfo : null,
 			registeredAt: typeof row.registeredAt === "string" ? row.registeredAt : (/* @__PURE__ */ new Date(0)).toISOString(),
 			endedAt: typeof row.endedAt === "string" ? row.endedAt : null,
-			disconnect: row.disconnect === "done" || row.disconnect === "pending" || row.disconnect === "pending_enrollment" || row.disconnect === "deferred" ? row.disconnect : typeof row.endedAt === "string" ? "done" : null,
+			disconnect: row.disconnect === "done" || row.disconnect === "pending" || row.disconnect === "pending_enrollment" || row.disconnect === "deferred" || row.disconnect === "kept" ? row.disconnect : typeof row.endedAt === "string" ? "done" : null,
 			deferredUntil: typeof row.deferredUntil === "string" ? row.deferredUntil : null,
+			revokeOnEnd: row.revokeOnEnd === true,
 			endReason: typeof row.endReason === "string" && REASON.test(row.endReason) ? row.endReason : null,
 			release: parseRelease(row.release)
 		};
@@ -1741,6 +1742,7 @@ function releasedRecord(record, reason, at, current) {
 		endedAt: null,
 		disconnect: null,
 		deferredUntil: null,
+		revokeOnEnd: false,
 		endReason: null,
 		release: {
 			at: at.toISOString(),
@@ -2505,7 +2507,7 @@ async function runAddressNotesRequest(client, request) {
 		if (request.ifAbsent) condition = { if_absent: true };
 		else if (ifVersion) condition = { if_version: ifVersion };
 		else try {
-			condition = { if_version: (await getNote(client, address, name)).version };
+			condition = { if_version: (await getNote(client, address, name, request.signal)).version };
 		} catch (error) {
 			if (!(error instanceof AddressNotesApiError) || error.status !== 404) throw error;
 			condition = { if_absent: true };
@@ -2523,10 +2525,11 @@ async function runAddressNotesRequest(client, request) {
 				...request.visibility ? { visibility: request.visibility } : {}
 			},
 			headers: { "Content-Type": "application/json" },
-			responseStyle: "fields"
+			responseStyle: "fields",
+			...request.signal ? { signal: request.signal } : {}
 		})), address, name);
 	}
-	const version = ifVersion ?? (await getNote(client, address, name)).version;
+	const version = ifVersion ?? (await getNote(client, address, name, request.signal)).version;
 	const data = await result(client.delete({
 		security,
 		url: "/address-notes/{address}/{name}",
@@ -2535,12 +2538,127 @@ async function runAddressNotesRequest(client, request) {
 			name
 		},
 		query: { if_version: version },
-		responseStyle: "fields"
+		responseStyle: "fields",
+		...request.signal ? { signal: request.signal } : {}
 	}));
 	if (!data || typeof data !== "object" || Array.isArray(data) || typeof data.deleted !== "boolean") throw new Error("The address notes API returned an invalid deletion response.");
 	return data;
 }
 //#endregion
+//#region src/oclif/agent-resume-note.ts
+/**
+* The address note holding the command that resumes the coding session an
+* agent is bound to, so an app can offer to reopen that exact session.
+*/
+const RESUME_NOTE_NAME = "AGENT_RESUME";
+/**
+* Each note request gets this long. The note is best effort and runs inside
+* registration, connect, disconnect and their hooks, so a stalled request
+* must never hold them up.
+*/
+const NOTE_REQUEST_TIMEOUT_MS = 1e4;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The AGENT_RESUME value for a session: `claude --resume <uuid>` for Claude
+* Code or `codex resume <uuid>` for Codex, with the ID lowercased. Any other
+* runtime, or an ID that is not a UUID, has no value.
+*/
+function resumeNoteValue(runtime, sessionId) {
+	const id = sessionId?.trim().toLowerCase() ?? "";
+	if (!UUID.test(id)) return null;
+	if (runtime === "claude") return `claude --resume ${id}`;
+	if (runtime === "codex") return `codex resume ${id}`;
+	return null;
+}
+function client(profile, fetchImpl) {
+	return new PrimitiveApiClient({
+		apiKey: profile.api_key,
+		apiBaseUrl: profile.api_base_url,
+		...fetchImpl ? { fetch: fetchImpl } : {}
+	}).client;
+}
+/** The current note, or null when the address has none. */
+async function currentNote(api, address, timeoutMs) {
+	try {
+		return await runAddressNotesRequest(api, {
+			action: "get",
+			address,
+			name: RESUME_NOTE_NAME,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (error) {
+		if (error instanceof AddressNotesApiError && error.status === 404) return null;
+		throw error;
+	}
+}
+/**
+* Write the AGENT_RESUME note for a connected profile's address. Skips the
+* write when the note already holds the same value, so a resume hook that
+* runs on every start does not rewrite it. `rewrite` writes it anyway, so a
+* new claim leaves the note no older than the connection it belongs to.
+* Never throws.
+*/
+async function publishResumeNote(options) {
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const value = resumeNoteValue(options.runtime, options.sessionId);
+	if (value === null) return "skipped";
+	try {
+		const profile = loadConnectedAgentProfile(options.configDir, options.profileName);
+		if (!profile) return "skipped";
+		const api = client(profile, options.fetch);
+		const address = profile.agent_address;
+		const current = await currentNote(api, address, timeoutMs);
+		if (current?.value === value && !options.rewrite) return "unchanged";
+		await runAddressNotesRequest(api, {
+			action: "set",
+			address,
+			name: RESUME_NOTE_NAME,
+			value,
+			visibility: "private",
+			signal: AbortSignal.timeout(timeoutMs),
+			...current?.version ? { ifVersion: current.version } : { ifAbsent: true }
+		});
+		return "written";
+	} catch {
+		return "failed";
+	}
+}
+/**
+* Delete the AGENT_RESUME note with this credential, before it is revoked.
+* Never throws.
+*/
+async function clearResumeNote(profile, fetchImpl, timeoutMs = NOTE_REQUEST_TIMEOUT_MS) {
+	try {
+		const api = client(profile, fetchImpl);
+		const current = await currentNote(api, profile.agent_address, timeoutMs);
+		if (!current) return "absent";
+		await runAddressNotesRequest(api, {
+			action: "delete",
+			address: profile.agent_address,
+			name: RESUME_NOTE_NAME,
+			signal: AbortSignal.timeout(timeoutMs),
+			...current.version ? { ifVersion: current.version } : {}
+		});
+		return "cleared";
+	} catch {
+		return "failed";
+	}
+}
+/**
+* Delete the AGENT_RESUME note of a connected profile's address, for a
+* connection that binds no resumable session, so a command left by an older
+* session never points at the wrong conversation. Never throws.
+*/
+async function clearProfileResumeNote(options) {
+	try {
+		const profile = loadConnectedAgentProfile(options.configDir, options.profileName);
+		if (!profile) return "skipped";
+		return await clearResumeNote(profile, options.fetch);
+	} catch {
+		return "failed";
+	}
+}
+//#endregion
 //#region src/oclif/agent-disconnect.ts
 var AgentDisconnectError = class extends Error {};
 /** The profile no longer holds the credential the caller expected to revoke. */
@@ -2674,6 +2792,12 @@ async function disconnectAgent(params) {
 		}) : null;
 		if (receiver && !receiverStopped(receiver)) throw new AgentDisconnectError("The bound receiver has not confirmed stopping. The connection and credential were preserved. Check listener status before retrying.");
 		const previous = confirmedLocally(directory, profile);
+		let resumeNote = "skipped";
+		if (!previous) try {
+			resumeNote = await (params.clearResumeNote ?? clearResumeNote)(profile, params.fetch);
+		} catch {
+			resumeNote = "failed";
+		}
 		const revocation = previous ? "previously_confirmed" : await revoke(profile, params.fetch);
 		if (!previous) try {
 			writeMailJson(confirmationPath(directory, profile), {
@@ -2706,7 +2830,8 @@ async function disconnectAgent(params) {
 			identity: connectedAgentIdentity(profileName, profile),
 			receiver,
 			revocation,
-			externalHook
+			externalHook,
+			resumeNote
 		};
 	} catch (error) {
 		if (error instanceof AgentDisconnectError) throw error;
@@ -2816,6 +2941,7 @@ async function clearRevokedAddresses(params) {
 				stopReceiver: params.stopReceiver,
 				now: params.now,
 				env: params.env,
+				clearResumeNote: async () => "skipped",
 				expected: {
 					address: checked.agent_address,
 					invitationHash: checked.invitation_hash
@@ -4026,6 +4152,17 @@ function defaults(options) {
 			});
 		},
 		seedAgentInfo: (profileName, value) => seedAgentInfoNote(options.configDir, profileName, value),
+		publishResumeNote: (profileName, runtime, session) => publishResumeNote({
+			configDir: options.configDir,
+			profileName,
+			runtime,
+			sessionId: session,
+			rewrite: true
+		}),
+		clearResumeNote: (profileName) => clearProfileResumeNote({
+			configDir: options.configDir,
+			profileName
+		}),
 		refreshOwnerMemberAddress: (profileName) => refreshOwnerMemberAddress({
 			configDir: options.configDir,
 			profileName
@@ -4222,6 +4359,12 @@ async function runAgentConnect(options) {
 			reason: "already_present"
 		});
 	}
+	let resumeNote = "skipped";
+	if (verified) try {
+		resumeNote = session && runtime ? await dependencies.publishResumeNote(result.identity.profileName, runtime, session) : await dependencies.clearResumeNote(result.identity.profileName);
+	} catch {
+		resumeNote = "failed";
+	}
 	const receiving = receiver === "external" ? {
 		...result.receiving,
 		state: externalReceivingState(externalHook),
@@ -4277,6 +4420,7 @@ async function runAgentConnect(options) {
 		receiving,
 		...result.ownerNotifications ? { ownerNotifications: result.ownerNotifications } : {},
 		agentInfo: agentInfoState,
+		resumeNote,
 		skipped,
 		warnings,
 		selectProfile: `PRIMITIVE_AGENT_PROFILE=${result.identity.profileName}`,
@@ -4799,6 +4943,8 @@ async function enrollAgent(params) {
 var machine_session_exports = /* @__PURE__ */ __exportAll({
 	HOOK_END_GRACE_MS: () => HOOK_END_GRACE_MS,
 	OMP_MAIN: () => OMP_MAIN,
+	RECONNECT_HINT: () => RECONNECT_HINT,
+	STALE_SESSION_MS: () => STALE_SESSION_MS,
 	agentConnectionState: () => agentConnectionState,
 	agentInfoForSession: () => agentInfoForSession,
 	connectedProfilesForSession: () => connectedProfilesForSession,
@@ -4811,9 +4957,11 @@ var machine_session_exports = /* @__PURE__ */ __exportAll({
 	readClaudeHookInput: () => readClaudeHookInput,
 	registerSession: () => registerSession,
 	retryPendingDisconnects: () => retryPendingDisconnects,
+	revokeStaleSessionAgents: () => revokeStaleSessionAgents,
 	revokeWithMemberLogin: () => revokeWithMemberLogin,
 	runDetached: () => runDetached,
 	runtimeSessionId: () => runtimeSessionId,
+	staleSessionAgents: () => staleSessionAgents,
 	workspaceName: () => workspaceName
 });
 /** The repository (or directory) a session works in, for its default name. */
@@ -5158,7 +5306,7 @@ async function cleanUpReplacedRegistration(configDir, record, current, deps, env
 		await deps.revokeByAddress(configDir, address, fetchImpl);
 	} catch {}
 }
-async function disconnectSessionAgent(configDir, record, deps, env, fetchImpl, enrollmentSettled = false) {
+async function disconnectSessionAgent(configDir, record, deps, env, fetchImpl, enrollmentSettled = false, report = {}) {
 	try {
 		const current = loadConnectedAgentProfile(configDir, record.profile);
 		if (current) {
@@ -5168,7 +5316,7 @@ async function disconnectSessionAgent(configDir, record, deps, env, fetchImpl, e
 			};
 			if (!holdsRegisteredCredential(configDir, record, current)) return await release(current);
 			try {
-				await deps.disconnect({
+				const disconnected = await deps.disconnect({
 					configDir,
 					profileName: record.profile,
 					fetch: fetchImpl,
@@ -5178,6 +5326,7 @@ async function disconnectSessionAgent(configDir, record, deps, env, fetchImpl, e
 						invitationHash: current.invitation_hash
 					}
 				});
+				if (disconnected?.resumeNote) report.resumeNote = disconnected.resumeNote;
 			} catch (error) {
 				if (!(error instanceof AgentCredentialChangedError)) throw error;
 				const holder = loadConnectedAgentProfile(configDir, record.profile);
@@ -5197,8 +5346,8 @@ async function disconnectSessionAgent(configDir, record, deps, env, fetchImpl, e
 		return "pending";
 	}
 }
-async function finishSessionDisconnect(configDir, record, deps, env, fetchImpl, enrollmentSettled = false) {
-	const outcome = await disconnectSessionAgent(configDir, record, deps, env, fetchImpl, enrollmentSettled);
+async function finishSessionDisconnect(configDir, record, deps, env, fetchImpl, enrollmentSettled = false, report = {}) {
+	const outcome = await disconnectSessionAgent(configDir, record, deps, env, fetchImpl, enrollmentSettled, report);
 	const saved = await updateSessionRecord(configDir, record.session, (current) => {
 		if (current?.createdBy !== "session-register" || current.disconnect === "done") return current;
 		if (outcome === "released") return releasedRecord(current, "credential_changed", deps.now());
@@ -5221,8 +5370,15 @@ function withDefined(defaults, overrides) {
 		...Object.fromEntries(Object.entries(overrides ?? {}).filter(([, value]) => value !== void 0))
 	};
 }
+/**
+* What to do about an agent that was disconnected in Primitive. The owner's
+* Reconnect re-invites the same address, and pasting that instruction into
+* the session claims it into the session's profile again.
+*/
+const RECONNECT_HINT = "To get the same address back, the owner can use Reconnect on this agent in the Primitive app and paste the instruction it gives into this session.";
 const HELD_DETAIL = "This session already receives as another connected profile, so this profile's receive hooks were not added. Run `primitive machine doctor --fix --profile <profile>` to bind it deliberately.";
-const ENDED_DETAIL = "This session ended, so its agent was disconnected. A new address is never created for the same session.";
+const ENDED_DETAIL = `This session ended and its agent was disconnected. A new address is never created for the same session. ${RECONNECT_HINT}`;
+const ENDED_KEPT_DETAIL = "This session ended while it was registering. Its agent is kept, and resuming the session reconnects it at the same address.";
 const ENDED_DEFERRED_DETAIL = "This session ended moments ago. Its agent is disconnected after a short wait unless the session starts again first.";
 const RELEASED_DETAIL = "This session's profile now holds an agent connected some other way, so it was left connected.";
 const ENDED_PENDING_DETAIL = "This session ended, but disconnecting its agent has not been confirmed yet; `primitive machine doctor --fix` retries it.";
@@ -5239,6 +5395,13 @@ async function registerSession(options) {
 		installClaudeHook: installClaudeWakeHook,
 		seedAgentInfo: (configDir, profileName, value) => seedAgentInfoNote(configDir, profileName, value, options.fetch),
 		connectionState: (profile) => agentConnectionState(profile, options.fetch),
+		publishResumeNote: (configDir, profileName, runtime, sessionId) => publishResumeNote({
+			configDir,
+			profileName,
+			runtime,
+			sessionId,
+			fetch: options.fetch
+		}),
 		ompSession: ompProcessSession,
 		...DISCONNECT_DEFAULTS
 	}, options.dependencies);
@@ -5313,6 +5476,12 @@ async function registerSession(options) {
 			status: "ended",
 			detail: ENDED_DEFERRED_DETAIL
 		};
+		if (current.disconnect === "kept") return {
+			...known,
+			address: current.address,
+			status: "ended",
+			detail: ENDED_KEPT_DETAIL
+		};
 		const outcome = current.disconnect === "done" && !enrolledNow ? "done" : await finishSessionDisconnect(options.configDir, current, deps, env, options.fetch, enrolledNow);
 		if (outcome === "released") return {
 			...known,
@@ -5340,15 +5509,17 @@ async function registerSession(options) {
 		endedAt: null,
 		disconnect: null,
 		deferredUntil: null,
+		revokeOnEnd: false,
 		endReason: null,
 		release: null
 	});
 	try {
-		let record = await updateSessionRecord(options.configDir, sessionId, (current) => current?.endedAt && current.disconnect === "deferred" ? {
+		let record = await updateSessionRecord(options.configDir, sessionId, (current) => current?.endedAt && (current.disconnect === "deferred" || current.disconnect === "kept") ? {
 			...current,
 			endedAt: null,
 			disconnect: null,
 			deferredUntil: null,
+			revokeOnEnd: false,
 			endReason: null
 		} : current);
 		if (record?.endedAt) return await ended(record);
@@ -5361,6 +5532,14 @@ async function registerSession(options) {
 				agentInfo: seeded
 			} : current);
 		};
+		const finishResumeNote = async () => {
+			if (runtime === "omp") return {};
+			try {
+				return { resumeNote: await deps.publishResumeNote(options.configDir, profileName, runtime, sessionId) };
+			} catch {
+				return { resumeNote: "failed" };
+			}
+		};
 		const claudeHook = (agentAddress) => {
 			const outcome = deps.installClaudeHook({
 				cliPath: options.cliPath,
@@ -5387,7 +5566,7 @@ async function registerSession(options) {
 			if (state === "revoked" || state === "rejected") return {
 				...withAddress,
 				status: "revoked",
-				detail: "This session's agent was disconnected in Primitive. No new address was created. `primitive machine doctor --fix` removes the stale local profile."
+				detail: `This session's agent was disconnected in Primitive, so it cannot receive mail. No new address was created. ${RECONNECT_HINT}`
 			};
 			if (state === "unavailable") return {
 				...withAddress,
@@ -5403,10 +5582,12 @@ async function registerSession(options) {
 			if (state === "connected") {
 				const hooked = installHook(existing);
 				await finishAgentInfo();
+				const resumeNote = await finishResumeNote();
 				return {
 					...withAddress,
 					receiving: RECEIVING[runtime],
 					status: "already_registered",
+					...resumeNote,
 					detail: hooked === "installed" ? "This session is already connected." : hooked === "held" ? HELD_DETAIL : "This session is already connected, but its receive hook could not be installed. Run `primitive machine doctor`."
 				};
 			}
@@ -5414,7 +5595,7 @@ async function registerSession(options) {
 			...known,
 			address: record.address,
 			status: "removed",
-			detail: "This session's local profile was removed. No new address was created for the same session."
+			detail: `This session's local profile was removed. No new address was created for the same session. ${RECONNECT_HINT}`
 		};
 		let credentials;
 		try {
@@ -5474,7 +5655,11 @@ async function registerSession(options) {
 		const status = result.connection.status;
 		let hooked = "installed";
 		if (runtime === "claude" && submitted && status !== "owner_inactive") hooked = claudeHook(address);
-		if (status === "connected") await finishAgentInfo();
+		let resumeNote = {};
+		if (status === "connected") {
+			await finishAgentInfo();
+			resumeNote = await finishResumeNote();
+		}
 		const withAddress = {
 			...known,
 			address,
@@ -5486,6 +5671,7 @@ async function registerSession(options) {
 			status: "registered",
 			name,
 			nameIsDefault: name === record.name,
+			...resumeNote,
 			detail: hooked === "installed" ? `Connected as ${address}.` : hooked === "held" ? `Connected as ${address}. ${HELD_DETAIL}` : `Connected as ${address}, but the receive hook could not be installed. Run \`primitive machine doctor\`.`
 		};
 		if (status === "revoked" || status === "owner_inactive") return {
@@ -5512,24 +5698,62 @@ async function registerSession(options) {
 	}
 }
 /**
-* How long an end from a runtime hook waits before disconnecting. A runtime
+* How long an end from a runtime hook waits before it takes effect. A runtime
 * reports the same end for a restart, a switch to another session and a real
 * exit, so the hook cannot tell them apart; a start of the same session
-* within this window cancels the end and keeps its agent.
+* within this window cancels the end.
 */
 const HOOK_END_GRACE_MS = 3e5;
+/**
+* How long an ended session keeps the agent `session-register` created for
+* it. A session that has not started again for this long has its agent
+* disconnected by `machine doctor --fix` or the next registration on this
+* machine, so closed sessions do not keep live credentials forever.
+*/
+const STALE_SESSION_MS = 2592e6;
 /** The end of this record is a hook's, still waiting. */
 function deferredEnd(record) {
 	return Boolean(record?.endedAt) && record?.disconnect === "deferred";
 }
+/** Removes an ended session's own exact-session receive hooks. Best effort. */
+function removeSessionHooks(configDir, record, deps, env) {
+	if (record.runtime !== "claude" || !record.address) return;
+	try {
+		deps.uninstallHook({
+			configDir,
+			profileName: record.profile,
+			agentAddress: record.address,
+			sessionId: record.session,
+			env
+		});
+	} catch {}
+}
 /**
-* Disconnect the agent a session got from `session-register`. Agents
-* connected any other way are left alone, including a credential connected
-* later into the same profile. The end is recorded first, under the record's
-* lock, so a registration still enrolling sees it and disconnects the agent
-* it creates. With `graceMs` (an end reported by a runtime hook) the
-* disconnect waits that long, and a start of the same session meanwhile
-* cancels it. Never throws.
+* The record of an end that keeps the agent. Its exact-session receive hooks
+* are removed in the same step, under the record's lock, so a start of the
+* same session that clears the end afterwards reinstalls them.
+*/
+function keptEnd(configDir, current, deps, env, at) {
+	removeSessionHooks(configDir, current, deps, env);
+	return {
+		...current,
+		endedAt: current.endedAt ?? at.toISOString(),
+		disconnect: "kept",
+		deferredUntil: null,
+		revokeOnEnd: false
+	};
+}
+const KEPT_DETAIL = "This session is marked ended. Its agent stays connected, so resuming the session keeps the same address; it is disconnected only if the session does not start again for 30 days. Pass --revoke to disconnect it now.";
+/**
+* Record that a session ended. By default the agent `session-register`
+* created for it stays connected, with its credential and profile, so a
+* resume of the same session keeps its address; only its exact-session
+* receive hooks are removed. With `revoke` the agent is disconnected instead.
+* Agents connected any other way are left alone either way, including a
+* credential connected later into the same profile. The end is recorded
+* first, under the record's lock, so a registration still enrolling sees it.
+* With `graceMs` (an end reported by a runtime hook) the end waits that
+* long, and a start of the same session meanwhile cancels it. Never throws.
 */
 async function endSession(options) {
 	const env = options.env ?? process.env;
@@ -5561,6 +5785,7 @@ async function endSession(options) {
 	};
 	const sessionId = session.toLowerCase();
 	const graceMs = Math.max(0, options.graceMs ?? 0);
+	const revoke = options.revoke === true;
 	const reason = options.reason && /^[a-z_]{1,40}$/.test(options.reason) ? options.reason : null;
 	try {
 		let managed = false;
@@ -5574,21 +5799,29 @@ async function endSession(options) {
 				return current;
 			}
 			const now = deps.now();
-			if (graceMs > 0 && (!current.endedAt || deferredEnd(current))) {
+			const revoking = revoke || Boolean(current.endedAt) && (current.disconnect === "pending" || current.disconnect === "pending_enrollment" || current.disconnect === "deferred" && current.revokeOnEnd);
+			if (!revoking && current.endedAt && current.disconnect === "kept") return current;
+			if (graceMs > 0 && (!current.endedAt || deferredEnd(current) || current.disconnect === "kept")) {
 				deferred = true;
 				return {
 					...current,
 					endedAt: now.toISOString(),
 					disconnect: "deferred",
 					deferredUntil: new Date(now.getTime() + graceMs).toISOString(),
+					revokeOnEnd: revoking,
 					endReason: reason
 				};
 			}
+			if (!revoking) return {
+				...keptEnd(options.configDir, current, deps, env, now),
+				endReason: current.endReason ?? reason
+			};
 			return {
 				...current,
 				endedAt: current.endedAt ?? now.toISOString(),
 				disconnect: current.disconnect === "pending_enrollment" ? "pending_enrollment" : "pending",
 				deferredUntil: null,
+				revokeOnEnd: true,
 				endReason: current.endReason ?? reason
 			};
 		});
@@ -5616,19 +5849,25 @@ async function endSession(options) {
 					resumed = true;
 					return current;
 				}
-				return {
+				return current.revokeOnEnd ? {
 					...current,
 					disconnect: "pending",
 					deferredUntil: null
-				};
+				} : keptEnd(options.configDir, current, deps, env, deps.now());
 			});
 			if (resumed || !record) return {
 				...known,
 				status: "resumed",
-				detail: "The session started again (or was ended again) before its end took effect, so this end left its agent connected."
+				detail: "The session started again (or was ended again) before its end took effect, so this end changed nothing."
 			};
 		}
-		const outcome = await finishSessionDisconnect(options.configDir, record, deps, env, options.fetch);
+		if (record.disconnect === "kept") return {
+			...known,
+			status: "kept",
+			detail: KEPT_DETAIL
+		};
+		const report = {};
+		const outcome = await finishSessionDisconnect(options.configDir, record, deps, env, options.fetch, false, report);
 		if (outcome === "released") return {
 			...known,
 			status: "left_connected",
@@ -5637,6 +5876,7 @@ async function endSession(options) {
 		return outcome === "done" ? {
 			...known,
 			status: "disconnected",
+			...report.resumeNote ? { resumeNote: report.resumeNote } : {},
 			detail: "This session's agent was disconnected."
 		} : {
 			...known,
@@ -5648,17 +5888,99 @@ async function endSession(options) {
 			...base,
 			session: sessionId,
 			status: "failed",
-			detail: error instanceof AgentDisconnectError ? error.message : "Disconnect did not finish. The agent was left as it was."
+			detail: error instanceof AgentDisconnectError ? error.message : "The end did not finish. The agent was left as it was."
 		};
 	}
 }
 /**
-* Ended sessions whose agent disconnect still needs confirming, including a
-* hook's end whose grace period is over but whose own process never finished
-* it (for example because the machine shut down).
+* Ended sessions whose agent disconnect was asked for and still needs
+* confirming, including a `--revoke` end from a hook whose grace period is
+* over but whose own process never finished it (for example because the
+* machine shut down). Ends that keep their agent are never listed here.
 */
 function pendingSessionDisconnects(configDir, now = /* @__PURE__ */ new Date()) {
-	return listSessionRecords(configDir).filter((record) => record.createdBy === "session-register" && record.endedAt && (record.disconnect === "pending" || record.disconnect === "pending_enrollment" || record.disconnect === "deferred" && !(Date.parse(record.deferredUntil ?? "") > now.getTime())));
+	return listSessionRecords(configDir).filter((record) => record.createdBy === "session-register" && record.endedAt && (record.disconnect === "pending" || record.disconnect === "pending_enrollment" || record.disconnect === "deferred" && record.revokeOnEnd && !(Date.parse(record.deferredUntil ?? "") > now.getTime())));
+}
+/**
+* Ended sessions that kept their agent and have not started again for
+* STALE_SESSION_MS, whose profile still holds exactly the credential
+* `session-register` created. Only these are disconnected for being stale.
+*/
+function staleSessionAgents(configDir, now = /* @__PURE__ */ new Date()) {
+	return listSessionRecords(configDir).filter((record) => {
+		if (record.createdBy !== "session-register" || !record.endedAt || !(record.disconnect === "kept" || record.disconnect === "deferred" && !record.revokeOnEnd) || !(now.getTime() - Date.parse(record.endedAt) >= 2592e6)) return false;
+		try {
+			const current = loadConnectedAgentProfile(configDir, record.profile);
+			return Boolean(current && holdsRegisteredCredential(configDir, record, current));
+		} catch {
+			return false;
+		}
+	});
+}
+/**
+* Disconnect the agent of every stale ended session (see
+* staleSessionAgents). Each disconnect names the exact credential it
+* checked, under the locks `agent connect` also takes, so a credential
+* connected into the profile meanwhile is never revoked, and nothing is
+* ever revoked by address here. A start of the session meanwhile turns it
+* into an ordinary pending disconnect, which that start finishes. Returns
+* how many agents were disconnected.
+*/
+async function revokeStaleSessionAgents(configDir, options = {}) {
+	const deps = withDefined(DISCONNECT_DEFAULTS, options.dependencies);
+	const env = options.env ?? process.env;
+	let revoked = 0;
+	for (const listed of staleSessionAgents(configDir, deps.now())) {
+		if (listed.session === options.exclude?.toLowerCase()) continue;
+		try {
+			const current = loadConnectedAgentProfile(configDir, listed.profile);
+			if (!current || !holdsRegisteredCredential(configDir, listed, current)) continue;
+			let claimed = false;
+			await updateSessionRecord(configDir, listed.session, (row) => {
+				if (row?.createdBy !== "session-register" || row.endedAt !== listed.endedAt || row.disconnect !== listed.disconnect) return row;
+				claimed = true;
+				return {
+					...row,
+					disconnect: "pending",
+					deferredUntil: null,
+					revokeOnEnd: true
+				};
+			});
+			if (!claimed) continue;
+			let outcome;
+			try {
+				await deps.disconnect({
+					configDir,
+					profileName: listed.profile,
+					fetch: options.fetch,
+					env,
+					expected: {
+						address: current.agent_address,
+						invitationHash: current.invitation_hash
+					}
+				});
+				outcome = "done";
+			} catch (error) {
+				outcome = error instanceof AgentCredentialChangedError ? "released" : "failed";
+			}
+			await updateSessionRecord(configDir, listed.session, (row) => {
+				if (row?.createdBy !== "session-register" || row.disconnect !== "pending") return row;
+				if (outcome === "done") return {
+					...row,
+					disconnect: "done"
+				};
+				if (outcome === "released") return releasedRecord(row, "credential_changed", deps.now());
+				return {
+					...row,
+					disconnect: listed.disconnect,
+					deferredUntil: listed.deferredUntil,
+					revokeOnEnd: false
+				};
+			});
+			if (outcome === "done") revoked++;
+		} catch {}
+	}
+	return revoked;
 }
 /**
 * Retry every pending disconnect. Each goes through the same credential check
@@ -5748,4 +6070,4 @@ async function runDetached(params) {
 	}
 }
 //#endregion
-export { boundSessionProfiles as $, AgentDisconnectError as A, runContactRequest as B, verificationReplySubmitted as C, createNotificationContactPolicy as D, NetworkAdmissionPendingError as E, addressNoteTarget as F, receiverStatusCommand as G, agentInvitationHash as H, runAddressNotesRequest as I, savedReceiver as J, refusalAfterReplacement as K, ContactsApiError as L, clearRevokedAddresses as M, disconnectAgent as N, evaluateContactPolicy as O, AddressNotesApiError as P, recordHookMailCheck as Q, contactAddress as R, externalReceivingState as S, NETWORK_ADMISSION_PENDING_RETRY_MS as T, connectAgent as U, agentConnectionStatus as V, readAgentInvitation as W, releaseRegistrationsForProfile as X, MACHINE_RUNTIMES as Y, installClaudeWakeHook as Z, defaultAgentProfileName as _, upsertManagedBlock as _t, endSession as a, ephemeralCliReason as at, runAgentConnect as b, refreshOwnerMemberAddressPeriodically as bt, pendingSessionDisconnects as c, inspectClaudeHooks as ct, registerSession as d, samePath as dt, claudeConfigDir as et, retryPendingDisconnects as f, writeClaudeSettings as ft, connectWarnings as g, readManagedFile as gt, enrollmentResumes as h, jsonIndentation as ht, connectedProfilesForSession as i, ensureHookLauncher as it, claimOverRevokedSetup as j, canonicalContactSelector as k, psProcessInfo as l, readClaudeSettings as lt, enrollAgent as m, inspectManagedBlock as mt, OMP_MAIN as n, describeSessionHookChange as nt, headlessClaudeRun as o, findOnPath as ot, runDetached as p, MachineFileError as pt, saveConnectionName as q, agentConnectionState as r, describeSessionHookItem as rt, machine_session_exports as s, hasMachineSessionHooks as st, HOOK_END_GRACE_MS as t, currentCliLocation as tt, readClaudeHookInput as u, repairClaudeHooks as ut, invitationProfileName as v, writeManagedFile as vt, ContactPolicyReadRetryError as w, RECEIVER_MODES as x, withOwnerMemberAddress as xt, pollCheckCommand as y, readHookLauncherWarning as yt, contactAgentAddress as z };
+export { installClaudeWakeHook as $, evaluateContactPolicy as A, contactAddress as B, RECEIVER_MODES as C, withOwnerMemberAddress as Ct, NETWORK_ADMISSION_PENDING_RETRY_MS as D, ContactPolicyReadRetryError as E, disconnectAgent as F, connectAgent as G, runContactRequest as H, AddressNotesApiError as I, refusalAfterReplacement as J, readAgentInvitation as K, addressNoteTarget as L, AgentDisconnectError as M, claimOverRevokedSetup as N, NetworkAdmissionPendingError as O, clearRevokedAddresses as P, releaseRegistrationsForProfile as Q, runAddressNotesRequest as R, runAgentConnect as S, refreshOwnerMemberAddressPeriodically as St, verificationReplySubmitted as T, agentConnectionStatus as U, contactAgentAddress as V, agentInvitationHash as W, savedReceiver as X, saveConnectionName as Y, MACHINE_RUNTIMES as Z, enrollmentResumes as _, jsonIndentation as _t, endSession as a, describeSessionHookItem as at, invitationProfileName as b, writeManagedFile as bt, pendingSessionDisconnects as c, findOnPath as ct, registerSession as d, readClaudeSettings as dt, recordHookMailCheck as et, retryPendingDisconnects as f, repairClaudeHooks as ft, enrollAgent as g, inspectManagedBlock as gt, staleSessionAgents as h, MachineFileError as ht, connectedProfilesForSession as i, describeSessionHookChange as it, canonicalContactSelector as j, createNotificationContactPolicy as k, psProcessInfo as l, hasMachineSessionHooks as lt, runDetached as m, writeClaudeSettings as mt, OMP_MAIN as n, claudeConfigDir as nt, headlessClaudeRun as o, ensureHookLauncher as ot, revokeStaleSessionAgents as p, samePath as pt, receiverStatusCommand as q, agentConnectionState as r, currentCliLocation as rt, machine_session_exports as s, ephemeralCliReason as st, HOOK_END_GRACE_MS as t, boundSessionProfiles as tt, readClaudeHookInput as u, inspectClaudeHooks as ut, connectWarnings as v, readManagedFile as vt, externalReceivingState as w, pollCheckCommand as x, readHookLauncherWarning as xt, defaultAgentProfileName as y, upsertManagedBlock as yt, ContactsApiError as z };