primitive 1.72.2 → 1.73.0

package/dist/{machine-session-Be6j29GE.js → machine-session-B6V5-grn.js}

@@ -1,11 +1,11 @@
-import { S as __exportAll } from "./repeats-BL7ZC-_6-CKMKBlx7.js";
-import { B as parseConnectedAgentProfile, F as agentProfileName, G as PrimitiveApiClient, H as profileAlreadyConnectedMessage, I as agentProfilesDirectory, L as connectedAgentIdentity, M as AGENT_PROFILE_ENV, N as AgentConnectionSetupError, P as agentProfileDirectory, R as connectedApiBaseUrl, V as parseOwnerMemberAddress, W as saveConnectedAgentProfile, x as loadCliCredentials, z as loadConnectedAgentProfile } from "./cli-config--YTRdJ3t.js";
-import { $t as refreshStoredCliCredentials, Bn as listAgentContacts, Dt as defaultConnectionName, Gn as listDomains, Hn as listContacts, Tn as getContact, Tt as cliInvocation, cr as putContact, er as listSentEmails, fn as deleteAgentContact, hr as searchEmails, kn as getEmail, or as putAgentContact, pn as deleteContact, sr as putAgentContactPolicy, vr as sendEmail, wn as getAgentContactPolicy } from "./api-command-BrwPbyPP.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-Byt5sPWW.js";
-import { a as scopedChatSenderTrust } from "./scoped-chat-DTFkP360.js";
-import { l as stopBackgroundListen, r as backgroundListenStatus } from "./listen-background--0peztKE.js";
-import { t as readSharedMailOwner } from "./shared-mail-watch-DtKpsgg8.js";
+import { $t as listDomains, At as getAgentContactPolicy, Dn as sendEmail, Ft as getEmail, Jt as listAgentContacts, Kn as __exportAll, Kt as inviteAgentConnection, Xt as listContacts, cn as listSentEmails, gn as putContact, hn as putAgentContactPolicy, jt as getContact, mn as putAgentContact, qt as listAgentConnections, vt as deleteAgentContact, wn as searchEmails, yt as deleteContact } from "./repeats-BL7ZC-_6-B_ESsWTH.js";
+import { B as parseConnectedAgentProfile, F as agentProfileName, G as PrimitiveApiClient, H as profileAlreadyConnectedMessage, I as agentProfilesDirectory, L as connectedAgentIdentity, M as AGENT_PROFILE_ENV, N as AgentConnectionSetupError, P as agentProfileDirectory, R as connectedApiBaseUrl, V as parseOwnerMemberAddress, W as saveConnectedAgentProfile, x as loadCliCredentials, z as loadConnectedAgentProfile } from "./cli-config-C0Y_Ppol.js";
+import { _ as acquireListenLock, b as listenLockHeld, c as mailTime, d as readMailJson, f as removeMailFile, g as ListenStateError, h as writeMailJson, i as mailId, l as privateMailDirectory, o as mailObject, p as syncMailDirectory, r as mailAddress, s as mailString } from "./shared-mail-files-CZfm7E2k.js";
+import { gt as defaultConnectionName, jt as refreshStoredCliCredentials, mt as cliInvocation } from "./api-command-fKP3NYa7.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-DJAb9SGm.js";
+import { o as scopedChatSenderTrust } from "./scoped-chat-DAiOb622.js";
+import { l as stopBackgroundListen, r as backgroundListenStatus } from "./listen-background-cD6n8VYO.js";
+import { t as readSharedMailOwner } from "./shared-mail-watch-DyQB0MK0.js";
 import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
@@ -146,6 +146,146 @@ async function withOwnerMemberAddress(result, params) {
 	};
 }
 //#endregion
+//#region src/oclif/claude-session-receivers.ts
+const FILE = /^([0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12})\.json$/;
+const LOCK_WAIT$2 = new Int32Array(new SharedArrayBuffer(4));
+function sessionReceiversDirectory(configDir) {
+	return join(agentProfilesDirectory(resolve(configDir)), "claude-sessions");
+}
+function sessionId(value) {
+	const id = value.toLowerCase();
+	if (!SESSION_UUID.test(id)) throw new Error("A session must be a UUID.");
+	return id;
+}
+function sessionReceiversPath(configDir, session) {
+	return join(sessionReceiversDirectory(configDir), `${sessionId(session)}.json`);
+}
+function receiver(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const row = value;
+	try {
+		return {
+			profile: agentProfileName(String(row.profile ?? "")),
+			address: mailAddress(String(row.address ?? ""))
+		};
+	} catch {
+		return null;
+	}
+}
+/** The profiles one session receives as; empty when it has none. */
+function readSessionReceivers(configDir, session) {
+	let value;
+	try {
+		value = readMailJson(sessionReceiversPath(configDir, session));
+	} catch {
+		return [];
+	}
+	const row = value && typeof value === "object" && !Array.isArray(value) ? value : null;
+	if (row?.version !== 1 || row.session_id !== sessionId(session) || !Array.isArray(row.receivers)) return [];
+	return row.receivers.flatMap((item) => {
+		const parsed = receiver(item);
+		return parsed ? [parsed] : [];
+	});
+}
+/** Every session with an entry, and the profiles it receives as. */
+function listSessionReceivers(configDir) {
+	const sessions = /* @__PURE__ */ new Map();
+	let names;
+	try {
+		names = readdirSync(sessionReceiversDirectory(configDir));
+	} catch {
+		return sessions;
+	}
+	for (const name of names.sort()) {
+		const session = FILE.exec(name)?.[1];
+		if (!session) continue;
+		const receivers = readSessionReceivers(configDir, session);
+		if (receivers.length) sessions.set(session, receivers);
+	}
+	return sessions;
+}
+function withLock(configDir, action) {
+	const directory = sessionReceiversDirectory(configDir);
+	let release;
+	for (let attempt = 0; attempt < 80 && !release; attempt++) try {
+		release = acquireListenLock(directory, "claude-session-receivers");
+	} catch {
+		Atomics.wait(LOCK_WAIT$2, 0, 0, 25);
+	}
+	if (!release) throw new Error("Another Primitive command is editing session receivers.");
+	try {
+		return action();
+	} finally {
+		release();
+	}
+}
+function write(configDir, session, receivers) {
+	const path = sessionReceiversPath(configDir, session);
+	if (receivers.length === 0) {
+		try {
+			unlinkSync(path);
+			syncMailDirectory(sessionReceiversDirectory(configDir));
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		return;
+	}
+	writeMailJson(path, {
+		version: 1,
+		session_id: sessionId(session),
+		receivers
+	});
+}
+/**
+* Add or update one profile for a session (its address follows the
+* profile). Returns whether the entry changed.
+*/
+function addSessionReceiver(configDir, session, value) {
+	const next = receiver(value);
+	if (!next) throw new Error("A session receiver needs a profile and address.");
+	return withLock(configDir, () => {
+		const current = readSessionReceivers(configDir, session);
+		if (current.find((row) => row.profile === next.profile)?.address === next.address) return false;
+		write(configDir, session, [...current.filter((row) => row.profile !== next.profile), next]);
+		return true;
+	});
+}
+/** Remove one profile from a session. Returns whether it was there. */
+function removeSessionReceiver(configDir, session, profile) {
+	return withLock(configDir, () => {
+		const current = readSessionReceivers(configDir, session);
+		const next = current.filter((row) => row.profile !== profile);
+		if (next.length === current.length) return false;
+		write(configDir, session, next);
+		return true;
+	});
+}
+/**
+* Drop entries for profiles that are no longer saved as connected, or whose
+* saved address changed to another. Returns how many were dropped.
+*/
+function pruneSessionReceivers(configDir) {
+	const live = (row) => {
+		try {
+			const profile = loadConnectedAgentProfile(resolve(configDir), row.profile);
+			return profile !== null && profile.agent_address === row.address;
+		} catch {
+			return true;
+		}
+	};
+	let dropped = 0;
+	for (const [session, receivers] of listSessionReceivers(configDir)) {
+		if (receivers.every(live)) continue;
+		withLock(configDir, () => {
+			const current = readSessionReceivers(configDir, session);
+			const next = current.filter(live);
+			dropped += current.length - next.length;
+			if (next.length !== current.length) write(configDir, session, next);
+		});
+	}
+	return dropped;
+}
+//#endregion
 //#region src/oclif/hook-launcher.ts
 /**
 * Claude Code hooks run Primitive through a small POSIX launcher instead of a
@@ -730,7 +870,8 @@ const STATE_PHRASES = {
 	stale: "session disconnected or removed",
 	duplicate: "duplicate",
 	outdated: "old CLI path",
-	old_address: "old agent address"
+	old_address: "old agent address",
+	per_session: "per-session hook, now served by the shared receive hooks"
 };
 /** "profile my-agent, session 1234...": who a session hook serves. */
 function describeSessionHookOwner(item) {
@@ -799,7 +940,15 @@ function globalHookCurrent(hook, cli) {
 	return nodeCommandCurrent(hook.command, cli.node) && samePath(args[0], cli.entry);
 }
 const WAKE_MARKER = "primitive-agent-wake-v1";
-const PENDING_MARKER$1 = "primitive-pending-mail-v1";
+const PENDING_MARKER = "primitive-pending-mail-v1";
+/**
+* The shared receive hooks: one set per config directory serves every Claude
+* session. Each run reads its session id from the hook input and looks up
+* the profiles it receives as (claude-session-receivers.ts), exiting at once
+* for a session with none.
+*/
+const SHARED_WAKE_MARKER = "primitive-agent-wake-v2";
+const SHARED_PENDING_MARKER = "primitive-pending-mail-v2";
 const SESSION_EVENTS = [
 	"Stop",
 	"SessionStart",
@@ -818,6 +967,7 @@ const SESSION_HOOK_KIND = {
 * both use it, so they never disagree about a hook being present.
 */
 function hasSessionReceiveHook(hooks, event, target, node) {
+	if (hasSharedHook(hooks, event, target.configDir, node) && readSessionReceivers(target.configDir, target.session).some((row) => row.profile === target.profile && row.address === target.address)) return true;
 	const entries = hooks[event];
 	if (!Array.isArray(entries)) return false;
 	const pending = SESSION_HOOK_KIND[event] === "pending";
@@ -826,9 +976,64 @@ function hasSessionReceiveHook(hooks, event, target, node) {
 	return entries.some((entry) => record$2(entry) && Array.isArray(entry.hooks) && entry.hooks.some((hook) => {
 		if (!record$2(hook) || hook.type !== "command") return false;
 		const args = hook.args;
-		return Array.isArray(args) && args.length === 7 && args.every((value) => typeof value === "string") && basename(args[0]) === (pending ? "claude-pending-mail.mjs" : "claude-wake.mjs") && resolve(args[2]) === configDir && args[3] === target.profile && args[4] === target.address && args[5].toLowerCase() === session && args[6] === (pending ? PENDING_MARKER$1 : WAKE_MARKER) && (node === null || samePath(hook.command, node));
+		return Array.isArray(args) && args.length === 7 && args.every((value) => typeof value === "string") && basename(args[0]) === (pending ? "claude-pending-mail.mjs" : "claude-wake.mjs") && resolve(args[2]) === configDir && args[3] === target.profile && args[4] === target.address && args[5].toLowerCase() === session && args[6] === (pending ? PENDING_MARKER : WAKE_MARKER) && (node === null || samePath(hook.command, node));
+	}));
+}
+/** Whether an event carries the shared receive hook for a config directory. */
+function hasSharedHook(hooks, event, configDir, node) {
+	const entries = hooks[event];
+	if (!Array.isArray(entries)) return false;
+	const pending = SESSION_HOOK_KIND[event] === "pending";
+	return entries.some((entry) => record$2(entry) && (event !== "SessionStart" || entry.matcher === "resume") && Array.isArray(entry.hooks) && entry.hooks.some((hook) => {
+		const parsed = parseSessionHook(hook);
+		return parsed?.shared === true && parsed.kind === (pending ? "pending" : "wake") && resolve(parsed.configDir) === resolve(configDir) && (node === null || record$2(hook) && samePath(hook.command, node));
 	}));
 }
+/** The shared hook entry for one event, as installers write it. */
+function sharedHookEntry(event, cli, configDir, node = cli.node) {
+	const pending = SESSION_HOOK_KIND[event] === "pending";
+	const hook = {
+		type: "command",
+		command: node,
+		args: [
+			pending ? cli.pending : cli.wake,
+			cli.entry,
+			resolve(configDir),
+			pending ? SHARED_PENDING_MARKER : SHARED_WAKE_MARKER
+		],
+		...pending ? { timeout: 10 } : {
+			asyncRewake: true,
+			timeout: 604800
+		}
+	};
+	return event === "SessionStart" ? {
+		matcher: "resume",
+		hooks: [hook]
+	} : { hooks: [hook] };
+}
+/**
+* The receiver an exact-session hook from an earlier version stands for:
+* its profile, with the address the profile is connected as now, and its
+* session. Null when the profile is no longer connected.
+*/
+function foldedReceiver(parsed) {
+	if (!parsed.profile || !parsed.session || !SESSION_UUID.test(parsed.session)) return null;
+	try {
+		const profile = loadConnectedAgentProfile(resolve(parsed.configDir), parsed.profile);
+		return profile ? {
+			configDir: resolve(parsed.configDir),
+			profile: parsed.profile,
+			address: profile.agent_address,
+			session: parsed.session.toLowerCase()
+		} : null;
+	} catch {
+		return null;
+	}
+}
+/** A per-session receive hook (any version), shared or not. Exported for installers. */
+function parseReceiveHook(hook) {
+	return parseSessionHook(hook);
+}
 /** A per-session receive hook written by `agent connect` or `agent enroll`, any version. */
 function parseSessionHook(hook) {
 	if (!record$2(hook) || hook.type !== "command" || !Array.isArray(hook.args)) return null;
@@ -836,7 +1041,15 @@ function parseSessionHook(hook) {
 	if (!args.every((value) => typeof value === "string")) return null;
 	const strings = args;
 	const script = basename(strings[0] ?? "");
-	if (script === "claude-pending-mail.mjs") return strings.length === 7 && strings[6] === PENDING_MARKER$1 ? {
+	if (strings.length === 4 && (script === "claude-wake.mjs" && strings[3] === "primitive-agent-wake-v2" || script === "claude-pending-mail.mjs" && strings[3] === "primitive-pending-mail-v2")) return {
+		kind: script === "claude-wake.mjs" ? "wake" : "pending",
+		configDir: strings[2] ?? "",
+		profile: null,
+		address: null,
+		session: null,
+		shared: true
+	};
+	if (script === "claude-pending-mail.mjs") return strings.length === 7 && strings[6] === PENDING_MARKER ? {
 		kind: "pending",
 		configDir: strings[2] ?? "",
 		profile: strings[3] ?? null,
@@ -892,10 +1105,14 @@ function judgeSessionHooks(hooks, cli, bound = []) {
 				const parsed = parseSessionHook(hook);
 				if (!parsed || !record$2(hook)) continue;
 				const pathsExist = existsSync(String(hook.command)) && existsSync(String(hook.args[0])) && existsSync(String(hook.args[1]));
-				if (!(parsed.profile ? existsSync(parsed.configDir) && profileStillConnected(parsed.configDir, parsed.profile) : existsSync(parsed.configDir) && pathsExist)) {
+				if (!(parsed.shared ? existsSync(parsed.configDir) : parsed.profile ? existsSync(parsed.configDir) && profileStillConnected(parsed.configDir, parsed.profile) : existsSync(parsed.configDir) && pathsExist)) {
 					verdicts.set(hook, "stale");
 					continue;
 				}
+				if (parsed.profile && parsed.session) {
+					verdicts.set(hook, "per_session");
+					continue;
+				}
 				const current = bound.find((item) => item.configDir === resolve(parsed.configDir) && item.profile === parsed.profile && item.session === parsed.session?.toLowerCase());
 				if (current && parsed.address !== current.address) {
 					verdicts.set(hook, "old_address");
@@ -905,7 +1122,7 @@ function judgeSessionHooks(hooks, cli, bound = []) {
 					event,
 					parsed.kind,
 					resolve(parsed.configDir),
-					parsed.profile ?? "",
+					parsed.shared ? "shared" : parsed.profile ?? "",
 					parsed.session?.toLowerCase() ?? ""
 				].join("\0");
 				if (seen.has(key)) {
@@ -974,8 +1191,28 @@ function boundKey(item) {
 * disconnected or removed profile is stale (machine doctor removes it), so
 * the session does not receive through it.
 */
-function receivingProfilesBySession(hooks, always) {
+function receivingProfilesBySession(hooks, always, configDirs = []) {
 	const receiving = /* @__PURE__ */ new Map();
+	const shared = new Set(configDirs.map((dir) => resolve(dir)));
+	for (const event of SESSION_EVENTS) {
+		const entries = hooks[event];
+		if (!Array.isArray(entries)) continue;
+		for (const entry of entries) if (record$2(entry) && Array.isArray(entry.hooks)) for (const hook of entry.hooks) {
+			const parsed = parseSessionHook(hook);
+			if (parsed?.shared) shared.add(resolve(parsed.configDir));
+		}
+	}
+	for (const configDir of shared) for (const [session, receivers] of listSessionReceivers(configDir)) for (const row of receivers) {
+		const key = [
+			configDir,
+			row.profile,
+			session
+		].join("\0");
+		if (key !== always && !profileStillConnected(configDir, row.profile)) continue;
+		const profiles = receiving.get(session) ?? /* @__PURE__ */ new Set();
+		profiles.add(key);
+		receiving.set(session, profiles);
+	}
 	for (const event of SESSION_EVENTS) {
 		const entries = hooks[event];
 		if (!Array.isArray(entries)) continue;
@@ -1014,7 +1251,7 @@ function otherSessionReceivers(hooks, target) {
 		target.profile,
 		session
 	].join("\0");
-	const present = receivingProfilesBySession(hooks, own).get(session) ?? /* @__PURE__ */ new Set();
+	const present = receivingProfilesBySession(hooks, own, [target.configDir]).get(session) ?? /* @__PURE__ */ new Set();
 	if (present.has(own)) return [];
 	return [...present].map((other) => other.split("\0")[1] ?? "").sort();
 }
@@ -1073,31 +1310,6 @@ function sessionHookItems(hooks, verdicts, missing) {
 	}
 	return items;
 }
-/** The exact entry `agent connect` and `session-register` install. */
-function sessionHookEntry(event, item, cli) {
-	const pending = SESSION_HOOK_KIND[event] === "pending";
-	const hook = {
-		type: "command",
-		command: cli.node,
-		args: [
-			pending ? cli.pending : cli.wake,
-			cli.entry,
-			item.configDir,
-			item.profile,
-			item.address,
-			item.session,
-			pending ? PENDING_MARKER$1 : WAKE_MARKER
-		],
-		...pending ? { timeout: 10 } : {
-			asyncRewake: true,
-			timeout: 604800
-		}
-	};
-	return event === "SessionStart" ? {
-		matcher: "resume",
-		hooks: [hook]
-	} : { hooks: [hook] };
-}
 /** Inspect every Primitive-owned Claude hook without changing anything. */
 function inspectClaudeHooks(settings, context) {
 	const hooks = record$2(settings.hooks) ? settings.hooks : {};
@@ -1154,7 +1366,8 @@ function inspectClaudeHooks(settings, context) {
 		stale: 0,
 		duplicate: 0,
 		outdated: 0,
-		old_address: 0
+		old_address: 0,
+		per_session: 0
 	};
 	const verdicts = judgeSessionHooks(hooks, context.cli, bound);
 	for (const verdict of verdicts.values()) counts[verdict]++;
@@ -1166,16 +1379,17 @@ function inspectClaudeHooks(settings, context) {
 		counts.old_address ? `${counts.old_address} naming an old agent address` : "",
 		counts.stale ? `${counts.stale} for disconnected or removed sessions` : "",
 		counts.duplicate ? `${counts.duplicate} duplicates` : "",
-		counts.outdated ? `${counts.outdated} pointing at an old CLI path` : ""
+		counts.outdated ? `${counts.outdated} pointing at an old CLI path` : "",
+		counts.per_session ? `${counts.per_session} per-session hooks to fold into the shared receive hooks` : ""
 	].filter(Boolean);
 	findings["claude.hook.stop"] = problems.length ? {
 		status: "fail",
-		detail: `Per-session receive hooks need cleanup: ${problems.join(", ")}. Affected: ${summarizeOwners(items)}.${blockedNote}${heldNote}`,
-		fixable: canFix || counts.outdated === 0 && missing === 0 && context.blocked === null,
+		detail: `Receive hooks need cleanup: ${problems.join(", ")}. Affected: ${summarizeOwners(items)}.${blockedNote}${heldNote}`,
+		fixable: canFix || counts.outdated === 0 && counts.per_session === 0 && missing === 0 && context.blocked === null,
 		items
 	} : {
 		status: "ok",
-		detail: `${counts.keep ? `${counts.keep} per-session receive hooks, each present once and current.` : "No per-session receive hooks; each registered session adds its own exact-session hooks."}${heldNote}`,
+		detail: `${counts.keep ? `${counts.keep} receive hooks, each present once and current; the shared hooks serve every registered session.` : "No receive hooks; registering a session adds the shared receive hooks."}${heldNote}`,
 		fixable: false
 	};
 	return findings;
@@ -1210,6 +1424,7 @@ function rewriteEntries(entries, transform) {
 function repairClaudeHooks(settings, context, checks, options = {}) {
 	const changed = /* @__PURE__ */ new Set();
 	const changes = [];
+	const receivers = [];
 	const selected = (profile) => !options.profiles || profile !== null && options.profiles.has(profile);
 	const hooks = record$2(settings.hooks) ? { ...settings.hooks } : {};
 	const cli = context.blocked === null ? context.cli : null;
@@ -1246,6 +1461,13 @@ function repairClaudeHooks(settings, context, checks, options = {}) {
 			const held = heldSessionProfiles(hooks, context.bound ?? [], context.restoreProfiles);
 			const bound = (context.bound ?? []).filter((item) => !held.has(boundKey(item)));
 			const verdicts = judgeSessionHooks(hooks, context.cli, bound);
+			const missingBefore = missingSessionHooks(hooks, bound);
+			const planned = /* @__PURE__ */ new Set();
+			const plan = (item) => {
+				if (planned.has(boundKey(item))) return;
+				planned.add(boundKey(item));
+				receivers.push(item);
+			};
 			for (const event of SESSION_EVENTS) {
 				const entries = eventEntries(hooks, event);
 				if (entries === "invalid" || entries.length === 0) continue;
@@ -1253,13 +1475,23 @@ function repairClaudeHooks(settings, context, checks, options = {}) {
 					const verdict = verdicts.get(hook);
 					const parsed = parseSessionHook(hook);
 					if (!verdict || verdict === "keep" || !parsed) return hook;
-					if (!selected(parsed.profile)) return hook;
+					if (!parsed.shared && !selected(parsed.profile)) return hook;
 					const item = {
 						profile: parsed.profile,
 						session: parsed.session?.toLowerCase() ?? null,
 						hook: event,
 						state: verdict
 					};
+					if (verdict === "per_session") {
+						if (!cli) return hook;
+						const current = foldedReceiver(parsed);
+						if (current) plan(current);
+						changes.push({
+							...item,
+							action: "removed"
+						});
+						return;
+					}
 					if (verdict === "stale" || verdict === "duplicate" || verdict === "old_address") {
 						changes.push({
 							...item,
@@ -1286,26 +1518,33 @@ function repairClaudeHooks(settings, context, checks, options = {}) {
 					changed.add("claude.hook.stop");
 				}
 			}
-			if (cli) for (const missing of missingSessionHooks(hooks, bound)) {
-				if (!selected(missing.bound.profile)) continue;
-				const entries = eventEntries(hooks, missing.event);
-				if (entries === "invalid") continue;
-				changes.push({
-					profile: missing.bound.profile,
-					session: missing.bound.session,
-					hook: missing.event,
-					state: "missing",
-					action: "added"
-				});
-				hooks[missing.event] = [...entries, sessionHookEntry(missing.event, missing.bound, cli)];
-				changed.add("claude.hook.stop");
+			if (cli) {
+				for (const missing of missingBefore) {
+					if (!selected(missing.bound.profile)) continue;
+					changes.push({
+						profile: missing.bound.profile,
+						session: missing.bound.session,
+						hook: missing.event,
+						state: "missing",
+						action: "added"
+					});
+					plan(missing.bound);
+				}
+				for (const configDir of new Set(receivers.map((item) => resolve(item.configDir)))) for (const event of SESSION_EVENTS) {
+					const entries = eventEntries(hooks, event);
+					if (entries === "invalid" || hasSharedHook(hooks, event, configDir, null)) continue;
+					hooks[event] = [...entries, sharedHookEntry(event, cli, configDir)];
+					changed.add("claude.hook.stop");
+				}
+				if (receivers.length) changed.add("claude.hook.stop");
 			}
 		}
 	}
 	if (!changed.size) return {
 		settings,
 		changed,
-		changes
+		changes,
+		receivers
 	};
 	return {
 		settings: {
@@ -1313,15 +1552,17 @@ function repairClaudeHooks(settings, context, checks, options = {}) {
 			hooks
 		},
 		changed,
-		changes
+		changes,
+		receivers
 	};
 }
 //#endregion
 //#region src/oclif/claude-wake-install.ts
-const HOOK_MARKER = "primitive-agent-wake-v1";
-const WAKE_EVENTS = ["Stop", "SessionStart"];
-const PENDING_MARKER = "primitive-pending-mail-v1";
-const PENDING_EVENT = "PostToolUse";
+const RECEIVE_EVENTS = [
+	"Stop",
+	"SessionStart",
+	"PostToolUse"
+];
 const LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
 function record$1(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -1445,7 +1686,14 @@ function editClaudeSettings(claudeDir, edit) {
 		release();
 	}
 }
-/** Add exact-session fail-open receiving hooks while preserving unrelated settings. */
+/**
+* Record this profile as a receiver for the session and make sure the one
+* shared set of receive hooks is installed, preserving unrelated settings.
+* Per-session hooks written by earlier versions for this config directory
+* are folded in: a still-bound profile becomes a recorded receiver and its
+* hooks are removed; hooks for disconnected profiles or removed config
+* directories are pruned. Hooks of other tools are never touched.
+*/
 function installClaudeWakeHook(options) {
 	try {
 		const configDir = resolve(options.configDir);
@@ -1455,9 +1703,6 @@ function installClaudeWakeHook(options) {
 			platform: options.platform
 		});
 		if (!cli) return "unavailable";
-		const cliPath = cli.entry;
-		const wrapperPath = cli.wake;
-		const pendingPath = cli.pending;
 		const profileName = agentProfileName(options.profileName);
 		const agentAddress = mailAddress(options.agentAddress);
 		if (!SESSION_UUID.test(options.sessionId)) return "unavailable";
@@ -1469,52 +1714,19 @@ function installClaudeWakeHook(options) {
 		} catch {
 			node = cli.runtimeNode;
 		}
+		pruneSessionReceivers(configDir);
 		let held = false;
 		if (!editClaudeSettings(claudeDir, (settings) => {
 			const hooks = settings.hooks ?? {};
 			if (!record$1(hooks)) throw new Error("Invalid hook settings");
-			for (const event of WAKE_EVENTS) if (!Array.isArray(hooks[event] ?? [])) throw new Error(`Invalid ${event} hooks`);
-			if (!Array.isArray(hooks[PENDING_EVENT] ?? [])) throw new Error(`Invalid ${PENDING_EVENT} hooks`);
+			for (const event of RECEIVE_EVENTS) if (!Array.isArray(hooks[event] ?? [])) throw new Error(`Invalid ${event} hooks`);
 			held = options.yieldToOtherProfiles === true && otherSessionReceivers(hooks, {
 				configDir,
 				profile: profileName,
 				session: sessionId
 			}).length > 0;
-			const hook = {
-				type: "command",
-				command: node,
-				args: [
-					wrapperPath,
-					cliPath,
-					configDir,
-					profileName,
-					agentAddress,
-					sessionId,
-					HOOK_MARKER
-				],
-				asyncRewake: true,
-				timeout: 604800
-			};
-			const pendingHook = {
-				type: "command",
-				command: node,
-				args: [
-					pendingPath,
-					cliPath,
-					configDir,
-					profileName,
-					agentAddress,
-					sessionId,
-					PENDING_MARKER
-				],
-				timeout: 10
-			};
-			const isOwnPendingHook = (candidate) => record$1(candidate) && candidate.type === "command" && Array.isArray(candidate.args) && candidate.args.length === 7 && typeof candidate.args[0] === "string" && basename(candidate.args[0]) === "claude-pending-mail.mjs" && candidate.args[2] === configDir && candidate.args[3] === profileName && candidate.args[5] === sessionId && candidate.args[6] === PENDING_MARKER;
-			const isOwnHook = (candidate) => {
-				if (!record$1(candidate) || !Array.isArray(candidate.args)) return false;
-				if (typeof candidate.args[0] !== "string" || basename(candidate.args[0]) !== "claude-wake.mjs" || candidate.args[2] !== configDir || candidate.args[3] !== profileName) return false;
-				if (candidate.args.length === 7 && candidate.args[5] === sessionId && candidate.args[6] === HOOK_MARKER) return true;
-				if (candidate.args.length !== 6 || candidate.args[5] !== HOOK_MARKER) return false;
+			const isOwnLegacyHook = (parsed) => {
+				if (!parsed || parsed.shared || parsed.session !== null || parsed.profile !== profileName || resolve(parsed.configDir) !== configDir) return false;
 				try {
 					const state = readMailJson(join(agentProfileDirectory(configDir, profileName), "setup.json"));
 					return record$1(state) && state.session === sessionId;
@@ -1522,39 +1734,50 @@ function installClaudeWakeHook(options) {
 					return false;
 				}
 			};
+			const perSession = (parsed) => parsed !== null && !parsed.shared && parsed.profile !== null && parsed.session !== null;
+			if (!held) addSessionReceiver(configDir, sessionId, {
+				profile: profileName,
+				address: agentAddress
+			});
 			const nextHooks = { ...hooks };
-			for (const event of WAKE_EVENTS) {
-				const entries = hooks[event];
-				const retained = (entries ?? []).flatMap((entry) => {
+			for (const event of RECEIVE_EVENTS) {
+				const entries = hooks[event] ?? [];
+				const ownShared = (candidate) => {
+					const parsed = parseReceiveHook(candidate);
+					return parsed?.shared === true && resolve(parsed.configDir) === configDir;
+				};
+				const wanted = sharedHookEntry(event, cli, configDir, node);
+				const [wantedHook] = wanted.hooks;
+				const existing = entries.flatMap((entry) => record$1(entry) && Array.isArray(entry.hooks) ? entry.hooks.filter(ownShared) : []);
+				const reuse = held || existing.length === 1 && JSON.stringify(existing[0]) === JSON.stringify(wantedHook) && hasSharedHook(hooks, event, configDir, node);
+				const keep = (candidate) => {
+					const parsed = parseReceiveHook(candidate);
+					if (!parsed) return true;
+					if (isOwnLegacyHook(parsed)) return false;
+					if (!existsSync(parsed.configDir)) return false;
+					if (parsed.shared) return resolve(parsed.configDir) !== configDir || reuse;
+					if (!perSession(parsed)) return true;
+					if (held && !(parsed.profile === profileName && parsed.session?.toLowerCase() === sessionId && resolve(parsed.configDir) === configDir)) return true;
+					if (resolve(parsed.configDir) !== configDir) return profileStillConnected(parsed.configDir, parsed.profile ?? "");
+					const current = foldedReceiver(parsed);
+					if (current && !held) addSessionReceiver(configDir, current.session, {
+						profile: current.profile,
+						address: current.address
+					});
+					return false;
+				};
+				const retained = entries.flatMap((entry) => {
 					if (!record$1(entry) || !Array.isArray(entry.hooks)) return [entry];
-					const siblings = entry.hooks.filter((candidate) => !isOwnHook(candidate));
+					const siblings = entry.hooks.filter(keep);
 					if (siblings.length === entry.hooks.length) return [entry];
 					return siblings.length ? [{
 						...entry,
 						hooks: siblings
 					}] : [];
 				});
-				if (held) {
-					if (entries) nextHooks[event] = retained;
-				} else nextHooks[event] = [...retained, event === "SessionStart" ? {
-					matcher: "resume",
-					hooks: [hook]
-				} : { hooks: [hook] }];
+				if (hooks[event] !== void 0 || !reuse) nextHooks[event] = reuse ? retained : [...retained, wanted];
 			}
-			const pendingEntries = hooks[PENDING_EVENT];
-			const pendingRetained = (pendingEntries ?? []).flatMap((entry) => {
-				if (!record$1(entry) || !Array.isArray(entry.hooks)) return [entry];
-				const siblings = entry.hooks.filter((candidate) => !isOwnPendingHook(candidate));
-				if (siblings.length === entry.hooks.length) return [entry];
-				return siblings.length ? [{
-					...entry,
-					hooks: siblings
-				}] : [];
-			});
-			if (held) {
-				if (pendingEntries) nextHooks[PENDING_EVENT] = pendingRetained;
-			} else nextHooks[PENDING_EVENT] = [...pendingRetained, { hooks: [pendingHook] }];
-			if (held && JSON.stringify(nextHooks) === JSON.stringify(hooks)) return null;
+			if (JSON.stringify(nextHooks) === JSON.stringify(hooks)) return null;
 			return {
 				...settings,
 				hooks: nextHooks
@@ -1565,7 +1788,12 @@ function installClaudeWakeHook(options) {
 		return "unavailable";
 	}
 }
-/** Remove only this profile's exact-session hooks after disconnection. */
+/**
+* Stop receiving as this profile in the session after disconnection: its
+* receiver record goes, with any per-session hooks an earlier version wrote
+* for it. The shared hooks stay; for a session with no receivers they exit
+* at once.
+*/
 function uninstallClaudeWakeHook(options) {
 	try {
 		const configDir = resolve(options.configDir);
@@ -1575,12 +1803,12 @@ function uninstallClaudeWakeHook(options) {
 		const sessionId = options.sessionId.toLowerCase();
 		const env = options.env ?? process.env;
 		const claudeDir = resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
+		removeSessionReceiver(configDir, sessionId, profileName);
 		if (!existsSync(join(claudeDir, "settings.json"))) return true;
 		return editClaudeSettings(claudeDir, (settings) => {
 			const hooks = settings.hooks ?? {};
 			if (!record$1(hooks)) throw new Error("Invalid hook settings");
-			for (const event of WAKE_EVENTS) if (!Array.isArray(hooks[event] ?? [])) throw new Error(`Invalid ${event} hooks`);
-			if (!Array.isArray(hooks[PENDING_EVENT] ?? [])) throw new Error(`Invalid ${PENDING_EVENT} hooks`);
+			for (const event of RECEIVE_EVENTS) if (!Array.isArray(hooks[event] ?? [])) throw new Error(`Invalid ${event} hooks`);
 			const legacySessionMatches = () => {
 				try {
 					const setup = readMailJson(join(agentProfileDirectory(configDir, profileName), "setup.json"));
@@ -1590,38 +1818,25 @@ function uninstallClaudeWakeHook(options) {
 				}
 			};
 			const isOwnHook = (candidate) => {
-				if (!record$1(candidate) || !Array.isArray(candidate.args)) return false;
-				const args = candidate.args;
-				return candidate.type === "command" && typeof candidate.command === "string" && candidate.asyncRewake === true && typeof args[0] === "string" && basename(args[0]) === "claude-wake.mjs" && typeof args[1] === "string" && args[2] === configDir && args[3] === profileName && args[4] === agentAddress && (args.length === 7 && args[5] === sessionId && args[6] === HOOK_MARKER || args.length === 6 && args[5] === HOOK_MARKER && legacySessionMatches());
-			};
-			const isOwnPendingHook = (candidate) => {
-				if (!record$1(candidate) || !Array.isArray(candidate.args)) return false;
-				const args = candidate.args;
-				return candidate.type === "command" && typeof candidate.command === "string" && typeof args[0] === "string" && basename(args[0]) === "claude-pending-mail.mjs" && args[2] === configDir && args[3] === profileName && args[4] === agentAddress && args[5] === sessionId && args[6] === PENDING_MARKER && args.length === 7;
+				const parsed = parseReceiveHook(candidate);
+				return parsed !== null && !parsed.shared && resolve(parsed.configDir) === configDir && parsed.profile === profileName && parsed.address === agentAddress && (parsed.session === null ? legacySessionMatches() : parsed.session.toLowerCase() === sessionId);
 			};
 			let removed = false;
 			const nextHooks = { ...hooks };
-			for (const event of WAKE_EVENTS) nextHooks[event] = (hooks[event] ?? []).flatMap((entry) => {
-				if (!record$1(entry) || !Array.isArray(entry.hooks)) return [entry];
-				const siblings = entry.hooks.filter((candidate) => !isOwnHook(candidate));
-				if (siblings.length === entry.hooks.length) return [entry];
-				removed = true;
-				return siblings.length ? [{
-					...entry,
-					hooks: siblings
-				}] : [];
-			});
-			const pendingEntries = hooks[PENDING_EVENT];
-			nextHooks[PENDING_EVENT] = (pendingEntries ?? []).flatMap((entry) => {
-				if (!record$1(entry) || !Array.isArray(entry.hooks)) return [entry];
-				const siblings = entry.hooks.filter((candidate) => !isOwnPendingHook(candidate));
-				if (siblings.length === entry.hooks.length) return [entry];
-				removed = true;
-				return siblings.length ? [{
-					...entry,
-					hooks: siblings
-				}] : [];
-			});
+			for (const event of RECEIVE_EVENTS) {
+				const entries = hooks[event];
+				if (!entries) continue;
+				nextHooks[event] = entries.flatMap((entry) => {
+					if (!record$1(entry) || !Array.isArray(entry.hooks)) return [entry];
+					const siblings = entry.hooks.filter((candidate) => !isOwnHook(candidate));
+					if (siblings.length === entry.hooks.length) return [entry];
+					removed = true;
+					return siblings.length ? [{
+						...entry,
+						hooks: siblings
+					}] : [];
+				});
+			}
 			return removed ? {
 				...settings,
 				hooks: nextHooks
@@ -1821,6 +2036,12 @@ var AgentInvitationRejectedError = class extends AgentConnectionSetupError {
 		this.reason = reason;
 	}
 };
+/**
+* The claim was never sent: another setup on this machine held the claim
+* lock for the whole wait. Unlike an uncertain claim, the invitation is
+* untouched, so a caller may discard what it created for this run.
+*/
+var ClaimNotSubmittedError = class extends AgentConnectionSetupError {};
 const NOTHING_CHANGED = "Nothing was changed on this machine.";
 /**
 * Restates a refusal that followed a replacement: the agent being replaced
@@ -2122,9 +2343,16 @@ async function connectAgent(params) {
 	let release;
 	try {
 		privateMailDirectory(directory, true);
-		release = params.claimLockHeld ? () => {} : acquireListenLock(directory, "agent-connection-setup");
 	} catch {
-		throw new AgentConnectionSetupError("Agent setup is already running, or its private directory is unavailable. No invitation was submitted.");
+		throw new ClaimNotSubmittedError("This machine's private agent directory is unavailable. No invitation was submitted.");
+	}
+	if (params.claimLockHeld) release = () => {};
+	const deadline = Date.now() + Math.max(0, params.claimLockWaitMs ?? 0);
+	while (!release) try {
+		release = acquireListenLock(directory, "agent-connection-setup");
+	} catch {
+		if (Date.now() >= deadline) throw new ClaimNotSubmittedError("Agent setup is already running on this machine, so this invitation was not submitted; rerun the same command when it finishes.");
+		await setTimeout$1(Math.min(250, Math.max(1, deadline - Date.now())));
 	}
 	try {
 		const existing = loadConnectedAgentProfile(params.configDir, profileName);
@@ -3411,6 +3639,140 @@ function createNotificationContactPolicy(options) {
 	};
 }
 //#endregion
+//#region src/oclif/registration-log.ts
+/**
+* A short private record of this profile's registration attempts, so a
+* stuck registration can be explained by `agent connect --status` and
+* `whoami` without anyone opening profile files. It holds phase changes,
+* error codes, the organization id and the agent address only: never a
+* token, key, claim URL or response body.
+*/
+const LOG_FILE = "registration-log.json";
+const MAX_DETAIL = 400;
+const MAX_BYTES = 65536;
+/**
+* Removes anything that could carry a credential: setup URLs and their
+* fragments, token parameters and Primitive key or token prefixes. The
+* messages written here are the CLI's own refusals, so this is a second
+* line of defence, not the only one.
+*/
+function scrubRegistrationDetail(text) {
+	return text.replace(/https?:\/\/\S*agent-connections\/setup\S*/gi, "[setup URL]").replace(/#?token=[^\s"'&]+/gi, "token=[redacted]").replace(/\b(?:prim|pconn|invite|invitation)_[A-Za-z0-9_-]+/g, "[redacted]").replace(/\bBearer\s+\S+/gi, "Bearer [redacted]").slice(0, MAX_DETAIL);
+}
+function logPath(configDir, profileName) {
+	return join(agentProfileDirectory(configDir, profileName), LOG_FILE);
+}
+function entryFrom(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const row = value;
+	const text = (key) => typeof row[key] === "string" ? row[key] : null;
+	const at = text("at");
+	const event = text("event");
+	if (!at || !event || !Number.isFinite(Date.parse(at))) return null;
+	return {
+		at,
+		event,
+		phase: text("phase"),
+		code: text("code"),
+		orgId: text("orgId"),
+		address: text("address"),
+		detail: text("detail")
+	};
+}
+/** Every saved entry, oldest first. Empty when there is no readable log. */
+function readRegistrationLog(configDir, profileName) {
+	try {
+		const saved = readMailJson(logPath(configDir, profileName), MAX_BYTES);
+		if (saved?.version !== 1 || !Array.isArray(saved.entries)) return [];
+		return saved.entries.map(entryFrom).filter((row) => row !== null);
+	} catch {
+		return [];
+	}
+}
+/** Appends one entry, keeping the most recent ones. Best effort. */
+function appendRegistrationLog(configDir, profileName, entry) {
+	try {
+		const row = {
+			at: entry.at ?? (/* @__PURE__ */ new Date()).toISOString(),
+			event: entry.event,
+			phase: entry.phase,
+			code: entry.code,
+			orgId: entry.orgId,
+			address: entry.address,
+			detail: entry.detail === void 0 || entry.detail === null ? null : scrubRegistrationDetail(entry.detail)
+		};
+		const entries = [...readRegistrationLog(configDir, profileName), row].slice(-30);
+		writeMailJson(logPath(configDir, profileName), {
+			version: 1,
+			entries
+		});
+	} catch {}
+}
+/** What the last registration attempt did, or null when none was recorded. */
+function registrationSummary(configDir, profileName) {
+	const entries = readRegistrationLog(configDir, profileName);
+	const last = entries.at(-1);
+	if (!last) return null;
+	const address = [...entries].reverse().find((row) => row.address !== null)?.address ?? null;
+	const orgId = [...entries].reverse().find((row) => row.orgId !== null)?.orgId ?? null;
+	return {
+		lastAttemptAt: last.at,
+		lastEvent: last.event,
+		address,
+		orgId,
+		lastFailure: last.event === "failed" ? {
+			at: last.at,
+			code: last.code,
+			detail: last.detail
+		} : null
+	};
+}
+/** The lock scope an enrollment holds on its profile's enrollment directory. */
+const ENROLLMENT_LOCK_SCOPE = "agent-enrollment";
+/** Profiles whose registration is running right now on this machine. */
+function registrationsInFlight(configDir) {
+	let names;
+	try {
+		names = readdirSync(join(agentProfilesDirectory(configDir), "profiles"));
+	} catch {
+		return [];
+	}
+	return names.sort().filter((name) => listenLockHeld(join(agentProfilesDirectory(configDir), "profiles", name, "enrollment"), ENROLLMENT_LOCK_SCOPE));
+}
+/**
+* Waits up to `budgetMs` for running registrations to finish, so a login
+* switch does not change the member login underneath one. Returns the
+* profiles still registering when the budget ran out.
+*/
+async function waitForRegistrations(configDir, budgetMs, options = {}) {
+	const deadline = Date.now() + budgetMs;
+	let running = registrationsInFlight(configDir);
+	if (running.length) options.onWait?.(running);
+	while (running.length && Date.now() < deadline) {
+		await setTimeout$1(Math.min(options.pollMs ?? 250, deadline - Date.now()));
+		running = registrationsInFlight(configDir);
+	}
+	return running;
+}
+/** One line for people: what the last registration attempt did. */
+function registrationSummaryLine(summary) {
+	const failure = summary.lastFailure;
+	return failure ? `The last registration attempt for this session${summary.address ? ` (${summary.address})` : ""} failed at ${failure.at}${failure.code ? ` (${failure.code})` : ""}: ${failure.detail ?? "no detail was recorded."}` : `The last registration attempt for this session${summary.address ? ` (${summary.address})` : ""} reached "${summary.lastEvent}" at ${summary.lastAttemptAt}.`;
+}
+/**
+* The failed registration of this session's own profile, when the session
+* has no connected credential there. Null when it is connected, never
+* registered, or its last attempt did not fail. Offline and read-only.
+*/
+function failedSessionRegistration(configDir, session) {
+	const profile = `session-${session.toLowerCase()}`;
+	try {
+		if (loadConnectedAgentProfile(configDir, profile)) return null;
+	} catch {}
+	const summary = registrationSummary(configDir, profile);
+	return summary?.lastFailure ? summary : null;
+}
+//#endregion
 //#region src/oclif/agent-setup.ts
 const SUBJECT = "Connect your agent to Primitive";
 const MARKER = /\bprimitive-connection:([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}):([1-9]\d*)\b/g;
@@ -3786,6 +4148,44 @@ function refuseSetupConflicts(state, params) {
 	];
 	if (conflicts.length) throw fail(`This profile's saved setup conflicts with ${conflicts.join(" and ")}. Omit the option to reuse the saved setup. Its session and notification preferences were not changed.${params.resume ? "" : " Do not create a separate profile on your own: if this session should get a different address, ask the user whether to keep the existing one or disconnect it first."}`);
 }
+/** How long a claim waits for another claim on this machine to finish. */
+const CLAIM_LOCK_WAIT_MS = 3e4;
+/**
+* Moves a file aside as `replaced-<stamp>-<name>`, keeping it for recovery.
+* Returns where it went, or null when there was no file.
+*/
+function moveAside(path, now) {
+	const stamp = now.toISOString().replace(/[^0-9]/g, "");
+	const target = join(dirname(path), `replaced-${stamp}-${basename(path)}`);
+	try {
+		renameSync(path, target);
+		return target;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		return null;
+	}
+}
+/** The address an unfinished enrollment in this profile reserved, if any. */
+function pendingEnrollmentAddress(directory) {
+	try {
+		const saved = readMailJson(join(directory, "enrollment", "state.json"));
+		return typeof saved?.address === "string" ? saved.address : null;
+	} catch {
+		return null;
+	}
+}
+/** A connected credential is saved in this profile. Unreadable counts as one. */
+function holdsCredential(configDir, profileName) {
+	try {
+		return loadConnectedAgentProfile(configDir, profileName) !== null;
+	} catch {
+		return true;
+	}
+}
+/** The one next step when a profile has setup progress but no credential. */
+function unfinishedSetupStep(address) {
+	return address ? `This session's agent ${address} is created but not connected: in the Primitive app open it and choose Copy again, then paste that setup instruction here; \`agent connect\` finishes the same address.` : "This profile's earlier setup never finished and holds no credential: ask the owner to copy a fresh setup instruction from the Primitive app and paste it here; `agent connect` claims it into this same profile.";
+}
 function invitationHashOrNull(invitation) {
 	if (invitation === void 0) return null;
 	try {
@@ -3815,7 +4215,8 @@ async function setupAgent(params) {
 	} catch {}
 	const newHash = params.resume ? null : invitationHashOrNull(params.invitation);
 	const replacesRevoked = (state) => newHash !== null && state.invitationHash !== newHash && savedSetupRevoked(params.configDir, profileName, state.invitationHash);
-	if (saved && !replacesRevoked(saved)) refuseSetupConflicts(saved, params);
+	const replacesUnfinished = (state) => newHash !== null && state.invitationHash !== newHash && state.phase === "waiting" && !holdsCredential(params.configDir, profileName);
+	if (saved && !replacesRevoked(saved) && !replacesUnfinished(saved)) refuseSetupConflicts(saved, params);
 	const receiverMode = params.receiverMode ?? (params.resume ? saved?.receiverMode : void 0);
 	if (params.session === void 0 && (receiverMode ?? "native") !== "poll") throw fail("--session requires the exact loaded session UUID. Without one, use --receiver poll. No invitation was claimed.");
 	if ((receiverMode ?? "native") === "native" && params.session) try {
@@ -3826,13 +4227,31 @@ async function setupAgent(params) {
 	privateMailDirectory(directory, true);
 	const release = acquireListenLock(directory, "setup");
 	let releaseClaim;
+	let releaseEnrollment;
+	let replacedUnfinished;
+	const moved = [];
+	let retireEnrollment = false;
+	const setAside = (from, at) => {
+		const to = moveAside(from, at);
+		if (to) moved.push({
+			from,
+			to
+		});
+	};
 	let discardStub = false;
 	let claimedName;
+	const takeEnrollment = () => {
+		try {
+			releaseEnrollment = acquireListenLock(join(directory, "enrollment"), ENROLLMENT_LOCK_SCOPE);
+		} catch {
+			throw fail("This session's background registration is still running, so this invitation was not claimed; wait a few seconds and rerun the same command.");
+		}
+	};
 	try {
 		const path = join(directory, "setup.json");
 		const value = readMailJson(path);
 		let state = value === null ? null : parseState(value);
-		if (state && replacesRevoked(state)) {
+		if (state && (replacesRevoked(state) || replacesUnfinished(state))) {
 			try {
 				releaseClaim = acquireListenLock(agentProfilesDirectory(params.configDir), "agent-connection-setup");
 			} catch {
@@ -3843,8 +4262,19 @@ async function setupAgent(params) {
 			if (state && replacesRevoked(state)) {
 				archiveRevokedSetup(params.configDir, profileName, new Date(dependencies.now()));
 				state = null;
+			} else if (state && replacesUnfinished(state)) {
+				if (!params.enrollmentOwned) takeEnrollment();
+				replacedUnfinished = { address: pendingEnrollmentAddress(directory) };
+				setAside(path, new Date(dependencies.now()));
+				retireEnrollment = !params.enrollmentOwned;
+				state = null;
 			}
 		}
+		if (!params.resume && !state && !params.enrollmentOwned && !releaseEnrollment && !holdsCredential(params.configDir, profileName) && existsSync(join(directory, "enrollment", "state.json"))) {
+			takeEnrollment();
+			replacedUnfinished = { address: pendingEnrollmentAddress(directory) };
+			retireEnrollment = true;
+		}
 		if (state) refuseSetupConflicts(state, params);
 		if (!state && loadConnectedAgentProfile(params.configDir, profileName)) throw fail("This profile was configured without a setup binding. Use its existing session setup; do not adopt it into another session.");
 		if (params.resume && !state) throw fail("No resumable setup exists for this profile. Do not adopt another session's identity.");
@@ -3874,16 +4304,29 @@ async function setupAgent(params) {
 					invitation: params.invitation ?? "",
 					fetch: params.fetch,
 					presence: true,
-					claimLockHeld: releaseClaim !== void 0
+					claimLockHeld: releaseClaim !== void 0,
+					claimLockWaitMs: params.claimLockWaitMs ?? CLAIM_LOCK_WAIT_MS
 				})).name;
+				if (retireEnrollment) moveAside(join(directory, "enrollment", "state.json"), new Date(dependencies.now()));
+				if (replacedUnfinished?.address) appendRegistrationLog(params.configDir, profileName, {
+					event: "replaced_unfinished",
+					phase: null,
+					code: null,
+					orgId: null,
+					address: replacedUnfinished.address,
+					detail: "A pasted setup instruction finished this session's unfinished registration."
+				});
 			} catch (error) {
-				if (error instanceof AgentInvitationRejectedError && created) {
+				if ((error instanceof AgentInvitationRejectedError || error instanceof ClaimNotSubmittedError) && created) {
 					discardStub = true;
 					try {
 						removeMailFile(path);
 					} catch {
 						discardStub = false;
 					}
+					if (discardStub) for (const { from, to } of moved.splice(0).reverse()) try {
+						renameSync(to, from);
+					} catch {}
 				}
 				throw error;
 			} finally {
@@ -3892,7 +4335,8 @@ async function setupAgent(params) {
 			}
 		}
 		const profile = loadConnectedAgentProfile(params.configDir, profileName);
-		if (!profile || !state || profile.invitation_hash !== state.invitationHash) throw fail("The claim has no matching saved credential. Preserve private state and request a fresh invitation; do not replay this one.");
+		if (!profile) throw fail(unfinishedSetupStep(pendingEnrollmentAddress(directory)));
+		if (!state || profile.invitation_hash !== state.invitationHash) throw fail("The claim has no matching saved credential. Preserve private state and request a fresh invitation; do not replay this one.");
 		const setupBudgetMs = Math.max(9e4, timeoutMs + 3e4);
 		const readBudget = {
 			deadline: dependencies.now() + setupBudgetMs,
@@ -3923,6 +4367,10 @@ async function setupAgent(params) {
 		claimedName ??= savedConnectionName(params.configDir, profileName);
 		const result = (receiving, ownerNotifications) => ({
 			identity: context.identity,
+			...replacedUnfinished ? { replacedUnfinished: {
+				address: replacedUnfinished.address,
+				sameAddress: replacedUnfinished.address === null ? null : replacedUnfinished.address.toLowerCase() === context.identity.agentAddress.toLowerCase()
+			} } : {},
 			...claimedName === void 0 ? {} : { connectionName: claimedName },
 			sessionId: params.session ?? state?.session ?? null,
 			verification: {
@@ -3979,6 +4427,7 @@ async function setupAgent(params) {
 		return result(state.receiverMode === "external" ? EXTERNAL_HOOKS_PENDING : state.receiverMode === "poll" ? "poll" : healthy ? "healthy" : "not_ready", ownerNotifications);
 	} finally {
 		releaseClaim?.();
+		releaseEnrollment?.();
 		release();
 		if (discardStub) removeEmptyDirectory(directory);
 	}
@@ -4209,6 +4658,11 @@ async function seedAgentInfoNote(configDir, profileName, value, fetchImpl) {
 		return "failed";
 	}
 }
+/** What a claim that replaced an unfinished setup did to its agent. */
+function unfinishedNote(replaced) {
+	if (!replaced?.address) return "";
+	return replaced.sameAddress ? `This finished the session's unfinished agent ${replaced.address}. ` : `This invitation was for a different address, so the session's earlier unfinished agent ${replaced.address} stays unconnected in the Primitive app; tell the owner so they can remove it there if it is not needed. `;
+}
 /**
 * One call: self check, install the matching skill, claim and verify, start
 * receiving, seed AGENT_INFO, and report everything as one result. Every step
@@ -4419,13 +4873,14 @@ async function runAgentConnect(options) {
 		verification: result.verification,
 		receiving,
 		...result.ownerNotifications ? { ownerNotifications: result.ownerNotifications } : {},
+		...result.replacedUnfinished ? { replacedUnfinished: result.replacedUnfinished } : {},
 		agentInfo: agentInfoState,
 		resumeNote,
 		skipped,
 		warnings,
 		selectProfile: `PRIMITIVE_AGENT_PROFILE=${result.identity.profileName}`,
 		resumeCommand,
-		guidance: `${result.guidance} ${ownerReportGuidance(identity)}`,
+		guidance: `${unfinishedNote(result.replacedUnfinished)}${result.guidance} ${ownerReportGuidance(identity)}`,
 		identity,
 		externalHook
 	};
@@ -4437,7 +4892,23 @@ const CONNECTION_LIST_LIMIT = 131072;
 const CONFIRMATION_BUDGET_MS = 12e4;
 const CONFIRMATION_MAX_ATTEMPTS = 40;
 const CONFIRMATION_PAGE_LIMIT = 20;
+/** How long a member-login refresh waits out another credential operation. */
+const CREDENTIAL_LOCK_WAIT_MS = 15e3;
+/** Fresh invitations a stuck enrollment may issue for itself, in total. */
+const HEAL_MAX_ATTEMPTS = 3;
 const refuse = (message) => new AgentConnectionSetupError(message);
+/**
+* The one next step for a session whose agent exists but never connected.
+* Copying the setup instruction again in the app issues a fresh invitation
+* for the same address, and `agent connect` claims it into this session.
+*/
+function stuckEnrollmentStep(address) {
+	return unfinishedSetupStep(address);
+}
+/** The one next step for a session whose agent was disconnected or taken over. */
+function reconnectStep(address, why) {
+	return `This session's agent ${address} ${why}, so this machine did not change it: in the Primitive app open it and choose Reconnect, then paste that setup instruction here; \`agent connect\` finishes the same address.`;
+}
 function plainRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -4632,15 +5103,14 @@ async function enableAgentContactRequests(options) {
 }
 async function readOwnerConnection(enrollment, params, deadline, listed) {
 	const saved = loadCliCredentials(params.configDir);
-	if (!saved || saved.org_id !== enrollment.orgId || saved.oauth_grant_id !== enrollment.grantId || saved.api_base_url !== enrollment.apiBaseUrl) throw refuse("The saved member login changed before connection confirmation. Preserve this session's profile and resume with the original member login.");
-	const credentials = await refreshStoredCliCredentials({
-		apiBaseUrl: enrollment.apiBaseUrl,
-		configDir: params.configDir,
-		credentials: saved,
-		fetch: params.fetch,
-		now: params.now
-	});
-	if (credentials.org_id !== enrollment.orgId || credentials.oauth_grant_id !== enrollment.grantId || credentials.api_base_url !== enrollment.apiBaseUrl) throw refuse("The saved member login changed before connection confirmation. Preserve this session's profile and resume with the original member login.");
+	if (!saved || saved.org_id !== enrollment.orgId || saved.oauth_grant_id !== enrollment.grantId || saved.api_base_url !== enrollment.apiBaseUrl) return "unavailable";
+	let credentials;
+	try {
+		credentials = await refreshMemberLogin(enrollment.apiBaseUrl, saved, params);
+	} catch {
+		return "unavailable";
+	}
+	if (credentials.org_id !== enrollment.orgId || credentials.oauth_grant_id !== enrollment.grantId || credentials.api_base_url !== enrollment.apiBaseUrl) return "unavailable";
 	let cursor;
 	for (let page = 0; page < CONFIRMATION_PAGE_LIMIT; page++) {
 		const remaining = deadline - Date.now();
@@ -4672,7 +5142,7 @@ async function readOwnerConnection(enrollment, params, deadline, listed) {
 		for (const candidate of envelope.data) {
 			const connection = plainRecord(candidate);
 			if (connection?.address !== enrollment.address) continue;
-			if (connection.owner_address !== enrollment.ownerAddress) throw refuse("The owner connection list did not match this session's saved identity. Preserve the profile and inspect the connection in the app.");
+			if (connection.owner_address !== enrollment.ownerAddress) throw refuse(`The owner connection list names a different control address for ${enrollment.address}, so this machine changed nothing: in the Primitive app open it and choose Reconnect, then paste that setup instruction here.`);
 			if (typeof connection.name === "string") listed.name = connection.name;
 			if (connection.owner_active === false) return "owner_inactive";
 			if (connection.status === "revoked") return "revoked";
@@ -4716,6 +5186,171 @@ function enrollmentResumes(configDir, session) {
 		return false;
 	}
 }
+function credentialLockBusy(error) {
+	return error instanceof Error && error.message.includes("credential operation is already in progress");
+}
+/**
+* Refreshes the saved member login, waiting out another credential
+* operation (a login or logout in another terminal) instead of failing on
+* its lock. The caller compares the returned login with the one it expects.
+*/
+async function refreshMemberLogin(apiBaseUrl, saved, params) {
+	const deadline = Date.now() + (params.credentialLockWaitMs ?? CREDENTIAL_LOCK_WAIT_MS);
+	for (;;) try {
+		return await refreshStoredCliCredentials({
+			apiBaseUrl,
+			configDir: params.configDir,
+			credentials: saved,
+			fetch: params.fetch,
+			now: params.now
+		});
+	} catch (error) {
+		if (!credentialLockBusy(error) || Date.now() >= deadline) throw error;
+		await setTimeout$1(Math.min(500, Math.max(1, deadline - Date.now())));
+	}
+}
+/**
+* One connection the signed-in member personally owns, read page by page
+* from their own list (`owner=self`), so a login that does not own the
+* agent never finds it.
+*/
+async function findOwnedConnection(client, address) {
+	let cursor;
+	for (let page = 0; page < CONFIRMATION_PAGE_LIMIT; page++) {
+		let value;
+		try {
+			const response = await listAgentConnections({
+				client: client.client,
+				query: {
+					limit: 50,
+					owner: "self",
+					...cursor ? { cursor } : {}
+				},
+				signal: AbortSignal.timeout(1e4),
+				responseStyle: "fields"
+			});
+			if (response.error) return "unavailable";
+			value = response.data;
+		} catch {
+			return "unavailable";
+		}
+		const envelope = plainRecord(value);
+		if (envelope?.success !== true || !Array.isArray(envelope.data)) return "unavailable";
+		for (const candidate of envelope.data) {
+			const row = plainRecord(candidate);
+			if (row?.address !== address) continue;
+			return {
+				status: String(row.status),
+				ownerAddress: row.owner_address
+			};
+		}
+		const next = plainRecord(envelope.meta)?.cursor;
+		if (next === null) return "absent";
+		if (typeof next !== "string" || !SESSION_UUID.test(next) || next === cursor) return "unavailable";
+		cursor = next;
+	}
+	return "unavailable";
+}
+function healAttempts(path) {
+	try {
+		const saved = readMailJson(path);
+		return saved?.version === 1 && Number.isSafeInteger(saved.attempts) ? Number(saved.attempts) : 0;
+	} catch {
+		return HEAL_MAX_ATTEMPTS;
+	}
+}
+/**
+* A stuck enrollment: its address exists and its claim never produced a
+* saved credential (the claim was never sent, was refused, or its response
+* was lost). With the owner's member login for the same organization, it
+* asks Primitive for a fresh invitation for the same address and returns it
+* for this session to claim. It never creates another address and only
+* heals a pending connection, with a pending-only invitation. Every refusal
+* names the one next step.
+*/
+async function healStuckEnrollment(state, params, saved, directory) {
+	const stuck = stuckEnrollmentStep(state.address);
+	if (saved.org_id !== state.orgId || connectedApiBaseUrl(saved.api_base_url) !== state.apiBaseUrl) throw refuse(stuck);
+	const healPath = join(directory, "heal.json");
+	const attempts = healAttempts(healPath);
+	if (attempts >= HEAL_MAX_ATTEMPTS) throw refuse(stuck);
+	let credentials;
+	try {
+		credentials = await refreshMemberLogin(state.apiBaseUrl, saved, params);
+	} catch (error) {
+		if (credentialLockBusy(error)) throw refuse(`Another Primitive login is still in progress, so this session's agent ${state.address} was not finished yet; rerun this command once that login completes.`);
+		throw refuse(stuck);
+	}
+	if (credentials.org_id !== state.orgId || credentials.api_base_url !== state.apiBaseUrl) throw refuse(stuck);
+	const client = new PrimitiveApiClient({
+		apiKey: credentials.access_token,
+		apiBaseUrl: state.apiBaseUrl,
+		fetch: params.fetch
+	});
+	const row = await findOwnedConnection(client, state.address);
+	if (row === "unavailable") throw refuse(`Primitive could not be reached to finish this session's agent ${state.address}; rerun this command (or start the session again) to retry.`);
+	if (row === "absent" || row.ownerAddress !== state.ownerAddress) throw refuse(stuck);
+	if (row.status === "revoked") throw refuse(reconnectStep(state.address, "was disconnected in the Primitive app"));
+	if (row.status !== "pending") throw refuse(reconnectStep(state.address, row.status === "connected" ? "is connected from somewhere else" : "was claimed by another setup"));
+	const record = (count) => writeMailJson(healPath, {
+		version: 1,
+		attempts: count,
+		lastAttemptAt: new Date((params.now ?? Date.now)()).toISOString()
+	});
+	record(attempts + 1);
+	let claimedElsewhere = false;
+	try {
+		const response = await inviteAgentConnection({
+			client: client.client,
+			path: { address: state.address },
+			body: { pending_only: true },
+			signal: AbortSignal.timeout(25e3),
+			responseStyle: "fields"
+		});
+		if (response.error) {
+			claimedElsewhere = plainRecord(plainRecord(response.error)?.error)?.code === "connection_already_claimed";
+			throw new Error();
+		}
+		const invitation = invitationFrom(response.data, state, (params.now ?? Date.now)());
+		if (invitation.ownerAddress !== state.ownerAddress) throw new Error();
+		return {
+			...invitation,
+			grantId: credentials.oauth_grant_id
+		};
+	} catch {
+		if (claimedElsewhere) throw refuse(reconnectStep(state.address, "was claimed by another setup"));
+		try {
+			record(HEAL_MAX_ATTEMPTS);
+		} catch {}
+		throw refuse(stuck);
+	}
+}
+/** A short code for the registration log, from the refusal it explains. */
+function failureCode(error) {
+	if (!(error instanceof AgentConnectionSetupError)) return "unexpected_error";
+	const text = error.message;
+	if (text.includes("is created but not connected")) return "setup_unfinished";
+	if (text.includes("choose Reconnect")) return "reconnect_needed";
+	if (text.includes("could not be reached")) return "api_unavailable";
+	if (text.includes("login is still in progress")) return "login_in_progress";
+	if (text.includes("Sign in") || text.includes("sign in")) return "login_required";
+	return "refused";
+}
+/**
+* The address this session's enrollment reserved when it has no saved
+* credential yet, so a refusal can name the step that finishes it. Null when
+* there is no such enrollment. Offline and read-only.
+*/
+function unfinishedEnrollmentAddress(configDir, session) {
+	const profile = `session-${session}`;
+	try {
+		if (loadConnectedAgentProfile(configDir, profile)) return null;
+		const raw = readMailJson(join(agentProfileDirectory(configDir, profile), "enrollment", "state.json"));
+		return raw === null ? null : savedEnrollment(raw).address;
+	} catch {
+		return null;
+	}
+}
 /** Trusted-machine enrollment using only saved member OAuth and the public API. */
 async function enrollAgent(params) {
 	if (!SESSION_UUID.test(params.session)) throw refuse("Enrollment requires the exact current session UUID.");
@@ -4726,24 +5361,58 @@ async function enrollAgent(params) {
 	const env = params.env ?? process.env;
 	if (env["PRIMITIVE_AGENT_PROFILE"]?.trim() || env.PRIMITIVE_API_KEY?.trim() || env.PRIMITIVE_KEY?.trim()) throw refuse("Enrollment uses only the saved member login; rerun it under `env -u PRIMITIVE_AGENT_PROFILE -u PRIMITIVE_API_KEY -u PRIMITIVE_KEY` so no agent profile or API key override applies.");
 	const saved = loadCliCredentials(params.configDir);
-	if (!saved) throw refuse("Sign in with `primitive signin` as a member of this organization first.");
+	if (!saved) {
+		const pending = unfinishedEnrollmentAddress(params.configDir, params.session);
+		throw refuse(pending ? stuckEnrollmentStep(pending) : "Sign in with `primitive signin` as a member of this organization first.");
+	}
 	const apiBaseUrl = connectedApiBaseUrl(saved.api_base_url);
 	const profile = `session-${params.session}`;
 	const directory = join(agentProfileDirectory(params.configDir, profile), "enrollment");
 	privateMailDirectory(directory, true);
-	const release = acquireListenLock(directory, "agent-enrollment");
+	const release = acquireListenLock(directory, ENROLLMENT_LOCK_SCOPE);
+	const progress = {
+		phase: null,
+		orgId: saved.org_id,
+		address: null
+	};
+	const log = (event, extra = {}) => appendRegistrationLog(params.configDir, profile, {
+		event,
+		phase: progress.phase,
+		code: extra.code ?? null,
+		orgId: progress.orgId,
+		address: progress.address,
+		detail: extra.detail ?? null
+	});
+	const track = (current) => {
+		if (!current) return;
+		progress.phase = current.phase;
+		progress.orgId = current.orgId;
+		progress.address = current.address;
+	};
 	try {
 		await (params.preflight ?? ((session, receiver) => preflight(session, receiver, env)))(params.session, receiverMode);
 		await params.beforeCreate?.();
 		const path = join(directory, "state.json");
 		const old = readMailJson(path);
 		let state = old === null ? null : savedEnrollment(old);
+		track(state);
+		log("started");
 		if (state && params.name === void 0) name = state.name;
-		if (state && (state.session !== params.session || state.profile !== profile || state.name !== name || state.orgId !== saved.org_id || state.grantId !== saved.oauth_grant_id || state.apiBaseUrl !== apiBaseUrl || state.receiverMode !== receiverMode || state.contactRequests !== contactRequests)) throw refuse("This session's enrollment belongs to another owner, address, or setup choice. Nothing was changed.");
-		if (state && Date.parse(state.startedAt) > (params.now ?? Date.now)() + 6e4) throw refuse("Saved enrollment time is inconsistent. Preserve its private files.");
+		if (state && (state.session !== params.session || state.profile !== profile || state.name !== name || state.receiverMode !== receiverMode || state.contactRequests !== contactRequests)) throw refuse("This session's enrollment was started with different setup choices (name, receiver or contact requests); rerun it with the original options. Nothing was changed.");
 		const existing = loadConnectedAgentProfile(params.configDir, profile);
+		const resumesClaim = Boolean(existing && state?.phase === "setup_attempted");
+		const sameOrganization = state?.orgId === saved.org_id && state.apiBaseUrl === apiBaseUrl;
+		if (state && !sameOrganization && !resumesClaim) throw refuse(state.address && !existing ? stuckEnrollmentStep(state.address) : `This session's enrollment belongs to organization ${state.orgId}, and the saved member login is now for another organization: sign in to ${state.orgId} with \`primitive login\` and rerun this command. Nothing was changed.`);
+		if (state && sameOrganization && state.grantId !== saved.oauth_grant_id) {
+			state = {
+				...state,
+				grantId: saved.oauth_grant_id
+			};
+			writeMailJson(path, state);
+		}
+		if (state && Date.parse(state.startedAt) > (params.now ?? Date.now)() + 6e4) throw refuse("Saved enrollment time is inconsistent. Preserve its private files.");
 		if (existing && (!state || existing.agent_address !== state.address || existing.org_id !== state.orgId || existing.api_base_url !== state.apiBaseUrl || state.phase === "setup_attempted" && (existing.invitation_hash !== state.invitationHash || existing.owner_address !== state.ownerAddress))) throw refuse("This session profile already belongs to another connection. Nothing was changed.");
-		const finish = async (enrollment, resume, invitation) => {
+		const finishSetup = async (enrollment, resume, invitation) => {
 			const setup = await (params.setup ?? setupAgent)({
 				configDir: params.configDir,
 				profileName: profile,
@@ -4751,6 +5420,7 @@ async function enrollAgent(params) {
 				receiverMode,
 				...resume ? { resume: true } : { invitation },
 				contactRequests,
+				enrollmentOwned: true,
 				fetch: params.fetch
 			});
 			const ownerMemberAddress = await refreshOwnerMemberAddress({
@@ -4796,23 +5466,33 @@ async function enrollAgent(params) {
 				name: current.name ?? name
 			};
 		};
+		const finish = async (enrollment, resume, invitation) => {
+			const value = await finishSetup(enrollment, resume, invitation);
+			log("finished", { code: value.connection.status });
+			return value;
+		};
 		if (state?.phase === "setup_attempted") {
-			if (!existing) throw refuse("The invitation claim may have been consumed. Keep this pending agent and inspect it in the app; do not create or claim another address.");
-			return finish(resolvedEnrollment(state), true);
+			if (existing) return await finish(resolvedEnrollment(state), true);
+			const resolved = resolvedEnrollment(state);
+			const healed = await healStuckEnrollment(resolved, params, saved, directory);
+			state = {
+				...resolved,
+				grantId: healed.grantId,
+				invitationHash: healed.hash,
+				ownerAddress: healed.ownerAddress
+			};
+			writeMailJson(path, state);
+			track(state);
+			log("heal_invited", { code: "pending_only" });
+			return await finish(resolvedEnrollment(state), false, healed.url);
 		}
 		if (existing) throw refuse("This profile is already connected without a matching enrollment. Nothing was changed.");
-		if (state?.version === 1) throw refuse("Connection creation may already have happened. Inspect this session's pending address in the app and issue a fresh invitation there if needed. Use `primitive agent connect` with that invitation and this session's profile; do not rerun enrollment or create another address.");
-		const credentials = await refreshStoredCliCredentials({
-			apiBaseUrl,
-			configDir: params.configDir,
-			credentials: saved,
-			fetch: params.fetch,
-			now: params.now
-		});
+		if (state?.version === 1) throw refuse(stuckEnrollmentStep(resolvedEnrollment(state).address));
+		const credentials = await refreshMemberLogin(apiBaseUrl, saved, params);
 		if (credentials.org_id !== saved.org_id || credentials.oauth_grant_id !== saved.oauth_grant_id || credentials.api_base_url !== apiBaseUrl) throw refuse("The saved member login changed during enrollment. No address was created. Sign in to the intended organization and retry this exact session.");
 		const fetchImpl = params.fetch ?? fetch;
 		const firstAttempt = state === null;
-		if (state?.continueAttempted) throw refuse("Continue setup already ran and its result may be uncertain. Inspect the saved agent in the app; do not issue another invitation automatically.");
+		if (state?.continueAttempted) throw refuse(stuckEnrollmentStep(resolvedEnrollment(state).address));
 		if (!state) {
 			if (params.continueSetup) throw refuse("There is no saved enrollment to continue. Start enrollment normally first.");
 			if (!(await managedDomains(new PrimitiveApiClient({
@@ -4894,9 +5574,11 @@ async function enrollAgent(params) {
 			address: connection.address
 		};
 		writeMailJson(path, state);
+		track(state);
+		log("created");
 		if (data?.recovered === true) {
 			if (data.invitation !== null) throw refuse("Recovered setup unexpectedly included an invitation. Preserve the saved identity; no invitation was claimed.");
-			if (connection.status !== "pending") throw refuse("The saved agent is already claimed, connected or disconnected. Its credential was not changed. Inspect it in the app; do not automatically reconnect it.");
+			if (connection.status !== "pending") throw refuse(reconnectStep(connection.address, connection.status === "revoked" ? "was disconnected in the Primitive app and its credential was not changed" : "was already claimed and its credential was not changed"));
 			if (!params.continueSetup) throw refuse(`Recovered ${state.address}. Run this exact command with --continue-setup to explicitly obtain one pending-only invitation.`);
 			state = {
 				...state,
@@ -4916,13 +5598,13 @@ async function enrollAgent(params) {
 					body: JSON.stringify({ pending_only: true })
 				});
 				if (response.status !== 200) {
-					if (plainRecord(plainRecord(await boundedJson(response, "pending setup continuation"))?.error)?.code === "connection_already_claimed") throw refuse("This agent was claimed before Continue setup. Its credential was not changed. Inspect it in the app.");
+					if (plainRecord(plainRecord(await boundedJson(response, "pending setup continuation"))?.error)?.code === "connection_already_claimed") throw refuse(reconnectStep(connection.address, "was claimed before Continue setup and its credential was not changed"));
 					throw new Error();
 				}
 				payload = await boundedJson(response);
 			} catch (error) {
 				if (error instanceof AgentConnectionSetupError) throw error;
-				throw refuse("Continue setup has an uncertain outcome. Inspect the saved agent in the app; do not repeat it and invalidate another invitation.");
+				throw refuse(`Continue setup has an uncertain outcome, so it is not repeated automatically. ${stuckEnrollmentStep(connection.address)}`);
 			}
 		}
 		const invitation = invitationFrom(payload, state, (params.now ?? Date.now)());
@@ -4933,7 +5615,21 @@ async function enrollAgent(params) {
 			ownerAddress: invitation.ownerAddress
 		};
 		writeMailJson(path, state);
-		return finish(resolvedEnrollment(state), false, invitation.url);
+		track(state);
+		let current = null;
+		try {
+			current = loadCliCredentials(params.configDir);
+		} catch {
+			current = null;
+		}
+		log("setup_attempted", { code: current?.org_id === state.orgId && current.oauth_grant_id === state.grantId ? null : "login_changed" });
+		return await finish(resolvedEnrollment(state), false, invitation.url);
+	} catch (error) {
+		log("failed", {
+			code: failureCode(error),
+			detail: error instanceof AgentConnectionSetupError ? error.message : "Registration stopped on an unexpected error."
+		});
+		throw error;
 	} finally {
 		release();
 	}
@@ -5604,11 +6300,15 @@ async function registerSession(options) {
 		} catch {
 			credentials = null;
 		}
-		if (!credentials) return {
-			...known,
-			status: "not_logged_in",
-			detail: "No saved member login on this machine. Run `primitive signin`, then start the session again."
-		};
+		if (!credentials) {
+			const pending = unfinishedEnrollmentAddress(options.configDir, sessionId);
+			return {
+				...known,
+				...pending ? { address: pending } : {},
+				status: "not_logged_in",
+				detail: pending ? stuckEnrollmentStep(pending) : "No saved member login on this machine. Run `primitive signin`, then start the session again."
+			};
+		}
 		record = await updateSessionRecord(options.configDir, sessionId, (current) => current ?? newRecord("session-register", null));
 		if (!record) throw new Error("session record unavailable");
 		if (record.endedAt) return await ended(record);
@@ -6072,4 +6772,4 @@ async function runDetached(params) {
 	}
 }
 //#endregion
-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 };
+export { saveConnectionName as $, ContactPolicyReadRetryError as A, AddressNotesApiError as B, RECEIVER_MODES as C, upsertManagedBlock as Ct, registrationSummary as D, refreshOwnerMemberAddressPeriodically as Dt, failedSessionRegistration as E, addSessionReceiver as Et, canonicalContactSelector as F, contactAgentAddress as G, runAddressNotesRequest as H, AgentDisconnectError as I, agentInvitationHash as J, runContactRequest as K, claimOverRevokedSetup as L, NetworkAdmissionPendingError as M, createNotificationContactPolicy as N, registrationSummaryLine as O, withOwnerMemberAddress as Ot, evaluateContactPolicy as P, refusalAfterReplacement as Q, clearRevokedAddresses as R, runAgentConnect as S, readManagedFile as St, verificationReplySubmitted as T, readHookLauncherWarning as Tt, ContactsApiError as U, addressNoteTarget as V, contactAddress as W, readAgentInvitation as X, connectAgent as Y, receiverStatusCommand as Z, enrollmentResumes as _, samePath as _t, endSession as a, boundSessionProfiles as at, invitationProfileName as b, inspectManagedBlock as bt, pendingSessionDisconnects as c, describeSessionHookChange as ct, registerSession as d, ephemeralCliReason as dt, savedReceiver as et, retryPendingDisconnects as f, findOnPath as ft, enrollAgent as g, repairClaudeHooks as gt, staleSessionAgents as h, readClaudeSettings as ht, connectedProfilesForSession as i, recordHookMailCheck as it, NETWORK_ADMISSION_PENDING_RETRY_MS as j, waitForRegistrations as k, psProcessInfo as l, describeSessionHookItem as lt, runDetached as m, inspectClaudeHooks as mt, OMP_MAIN as n, releaseRegistrationsForProfile as nt, headlessClaudeRun as o, claudeConfigDir as ot, revokeStaleSessionAgents as p, hasMachineSessionHooks as pt, agentConnectionStatus as q, agentConnectionState as r, installClaudeWakeHook as rt, machine_session_exports as s, currentCliLocation as st, HOOK_END_GRACE_MS as t, MACHINE_RUNTIMES as tt, readClaudeHookInput as u, ensureHookLauncher as ut, connectWarnings as v, writeClaudeSettings as vt, externalReceivingState as w, writeManagedFile as wt, pollCheckCommand as x, jsonIndentation as xt, defaultAgentProfileName as y, MachineFileError as yt, disconnectAgent as z };