primcli 1.48.0 → 1.50.0

package/dist/{machine-session-BaJ1Xmdm.js → machine-session-CY0j2r7S.js}

@@ -1,18 +1,334 @@
 import { n as __exportAll } from "./rolldown-runtime-CNZpIYwj.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-DGrZCUfw.js";
-import { $t as getAgentContactPolicy, Dn as listSentEmails, Fn as putContact, Gn as sendEmail, Gt as deleteAgentContact, Hn as searchEmails, Kt as deleteContact, Nn as putAgentContact, Pn as putAgentContactPolicy, Pt as refreshStoredCliCredentials, _n as listContacts, bn as listDomains, en as getContact, hn as listAgentContacts, in as getEmail } from "./api-command-DzQ8KxD9.js";
+import { An as listDomains, Dn as listContacts, Gn as putContact, H as defaultConnectionName, Ln as listSentEmails, Qn as searchEmails, Tn as listAgentContacts, Un as putAgentContact, Wn as putAgentContactPolicy, Wt as refreshStoredCliCredentials, ln as getAgentContactPolicy, mn as getEmail, nn as deleteContact, tn as deleteAgentContact, tr as sendEmail, un as getContact } from "./api-command-Ci6eyQ8d.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-SPPcis9g.js";
-import { a as readBundledConnectSkill, h as connectNativeSession, m as SESSION_UUID, n as detectAgentRuntime, o as notificationScope, r as installConnectSkill, u as NotificationRetryError } from "./connect-skill-DHPc9dVN.js";
-import { l as stopBackgroundListen, r as backgroundListenStatus } from "./listen-background-CyLc8VBn.js";
-import { t as readSharedMailOwner } from "./shared-mail-watch-BUfUaq6j.js";
-import { a as scopedChatSenderTrust } from "./scoped-chat-DhxtuNXs.js";
-import { accessSync, chmodSync, closeSync, constants, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { a as scopedChatSenderTrust } from "./scoped-chat-DSLrmgWQ.js";
+import { _ as NativeSessionDisconnectedError, a as readBundledConnectSkill, g as defaultSessionSocket, h as connectNativeSession, m as SESSION_UUID, n as detectAgentRuntime, o as notificationScope, r as installConnectSkill, u as NotificationRetryError } from "./connect-skill-xtf3Q5IF.js";
+import { l as stopBackgroundListen, r as backgroundListenStatus } from "./listen-background-CMfxkeVP.js";
+import { t as readSharedMailOwner } from "./shared-mail-watch-CWhpfJ0N.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";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
+import { createConnection } from "node:net";
+//#region src/oclif/owner-member-address.ts
+const REFRESH_TIMEOUT_MS = 5e3;
+const MAX_RESPONSE_BYTES$1 = 64 * 1024;
+/** Reads at most MAX_RESPONSE_BYTES, stopping as soon as the body exceeds it. */
+async function boundedText(response) {
+	const reader = response.body?.getReader();
+	if (!reader) return null;
+	const chunks = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const part = await reader.read();
+			if (part.done) break;
+			size += part.value.byteLength;
+			if (size > MAX_RESPONSE_BYTES$1) return null;
+			chunks.push(part.value);
+		}
+		return Buffer.concat(chunks).toString("utf8");
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+}
+/**
+* Reads the owner's personal mailbox from the connection's own record
+* (GET /agent-connections/me) and saves it in the profile, so an agent paired
+* before the server reported it, or before its owner set one up, learns where
+* to send reports. Best effort: any failure keeps the saved value. Returns the
+* address to report to, or null when there is none or it is unknown.
+*/
+async function refreshOwnerMemberAddress(params) {
+	const profile = loadConnectedAgentProfile(params.configDir, params.profileName);
+	if (!profile) return null;
+	const saved = profile.owner_member_address ?? null;
+	try {
+		const response = await (params.fetch ?? fetch)(`${profile.api_base_url}/agent-connections/me`, {
+			headers: { authorization: `Bearer ${profile.api_key}` },
+			redirect: "error",
+			signal: AbortSignal.timeout(params.timeoutMs ?? REFRESH_TIMEOUT_MS)
+		});
+		if (!response.ok) return saved;
+		const text = await boundedText(response);
+		if (text === null) return saved;
+		const body = JSON.parse(text);
+		const connection = body?.data?.connection;
+		if (body?.success !== true || !connection || !Object.hasOwn(connection, "owner_member_address") || mailAddress(connection.address) !== profile.agent_address || mailAddress(connection.owner_address) !== profile.owner_address) return saved;
+		const current = parseOwnerMemberAddress(connection.owner_member_address, profile.owner_address, profile.agent_address);
+		const latest = loadConnectedAgentProfile(params.configDir, params.profileName);
+		if (!latest || latest.api_key !== profile.api_key || latest.agent_address !== profile.agent_address || latest.owner_address !== profile.owner_address) return latest?.owner_member_address ?? null;
+		if (latest.owner_member_address !== current) saveConnectedAgentProfile(params.configDir, params.profileName, {
+			...latest,
+			owner_member_address: current
+		});
+		return current;
+	} catch {
+		return saved;
+	}
+}
+const REFRESH_STAMP_FILE = "owner-member-refresh.json";
+function lastRefreshAttempt(path) {
+	try {
+		const saved = readMailJson(path);
+		if (saved?.version !== 1 || typeof saved.at !== "string") return null;
+		const at = Date.parse(saved.at);
+		return Number.isFinite(at) ? at : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* refreshOwnerMemberAddress for routine paths (each mail check, each start of
+* a wake receiver): reads the connection's record at most once per interval,
+* so an owner who sets up a personal address after pairing is learned without
+* a reconnect. Between reads it returns the saved value without a request.
+* The time of each attempt is saved with the profile, so a failing server is
+* not asked again on every turn. Never throws.
+*/
+async function refreshOwnerMemberAddressPeriodically(params) {
+	let saved = null;
+	let release;
+	try {
+		const profile = loadConnectedAgentProfile(params.configDir, params.profileName);
+		if (!profile) return null;
+		saved = profile.owner_member_address ?? null;
+		const directory = agentProfileDirectory(params.configDir, params.profileName);
+		try {
+			release = acquireListenLock(directory, "owner-member-refresh");
+		} catch {
+			return saved;
+		}
+		const now = (params.now ?? Date.now)();
+		const stamp = join(directory, REFRESH_STAMP_FILE);
+		const last = lastRefreshAttempt(stamp);
+		if (last !== null && last <= now && now - last < (params.intervalMs ?? 6e5)) return saved;
+		try {
+			writeMailJson(stamp, {
+				version: 1,
+				at: new Date(now).toISOString()
+			});
+		} catch {}
+		return await refreshOwnerMemberAddress(params);
+	} catch {
+		return saved;
+	} finally {
+		release?.();
+	}
+}
+/** One sentence telling the agent where its reports go. */
+function ownerReportGuidance(identity) {
+	return identity.ownerMemberAddress ? `Send reports and questions to your owner's personal address ${identity.ownerMemberAddress}; ${identity.ownerAddress} is the setup and presence control address and nobody reads it.` : `No personal owner address is known, so reply to the member who wrote to you; never send reports to ${identity.ownerAddress}, the setup and presence control address.`;
+}
+/**
+* Adds the current personal address and report guidance to a result that
+* carries a connected identity, refreshing the saved profile first.
+*/
+async function withOwnerMemberAddress(result, params) {
+	const saved = loadConnectedAgentProfile(params.configDir, result.identity.profileName);
+	const ownerMemberAddress = params.onlyIfUnknown && typeof saved?.owner_member_address === "string" ? saved.owner_member_address : await refreshOwnerMemberAddress({
+		configDir: params.configDir,
+		profileName: result.identity.profileName,
+		fetch: params.fetch
+	});
+	const identity = {
+		...result.identity,
+		ownerMemberAddress
+	};
+	return {
+		...result,
+		identity,
+		ownerReportGuidance: ownerReportGuidance(identity)
+	};
+}
+//#endregion
+//#region src/oclif/hook-launcher.ts
+/**
+* Claude Code hooks run Primitive through a small POSIX launcher instead of a
+* pinned Node binary. A version manager (nvm, n, asdf) or a package-runner
+* cache (npx) can remove the Node or CLI files a hook names at any time; the
+* launcher then falls back to another Node and another copy of the CLI, and
+* when it finds no Node at all it records a warning instead of failing
+* silently. Windows keeps hooks that name Node directly.
+*/
+const HOOK_LAUNCHER_MARKER = "primitive-hook-launcher-v1";
+function hookLauncherSupported(platform = process.platform) {
+	return platform !== "win32";
+}
+function hookLauncherPath(configDir) {
+	return join(resolve(configDir), "bin", "primitive-node");
+}
+/** Written by the launcher when no Node (or no CLI copy) can be found. */
+function hookLauncherWarningPath(configDir) {
+	return join(resolve(configDir), "bin", "primitive-node.warning");
+}
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+const NO_NODE_WARNING = `Primitive wake hooks could not find Node.js 22 or later, so new mail will not wake this session. Install it, then run \`primitive agent connect --resume\` for each connected session or \`primitive machine doctor --fix\`.`;
+const NO_CLI_WARNING = "Primitive wake hooks could not find the Primitive CLI (its package cache was removed and it could not be fetched again), so new mail will not wake this session. Run `npm install -g primitive`, then `primitive machine doctor --fix`.";
+/** The read version of the CLI package whose bin/run.js is `entry`. */
+function cliPackageVersion(entry) {
+	try {
+		const manifest = JSON.parse(readFileSync(join(dirname(entry), "..", "package.json"), "utf8"));
+		return manifest.name === "primitive" && typeof manifest.version === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version) ? manifest.version : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The launcher script. It takes the hook's own arguments (the script to run,
+* then its arguments) and:
+*
+* 1. runs the pinned Node when it still exists, else the first `node` on
+*    PATH, else a sibling version of the pinned one, else a common install
+*    location;
+* 2. when the script the hook names is gone (a cleaned npx cache), runs the
+*    same script from the `primitive` on PATH, or from
+*    `npx -y -p primitive@<version>`;
+* 3. when neither can be found, writes a one-line warning, shows it once to
+*    the session through the PostToolUse hook, and exits 0 so Claude Code is
+*    never blocked.
+*/
+function hookLauncherScript(params) {
+	const warning = hookLauncherWarningPath(params.configDir);
+	const common = params.commonLocations === false ? "" : ` "$nvm_root/current/bin/node" "$nvm_root"/versions/node/*/bin/node /opt/homebrew/bin/node /usr/local/bin/node /usr/bin/node "$HOME/.volta/bin/node"`;
+	return `#!/bin/sh
+# ${HOOK_LAUNCHER_MARKER}
+# Written by the Primitive CLI. Claude Code hooks run Primitive through this
+# file so they keep working when the Node.js or CLI copy they were installed
+# with is removed. \`primitive agent connect --resume\` and
+# \`primitive machine doctor --fix\` rewrite it.
+pinned_node=${shellQuote(params.node)}
+pinned_version=${shellQuote(params.version ?? "")}
+warning_file=${shellQuote(warning)}
+
+# Record why hooks cannot run, show it once to each session through its
+# PostToolUse hook (the session id is the hook's sixth argument), and exit 0
+# so Claude Code is never blocked.
+fail_open() {
+  mkdir -p "\${warning_file%/*}" 2>/dev/null
+  printf '%s\\n' "$1" > "$warning_file" 2>/dev/null
+  case "\${hook_script##*/}" in
+    claude-pending-mail.mjs)
+      session=$hook_session
+      case "$session" in
+        '' | *[!0-9A-Fa-f-]*) session=unknown ;;
+      esac
+      # mkdir is atomic, so of several hooks running at once only one
+      # shows the warning.
+      if mkdir "$warning_file.shown-$session" 2>/dev/null; then
+        printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}' "$1"
+      fi
+      ;;
+  esac
+  exit 0
+}
+
+# A fallback Node must be new enough to run this CLI.
+supported() {
+  [ -x "$1" ] && "$1" -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 22 ? 0 : 1)' >/dev/null 2>&1
+}
+
+pick_node() {
+  if [ -x "$pinned_node" ]; then node=$pinned_node; return 0; fi
+  node=$(command -v node 2>/dev/null)
+  if [ -n "$node" ] && supported "$node"; then return 0; fi
+  versions=\${pinned_node%/*/bin/node}
+  nvm_root=\${NVM_DIR:-$HOME/.nvm}
+  for node in "$versions"/*/bin/node${common}; do
+    if supported "$node"; then return 0; fi
+  done
+  node=
+  return 1
+}
+
+package_dir() {
+  "$node" -e 'process.stdout.write(require("path").dirname(require("fs").realpathSync(process.argv[1])))' "$1" 2>/dev/null
+}
+
+# A CLI copy whose bin directory holds both the hook script and run.js.
+complete_copy() {
+  [ -n "$1" ] && [ -f "$1/$name" ] && [ -f "$1/run.js" ]
+}
+
+hook_script=$1
+hook_session=$6
+pick_node || fail_open ${shellQuote(NO_NODE_WARNING)}
+PATH=\${node%/*}:$PATH
+export PATH
+
+# The hook names a script and, after it, the CLI's run.js. When either is
+# gone (a cleaned npx cache), both come from another copy of the CLI.
+need_cli=
+if [ $# -ge 1 ] && [ ! -f "$1" ]; then need_cli=1; fi
+if [ $# -ge 2 ] && [ "\${2##*/}" = run.js ] && [ ! -f "$2" ]; then need_cli=1; fi
+if [ -n "$need_cli" ]; then
+  name=\${1##*/}
+  dir=
+  if [ -f "$1" ] && complete_copy "\${1%/*}"; then dir=\${1%/*}; fi
+  if ! complete_copy "$dir"; then
+    found=$(command -v primitive 2>/dev/null)
+    if [ -n "$found" ]; then dir=$(package_dir "$found"); fi
+  fi
+  if ! complete_copy "$dir" && [ -n "$pinned_version" ]; then
+    npx=\${node%/*}/npx
+    [ -x "$npx" ] || npx=$(command -v npx 2>/dev/null)
+    if [ -n "$npx" ]; then
+      found=$("$npx" -y -p "primitive@$pinned_version" -c 'command -v primitive' 2>/dev/null | tail -n 1)
+      if [ -n "$found" ]; then dir=$(package_dir "$found"); fi
+    fi
+  fi
+  complete_copy "$dir" || fail_open ${shellQuote(NO_CLI_WARNING)}
+  shift
+  if [ $# -ge 1 ] && [ "\${1##*/}" = run.js ] && [ ! -f "$1" ]; then
+    shift
+    set -- "$dir/$name" "$dir/run.js" "$@"
+  else
+    set -- "$dir/$name" "$@"
+  fi
+fi
+
+if [ -f "$warning_file" ]; then rm -rf "$warning_file" "$warning_file".shown-* 2>/dev/null; fi
+exec "$node" "$@"
+`;
+}
+/**
+* Write the launcher when its content differs, atomically and executable.
+* Returns true when the file changed. Throws when it cannot be written.
+*/
+function writeHookLauncher(path, content) {
+	try {
+		if (readFileSync(path, "utf8") === content) return false;
+	} catch {}
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, content, { mode: 493 });
+		chmodSync(temporary, 493);
+		renameSync(temporary, path);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+	return true;
+}
+/** The warning the launcher last wrote, or null when it found what it needed. */
+function readHookLauncherWarning(configDir) {
+	try {
+		return readFileSync(hookLauncherWarningPath(configDir), "utf8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/oclif/machine-files.ts
 /** Hand-edited files larger than this are reported, never rewritten. */
 const MAX_MANAGED_FILE_BYTES = 1048576;
@@ -296,20 +612,39 @@ function stableNodePath(env, execPath = process.execPath) {
 	if (onPath && isAbsolute(onPath) && onPath !== execPath && samePath(onPath, execPath)) return onPath;
 	return execPath;
 }
-/** Locate the running CLI. Null when its files are not where a package install puts them. */
-function currentCliLocation(entryArg, env, execPath = process.execPath) {
+/**
+* Locate the running CLI. Null when its files are not where a package install
+* puts them. With a config directory, Claude hooks run through the hook
+* launcher in it (except on Windows).
+*/
+function currentCliLocation(entryArg, env, execPath = process.execPath, options = {}) {
 	const entry = realpathOrNull(entryArg);
 	if (!entry) return null;
 	const wake = realpathOrNull(join(dirname(entry), "claude-wake.mjs"));
 	const pending = realpathOrNull(join(dirname(entry), "claude-pending-mail.mjs"));
 	if (!wake || !pending) return null;
+	const runtimeNode = stableNodePath(env, execPath);
+	const launcher = options.configDir !== void 0 && hookLauncherSupported(options.platform) ? {
+		path: hookLauncherPath(options.configDir),
+		content: hookLauncherScript({
+			node: runtimeNode,
+			version: cliPackageVersion(entry),
+			configDir: options.configDir
+		})
+	} : null;
 	return {
-		node: stableNodePath(env, execPath),
+		node: launcher?.path ?? runtimeNode,
+		runtimeNode,
+		launcher,
 		entry,
 		wake,
 		pending
 	};
 }
+/** Write the hook launcher a CLI location names. True when it changed. */
+function ensureHookLauncher(cli) {
+	return cli.launcher ? writeHookLauncher(cli.launcher.path, cli.launcher.content) : false;
+}
 /** Package-runner caches are cleaned up behind the user's back. */
 function ephemeralCliReason(entry) {
 	if (/[\\/]_npx[\\/]/.test(entry)) return "an npx cache";
@@ -438,6 +773,17 @@ function isGlobalManaged(hook, spec) {
 	const args = hook.args;
 	return args.length === 6 && typeof args[0] === "string" && args[1] === "agent" && args[2] === spec.subcommand && args[3] === "--runtime" && args[4] === "claude" && args[5] === "--hook";
 }
+/**
+* Whether settings carry either machine-wide session hook (SessionStart
+* session-register or SessionEnd session-end), from any CLI path or version.
+*/
+function hasMachineSessionHooks(settings) {
+	const hooks = record$2(settings.hooks) ? settings.hooks : {};
+	return Object.values(GLOBAL_HOOKS).some((spec) => {
+		const entries = eventEntries(hooks, spec.event);
+		return entries !== "invalid" && entries.some((entry) => record$2(entry) && Array.isArray(entry.hooks) && entry.hooks.some((hook) => isGlobalManaged(hook, spec)));
+	});
+}
 function globalHookArgs(cli, spec) {
 	return [
 		cli.entry,
@@ -480,7 +826,7 @@ 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) && 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$1 : WAKE_MARKER) && (node === null || samePath(hook.command, node));
 	}));
 }
 /** A per-session receive hook written by `agent connect` or `agent enroll`, any version. */
@@ -688,9 +1034,13 @@ function heldSessionProfiles(hooks, bound, restore) {
 	}
 	return held;
 }
-/** Receive hooks each bound profile should have and does not. */
-function missingSessionHooks(hooks, bound, node) {
-	return bound.flatMap((item) => SESSION_EVENTS.filter((event) => !hasSessionReceiveHook(hooks, event, item, node)).map((event) => ({
+/**
+* Receive hooks each bound profile has in no form at all. A hook that exists
+* but names an old Node or CLI path is outdated, not missing, so one hook is
+* never reported (or repaired) as both.
+*/
+function missingSessionHooks(hooks, bound) {
+	return bound.flatMap((item) => SESSION_EVENTS.filter((event) => !hasSessionReceiveHook(hooks, event, item, null)).map((event) => ({
 		event,
 		bound: item
 	})));
@@ -808,7 +1158,7 @@ function inspectClaudeHooks(settings, context) {
 	};
 	const verdicts = judgeSessionHooks(hooks, context.cli, bound);
 	for (const verdict of verdicts.values()) counts[verdict]++;
-	const missingHooks = missingSessionHooks(hooks, bound, context.cli?.node ?? process.execPath);
+	const missingHooks = missingSessionHooks(hooks, bound);
 	const missing = missingHooks.length;
 	const items = sessionHookItems(hooks, verdicts, missingHooks);
 	const problems = [
@@ -936,7 +1286,7 @@ function repairClaudeHooks(settings, context, checks, options = {}) {
 					changed.add("claude.hook.stop");
 				}
 			}
-			if (cli) for (const missing of missingSessionHooks(hooks, bound, cli.node)) {
+			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;
@@ -1023,12 +1373,12 @@ function claudeWakeHookStatus(options) {
 			address: agentAddress,
 			session: sessionId
 		};
-		const node = stableNodePath(env);
+		const commands = [...hookLauncherSupported(options.platform) ? [hookLauncherPath(configDir)] : [], stableNodePath(env)];
 		const installed = [
 			"Stop",
 			"SessionStart",
 			"PostToolUse"
-		].every((event) => hasSessionReceiveHook(hooks, event, target, node));
+		].every((event) => commands.some((node) => hasSessionReceiveHook(hooks, event, target, node)));
 		const lastFiredAt = recordedAt(readMailJson(join(agentProfileDirectory(configDir, profileName), `pending-mail-${sessionId}.fired.json`)));
 		const lastMailCheckAt = recordedAt(readMailJson(hookMailCheckPath(configDir, profileName, sessionId)));
 		const now = options.now ?? Date.now();
@@ -1099,17 +1449,27 @@ function editClaudeSettings(claudeDir, edit) {
 /** Add exact-session fail-open receiving hooks while preserving unrelated settings. */
 function installClaudeWakeHook(options) {
 	try {
-		const cliPath = realpathSync(options.cliPath);
-		const wrapperPath = realpathSync(join(dirname(cliPath), "claude-wake.mjs"));
-		const pendingPath = realpathSync(join(dirname(cliPath), "claude-pending-mail.mjs"));
 		const configDir = resolve(options.configDir);
+		const env = options.env ?? process.env;
+		const cli = currentCliLocation(options.cliPath, env, process.execPath, {
+			configDir,
+			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";
 		const sessionId = options.sessionId.toLowerCase();
-		const env = options.env ?? process.env;
 		const claudeDir = resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
-		const node = stableNodePath(env);
+		let node = cli.node;
+		try {
+			ensureHookLauncher(cli);
+		} catch {
+			node = cli.runtimeNode;
+		}
 		let held = false;
 		if (!editClaudeSettings(claudeDir, (settings) => {
 			const hooks = settings.hooks ?? {};
@@ -1273,8 +1633,121 @@ function uninstallClaudeWakeHook(options) {
 //#endregion
 //#region src/oclif/agent-connect.ts
 const MAX_INVITATION_BYTES = 4096;
-const MAX_RESPONSE_BYTES$1 = 32768;
+const MAX_RESPONSE_BYTES = 32768;
 const UNCERTAIN_CLAIM = "Setup did not complete safely. The invitation may have been consumed. Request a fresh invitation from the owner; do not retry this invitation.";
+const INVITATION_UNAVAILABLE = "This invitation was already used, has expired, or was revoked, so it cannot connect this agent. Ask the owner to copy a fresh setup instruction from the app. Nothing was changed on this machine.";
+const INVITATION_ATTEMPTED_HERE = "An earlier setup on this machine already submitted this invitation and did not finish, so it was not submitted again; it may already be used. Ask the owner to copy a fresh setup instruction from the app. Nothing was changed on this machine.";
+const INVITATION_INVALID = "Primitive rejected this invitation as invalid. Ask the owner to copy a fresh setup instruction from the app. Nothing was changed on this machine.";
+/**
+* The server answered the claim with a definite refusal, so nothing was
+* claimed and no credential exists. Unlike a lost or malformed response, it
+* is safe to discard every local trace of the attempt.
+*/
+var AgentInvitationRejectedError = class extends AgentConnectionSetupError {
+	constructor(message, reason) {
+		super(message);
+		this.reason = reason;
+	}
+};
+const NOTHING_CHANGED = "Nothing was changed on this machine.";
+/**
+* Restates a refusal that followed a replacement: the agent being replaced
+* was disconnected before the claim, so "nothing was changed" is not true.
+*/
+function refusalAfterReplacement(error, replaced) {
+	if (!(error instanceof AgentInvitationRejectedError) || !replaced.length) return error;
+	const names = replaced.map((row) => row.address).join(", ");
+	return new AgentInvitationRejectedError(error.message.replace(NOTHING_CHANGED, `The agent this was replacing (${names}) was already disconnected before the claim and stays disconnected.`), error.reason);
+}
+/** The error code of a refused claim, read without keeping the body. */
+async function claimErrorCode(response) {
+	try {
+		const body = await readClaimResponse(response);
+		return body?.success === false && typeof body.error?.code === "string" ? body.error.code : null;
+	} catch {
+		return null;
+	}
+}
+/** A definite refusal of the claim, or null when the outcome is uncertain. */
+async function definiteClaimRefusal(response) {
+	if (![
+		400,
+		409,
+		429
+	].includes(response.status)) return null;
+	const code = await claimErrorCode(response);
+	if (response.status === 409 && code === "connection_invitation_unavailable") return new AgentInvitationRejectedError(INVITATION_UNAVAILABLE, "invitation_unavailable");
+	if (response.status === 400 && code === "validation_error") return new AgentInvitationRejectedError(INVITATION_INVALID, "invitation_invalid");
+	if (response.status === 429 && code === "rate_limit_exceeded") {
+		const seconds = Number(response.headers.get("retry-after"));
+		return new AgentInvitationRejectedError(`Primitive is limiting connection attempts from this network. The invitation was not claimed; wait ${Number.isSafeInteger(seconds) && seconds > 0 && seconds <= 3600 ? `${seconds} seconds` : "a minute"} and rerun the same command with the same invitation. Nothing was changed on this machine.`, "rate_limited");
+	}
+	return null;
+}
+/** The message for an invitation another profile on this machine already claimed. */
+function invitationUsedHereMessage(address) {
+	return `This invitation was already used on this machine${address ? ` to connect ${address}` : ""} under another profile, so it cannot connect this agent. Ask the owner to copy a fresh setup instruction from the app. Nothing was changed on this machine.`;
+}
+/**
+* A local record says this invitation was submitted before. It is never
+* submitted again: the claim is one-use, and a second submission could not
+* recover a credential lost with an earlier response. The refusal names the
+* address when the earlier attempt finished, and is a definite local refusal
+* either way, so a caller may discard whatever it created for this run.
+*/
+function earlierAttemptRefusal(configDir, journal, invitationHash) {
+	const record = journal;
+	let address = null;
+	if (record?.status === "claimed" && typeof record.agent_address === "string") address = record.agent_address;
+	else if (typeof record?.profile_name === "string") try {
+		const earlier = loadConnectedAgentProfile(configDir, record.profile_name);
+		if (earlier?.invitation_hash === invitationHash) address = earlier.agent_address;
+	} catch {}
+	return address !== null || record?.status === "claimed" ? new AgentInvitationRejectedError(invitationUsedHereMessage(address), "invitation_used_here") : new AgentInvitationRejectedError(INVITATION_ATTEMPTED_HERE, "invitation_attempted_here");
+}
+/** Removes a directory only when it is empty. Best effort. */
+function removeEmptyDirectory(path) {
+	try {
+		rmdirSync(path);
+	} catch {}
+}
+const CONNECTION_NAME_FILE = "connection-name.json";
+/**
+* The display name this profile's claim reported, saved beside the profile
+* so a resumed setup can report it too. Undefined when none was saved.
+*/
+function savedConnectionName(configDir, profileName) {
+	try {
+		const saved = readMailJson(join(agentProfileDirectory(configDir, profileName), CONNECTION_NAME_FILE));
+		return saved?.version === 1 ? claimedConnectionName({ data: { connection: { name: saved.name } } }) : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Saves the connection's current display name beside its profile: from the
+* claim, and again after `agent rename`. Best effort: without it a resume
+* omits the name, as for a claim made by an older version.
+*/
+function saveConnectionName(configDir, profileName, name) {
+	try {
+		writeMailJson(join(agentProfileDirectory(configDir, profileName), CONNECTION_NAME_FILE), {
+			version: 1,
+			name
+		});
+	} catch {}
+}
+/** The display name a claim response reports, or undefined when unusable. */
+function claimedConnectionName(value) {
+	const name = value?.data?.connection?.name;
+	if (typeof name !== "string") return void 0;
+	const trimmed = name.trim();
+	const printable = Array.from(trimmed).every((character) => {
+		const code = character.charCodeAt(0);
+		return code >= 32 && !(code >= 127 && code <= 159) && code !== 8232 && code !== 8233;
+	});
+	return trimmed.length > 0 && trimmed.length <= 80 && printable ? trimmed : void 0;
+}
 /** The receiver a saved profile's setup record names. Offline. */
 function savedReceiver(configDir, profileName) {
 	try {
@@ -1434,7 +1907,7 @@ async function readClaimResponse(response) {
 			const part = await reader.read();
 			if (part.done) break;
 			size += part.value.byteLength;
-			if (size > MAX_RESPONSE_BYTES$1) throw new Error();
+			if (size > MAX_RESPONSE_BYTES) throw new Error();
 			chunks.push(part.value);
 		}
 		return JSON.parse(Buffer.concat(chunks).toString("utf8"));
@@ -1489,11 +1962,18 @@ async function connectAgent(params) {
 				identity: connectedAgentIdentity(profileName, existing)
 			};
 		}
-		privateMailDirectory(join(directory, "profiles"), true);
-		privateMailDirectory(agentProfileDirectory(params.configDir, profileName), true);
 		const journal = join(directory, "claims", `${invitationHash}.json`);
 		privateMailDirectory(join(directory, "claims"), true);
-		if (readMailJson(journal) !== null) throw new AgentConnectionSetupError(UNCERTAIN_CLAIM);
+		let earlier;
+		try {
+			earlier = readMailJson(journal);
+		} catch {
+			throw new AgentConnectionSetupError(UNCERTAIN_CLAIM);
+		}
+		if (earlier !== null) throw earlierAttemptRefusal(params.configDir, earlier, invitationHash);
+		privateMailDirectory(join(directory, "profiles"), true);
+		const profileDirectory = agentProfileDirectory(params.configDir, profileName);
+		privateMailDirectory(profileDirectory, true);
 		writeMailJson(journal, {
 			version: 1,
 			profile_name: profileName,
@@ -1514,16 +1994,37 @@ async function connectAgent(params) {
 				})
 			});
 			if (response.status !== 200) {
-				await response.body?.cancel();
-				throw new Error();
+				const refusal = await definiteClaimRefusal(response);
+				if (!refusal) {
+					await response.body?.cancel().catch(() => void 0);
+					throw new Error();
+				}
+				try {
+					removeMailFile(journal);
+				} catch {}
+				removeEmptyDirectory(profileDirectory);
+				throw refusal;
 			}
-			const profile = profileFromClaim(await readClaimResponse(response), invitation, invitationHash, params.now ?? Date.now);
+			const body = await readClaimResponse(response);
+			const profile = profileFromClaim(body, invitation, invitationHash, params.now ?? Date.now);
+			const name = claimedConnectionName(body);
 			saveConnectedAgentProfile(params.configDir, profileName, profile);
+			try {
+				writeMailJson(journal, {
+					version: 1,
+					profile_name: profileName,
+					status: "claimed",
+					agent_address: profile.agent_address
+				});
+			} catch {}
+			if (name !== void 0) saveConnectionName(params.configDir, profileName, name);
 			return {
 				status: "claimed",
-				identity: connectedAgentIdentity(profileName, profile)
+				identity: connectedAgentIdentity(profileName, profile),
+				...name === void 0 ? {} : { name }
 			};
-		} catch {
+		} catch (error) {
+			if (error instanceof AgentInvitationRejectedError) throw error;
 			throw new AgentConnectionSetupError(UNCERTAIN_CLAIM);
 		}
 	} finally {
@@ -2350,6 +2851,20 @@ const VERIFICATION_BACKOFF_MS = [
 	3e3,
 	5e3
 ];
+/**
+* Setup's receiving state for an external receiver: setup itself installs no
+* hooks, so the caller installs them and restates the outcome with
+* {@link externalReceivingState}.
+*/
+const EXTERNAL_HOOKS_PENDING = "hooks_pending";
+/**
+* The printed receiving state for an external receiver, from the hook
+* install outcome. `hooks_installed` is a finished setup: idle wake is only
+* proven by real mail, which `externalHook: "installed_unverified"` says.
+*/
+function externalReceivingState(hook) {
+	return hook === "installed_unverified" ? "hooks_installed" : hook === "unavailable" ? "hook_unavailable" : hook === "held_for_other_profile" ? "held_for_other_profile" : "pending_verification";
+}
 /** Both states mean the setup reply was accepted for sending. */
 function verificationReplySubmitted(state) {
 	return state === "reply_submitted" || state === "verified";
@@ -2697,10 +3212,12 @@ async function setupAgent(params) {
 	if ((receiverMode ?? "native") === "native" && params.session) try {
 		await dependencies.preflight(params.session);
 	} catch {
-		throw fail("This exact session is not available for native receiving. No invitation was claimed. Open a supported session and retry setup.");
+		throw fail("This exact session is not available for native receiving. No invitation was claimed. Open a supported session and retry setup, or rerun with --receiver poll, which needs no session socket.");
 	}
 	privateMailDirectory(directory, true);
 	const release = acquireListenLock(directory, "setup");
+	let discardStub = false;
+	let claimedName;
 	try {
 		const path = join(directory, "setup.json");
 		const value = readMailJson(path);
@@ -2712,6 +3229,7 @@ async function setupAgent(params) {
 			const invitation = parseAgentInvitation(params.invitation ?? "");
 			const hash = createHash("sha256").update(invitation.apiBaseUrl).update("\0").update(invitation.token).digest("hex");
 			if (state && state.invitationHash !== hash) throw fail(profileAlreadyConnectedMessage(profileName, loadConnectedAgentProfile(params.configDir, profileName)?.agent_address ?? null));
+			const created = !state;
 			if (!state) {
 				state = {
 					version: 1,
@@ -2726,13 +3244,25 @@ async function setupAgent(params) {
 				};
 				writeMailJson(path, state);
 			}
-			await connectAgent({
-				configDir: params.configDir,
-				profileName,
-				invitation: params.invitation ?? "",
-				fetch: params.fetch,
-				presence: true
-			});
+			try {
+				claimedName = (await connectAgent({
+					configDir: params.configDir,
+					profileName,
+					invitation: params.invitation ?? "",
+					fetch: params.fetch,
+					presence: true
+				})).name;
+			} catch (error) {
+				if (error instanceof AgentInvitationRejectedError && created) {
+					discardStub = true;
+					try {
+						removeMailFile(path);
+					} catch {
+						discardStub = false;
+					}
+				}
+				throw error;
+			}
 		}
 		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.");
@@ -2763,8 +3293,10 @@ async function setupAgent(params) {
 			"bounced",
 			"canceled"
 		].includes(state.receipt?.status ?? "") ? "reply_failed" : ["unknown", "wait_timeout"].includes(state.receipt?.status ?? "") ? "delivery_unknown" : "reply_submitted" : state?.phase === "sending" ? "send_unknown" : "challenge_pending";
+		claimedName ??= savedConnectionName(params.configDir, profileName);
 		const result = (receiving, ownerNotifications) => ({
 			identity: context.identity,
+			...claimedName === void 0 ? {} : { connectionName: claimedName },
 			sessionId: params.session ?? state?.session ?? null,
 			verification: {
 				state: confirmed && submittedState() === "reply_submitted" ? "verified" : submittedState(),
@@ -2817,93 +3349,13 @@ async function setupAgent(params) {
 			const check = await awaitVerification(context, dependencies, verificationTimeoutMs);
 			if (check.state === "verified") confirmed = { verifiedAt: check.verifiedAt };
 		}
-		return result(state.receiverMode === "external" ? "external_setup_required" : state.receiverMode === "poll" ? "poll" : healthy ? "healthy" : "not_ready", ownerNotifications);
+		return result(state.receiverMode === "external" ? EXTERNAL_HOOKS_PENDING : state.receiverMode === "poll" ? "poll" : healthy ? "healthy" : "not_ready", ownerNotifications);
 	} finally {
 		release();
+		if (discardStub) removeEmptyDirectory(directory);
 	}
 }
 //#endregion
-//#region src/oclif/owner-member-address.ts
-const REFRESH_TIMEOUT_MS = 5e3;
-const MAX_RESPONSE_BYTES = 64 * 1024;
-/** Reads at most MAX_RESPONSE_BYTES, stopping as soon as the body exceeds it. */
-async function boundedText(response) {
-	const reader = response.body?.getReader();
-	if (!reader) return null;
-	const chunks = [];
-	let size = 0;
-	try {
-		for (;;) {
-			const part = await reader.read();
-			if (part.done) break;
-			size += part.value.byteLength;
-			if (size > MAX_RESPONSE_BYTES) return null;
-			chunks.push(part.value);
-		}
-		return Buffer.concat(chunks).toString("utf8");
-	} finally {
-		await reader.cancel().catch(() => void 0);
-	}
-}
-/**
-* Reads the owner's personal mailbox from the connection's own record
-* (GET /agent-connections/me) and saves it in the profile, so an agent paired
-* before the server reported it, or before its owner set one up, learns where
-* to send reports. Best effort: any failure keeps the saved value. Returns the
-* address to report to, or null when there is none or it is unknown.
-*/
-async function refreshOwnerMemberAddress(params) {
-	const profile = loadConnectedAgentProfile(params.configDir, params.profileName);
-	if (!profile) return null;
-	const saved = profile.owner_member_address ?? null;
-	try {
-		const response = await (params.fetch ?? fetch)(`${profile.api_base_url}/agent-connections/me`, {
-			headers: { authorization: `Bearer ${profile.api_key}` },
-			redirect: "error",
-			signal: AbortSignal.timeout(params.timeoutMs ?? REFRESH_TIMEOUT_MS)
-		});
-		if (!response.ok) return saved;
-		const text = await boundedText(response);
-		if (text === null) return saved;
-		const body = JSON.parse(text);
-		const connection = body?.data?.connection;
-		if (body?.success !== true || !connection || !Object.hasOwn(connection, "owner_member_address") || mailAddress(connection.address) !== profile.agent_address || mailAddress(connection.owner_address) !== profile.owner_address) return saved;
-		const current = parseOwnerMemberAddress(connection.owner_member_address, profile.owner_address, profile.agent_address);
-		if (profile.owner_member_address !== current) saveConnectedAgentProfile(params.configDir, params.profileName, {
-			...profile,
-			owner_member_address: current
-		});
-		return current;
-	} catch {
-		return saved;
-	}
-}
-/** One sentence telling the agent where its reports go. */
-function ownerReportGuidance(identity) {
-	return identity.ownerMemberAddress ? `Send reports and questions to your owner's personal address ${identity.ownerMemberAddress}; ${identity.ownerAddress} is the setup and presence control address and nobody reads it.` : `No personal owner address is known, so reply to the member who wrote to you; never send reports to ${identity.ownerAddress}, the setup and presence control address.`;
-}
-/**
-* Adds the current personal address and report guidance to a result that
-* carries a connected identity, refreshing the saved profile first.
-*/
-async function withOwnerMemberAddress(result, params) {
-	const saved = loadConnectedAgentProfile(params.configDir, result.identity.profileName);
-	const ownerMemberAddress = params.onlyIfUnknown && typeof saved?.owner_member_address === "string" ? saved.owner_member_address : await refreshOwnerMemberAddress({
-		configDir: params.configDir,
-		profileName: result.identity.profileName,
-		fetch: params.fetch
-	});
-	const identity = {
-		...result.identity,
-		ownerMemberAddress
-	};
-	return {
-		...result,
-		identity,
-		ownerReportGuidance: ownerReportGuidance(identity)
-	};
-}
-//#endregion
 //#region src/oclif/agent-connect-flow.ts
 /** What this CLI version can do in one `agent connect --session` call. */
 const AGENT_CONNECT_CAPABILITIES = [
@@ -2921,6 +3373,51 @@ const MAX_NAME_LENGTH = 80;
 const MAX_INFO_LENGTH = 1e3;
 const MAIL_CHECK_WAIT_MS = 2e4;
 const PENDING_AGENT_INFO_FILE = "agent-info-pending.json";
+/**
+* The first Codex release whose shared app-server daemon exposes the local
+* session socket that native receiving connects to.
+*/
+const CODEX_NATIVE_MIN_VERSION = "0.158.0";
+/** The `major.minor.patch` triple in a `codex --version` line, if any. */
+function parseCodexVersion(text) {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+	return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+/** True when this Codex version has the session socket native receiving needs. */
+function codexSupportsNativeReceiving(version) {
+	const have = version.split(".").map(Number);
+	const need = CODEX_NATIVE_MIN_VERSION.split(".").map(Number);
+	for (let index = 0; index < need.length; index++) {
+		const a = have[index] ?? 0;
+		const b = need[index] ?? 0;
+		if (a !== b) return a > b;
+	}
+	return true;
+}
+/** True only when connecting to the socket is refused (nothing serves it). */
+function socketRefusesConnections(path, timeoutMs = 2e3) {
+	return new Promise((resolve) => {
+		const socket = createConnection({ path });
+		const done = (refused) => {
+			socket.destroy();
+			resolve(refused);
+		};
+		socket.setTimeout(timeoutMs, () => done(false));
+		socket.once("connect", () => done(false));
+		socket.once("error", (error) => done(error.code === "ECONNREFUSED"));
+	});
+}
+async function installedCodexVersion() {
+	try {
+		const { stdout } = await promisify(execFile)("codex", ["--version"], {
+			timeout: 3e3,
+			maxBuffer: 4096
+		});
+		return parseCodexVersion(String(stdout));
+	} catch {
+		return null;
+	}
+}
 function readPendingAgentInfo(path) {
 	try {
 		const saved = readMailJson(path);
@@ -2958,6 +3455,23 @@ function clearPendingAgentInfo(path) {
 		removeMailFile(path);
 	} catch {}
 }
+/**
+* Warns when the connection's own record says the owner has no personal
+* address in the organization. An unknown value (an older server, or a
+* failed read) warns nothing.
+*/
+function connectWarnings(configDir, profileName) {
+	let profile = null;
+	try {
+		profile = loadConnectedAgentProfile(configDir, profileName);
+	} catch {
+		return [];
+	}
+	return profile?.owner_member_address === null ? [{
+		kind: "owner_member_address_missing",
+		message: "Your owner has no personal address in this organization, so mail they send from their own address will not wake this agent and reports have nowhere to go. Ask them to open the Primitive app once (it sets one), or to run `primitive account provision-member-address --address <their address>` signed in as themselves."
+	}] : [];
+}
 function defaultAgentProfileName(session) {
 	return `session-${session.toLowerCase()}`;
 }
@@ -2995,6 +3509,9 @@ function defaults(options) {
 	return {
 		setupAgent,
 		nativePreflight: nativeSessionPreflight,
+		nativeSocketPresent: () => existsSync(defaultSessionSocket()),
+		nativeSocketRefuses: () => socketRefusesConnections(defaultSessionSocket()),
+		codexVersion: installedCodexVersion,
 		installClaudeWakeHook,
 		installSkill(runtime) {
 			return installConnectSkill({
@@ -3070,7 +3587,7 @@ async function runAgentConnect(options) {
 	const runtime = session ? detectAgentRuntime(session, env) : null;
 	const invitation = options.resume || session || options.profileName ? void 0 : await options.readInvitation();
 	const profileName = agentProfileName(options.profileName ?? (session ? defaultAgentProfileName(session) : invitationProfileName(invitation ?? "")));
-	const receiver = options.receiver ?? (options.resume ? savedSetup(options.configDir, profileName)?.receiverMode ?? null : null) ?? (!session ? "poll" : runtime === "claude" ? "external" : "native");
+	let receiver = options.receiver ?? (options.resume ? savedSetup(options.configDir, profileName)?.receiverMode ?? null : null) ?? (!session ? "poll" : runtime === "claude" ? "external" : "native");
 	if (receiver === "external" && env.CLAUDE_CODE_SESSION_ID?.trim().toLowerCase() !== session?.toLowerCase()) throw new AgentConnectionSetupError("External receiving requires this exact Claude session ID. No invitation was claimed.");
 	const agentInfo = agentInfoValue(options.name, options.info);
 	const skipped = [];
@@ -3105,15 +3622,31 @@ async function runAgentConnect(options) {
 		reason: skill.reason ?? skill.state
 	});
 	const startedAt = Date.now();
-	const setupInvitation = options.resume ? void 0 : invitation ?? await options.readInvitation();
-	if (options.beforeSetup) {
-		if (receiver === "native" && session) try {
-			await dependencies.nativePreflight(session);
-		} catch {
-			throw new AgentConnectionSetupError("This exact session is not available for native receiving. No invitation was claimed and nothing was changed. Open a supported session and retry setup.");
-		}
-		await options.beforeSetup();
+	const invocation = options.invocation ?? "primitive";
+	let fallback = null;
+	if (receiver === "native" && session && !options.resume) try {
+		await dependencies.nativePreflight(session);
+	} catch (error) {
+		const socketPresent = dependencies.nativeSocketPresent();
+		const socketDead = socketPresent && error instanceof NativeSessionDisconnectedError && await dependencies.nativeSocketRefuses();
+		const codexVersion = socketPresent && !socketDead || runtime === "claude" ? null : await dependencies.codexVersion();
+		const reason = socketDead ? "session_socket_unavailable" : socketPresent ? null : codexVersion !== null && !codexSupportsNativeReceiving(codexVersion) ? "codex_version_unsupported" : "session_socket_missing";
+		const why = reason === "codex_version_unsupported" ? `Native receiving needs Codex ${CODEX_NATIVE_MIN_VERSION} or newer; this machine has Codex ${codexVersion}.` : reason === "session_socket_unavailable" ? "The local Codex session socket exists but nothing accepted the connection, so its app-server is not running." : reason === "session_socket_missing" ? `Native receiving needs the local Codex session socket (Codex ${CODEX_NATIVE_MIN_VERSION} or newer with its shared app-server running), and none was found${codexVersion ? ` for Codex ${codexVersion}` : ""}.` : `The local session socket exists but did not accept session ${session}: it may not be loaded in this terminal, or the ID may not be this session's.`;
+		if (reason && options.receiver === void 0) {
+			receiver = "poll";
+			fallback = {
+				reason,
+				codexVersion,
+				detail: `${why} Connected with poll receiving instead: nothing wakes this session, so check for mail with receiving.checkCommand at the start of each turn and after sending.`
+			};
+		} else throw new AgentConnectionSetupError(`This exact session is not available for native receiving. ${why} No invitation was claimed and nothing was changed. To connect with poll receiving instead, pipe the same invitation to: ${invocation} agent connect --session ${session} --receiver poll --json`);
 	}
+	if (fallback) skipped.push({
+		step: "native_receiver",
+		reason: fallback.reason
+	});
+	const setupInvitation = options.resume ? void 0 : invitation ?? await options.readInvitation();
+	if (options.beforeSetup) await options.beforeSetup();
 	const result = await dependencies.setupAgent({
 		configDir: options.configDir,
 		profileName,
@@ -3129,6 +3662,7 @@ async function runAgentConnect(options) {
 		...result.identity,
 		ownerMemberAddress
 	};
+	const warnings = connectWarnings(options.configDir, result.identity.profileName);
 	let externalHook = null;
 	if (receiver === "external") if (verified) externalHook = dependencies.installClaudeWakeHook({
 		cliPath: options.cliPath,
@@ -3181,15 +3715,20 @@ async function runAgentConnect(options) {
 			reason: "already_present"
 		});
 	}
-	const invocation = options.invocation ?? "primitive";
 	const receiving = receiver === "external" ? {
 		...result.receiving,
+		state: externalReceivingState(externalHook),
 		mode: "external",
 		hook: externalHook
 	} : receiver === "poll" ? {
 		...result.receiving,
 		mode: "poll",
-		checkCommand: pollCheckCommand(invocation, result.identity.profileName)
+		checkCommand: pollCheckCommand(invocation, result.identity.profileName),
+		...fallback ? {
+			fallbackReason: fallback.reason,
+			fallbackDetail: fallback.detail,
+			codexVersion: fallback.codexVersion
+		} : {}
 	} : {
 		...result.receiving,
 		mode: "native",
@@ -3216,6 +3755,10 @@ async function runAgentConnect(options) {
 		ownerAddress: result.identity.ownerAddress,
 		ownerMemberAddress,
 		profile: result.identity.profileName,
+		...result.connectionName === void 0 ? {} : {
+			name: result.connectionName,
+			nameIsDefault: defaultConnectionName(result.connectionName, result.identity.agentAddress)
+		},
 		sessionId: session ?? null,
 		runtime,
 		cli: {
@@ -3228,6 +3771,7 @@ async function runAgentConnect(options) {
 		...result.ownerNotifications ? { ownerNotifications: result.ownerNotifications } : {},
 		agentInfo: agentInfoState,
 		skipped,
+		warnings,
 		selectProfile: `PRIMITIVE_AGENT_PROFILE=${result.identity.profileName}`,
 		resumeCommand,
 		guidance: `${result.guidance} ${ownerReportGuidance(identity)}`,
@@ -3236,45 +3780,6 @@ async function runAgentConnect(options) {
 	};
 }
 //#endregion
-//#region src/oclif/agent-identity-suggestions.ts
-/** The connection name enrollment uses when none is given. */
-const DEFAULT_ENROLL_NAME = "Coding agent";
-/** npx runs the CLI from its cache; print follow-up commands the same way. */
-function cliInvocation(entry) {
-	return entry && /[\\/]_npx[\\/]/.test(entry) ? "npx -y primitive@latest" : "primitive";
-}
-/**
-* Whether an enrollment's connection name is the fallback it chose by itself.
-* Session registration's `<runtime>-<repository>` names are reported by
-* registration, which knows the exact name it generated.
-*/
-function generatedAgentName(name) {
-	return name === DEFAULT_ENROLL_NAME;
-}
-/**
-* Additive result fields for a connect, enroll or session registration.
-* `nameIsDefault` appears only when it is known whether the connection name
-* is one this CLI generated. The runtime note is suggested once, after a
-* connection this run completed.
-*/
-function identitySuggestions(params) {
-	const prefix = `PRIMITIVE_AGENT_PROFILE=${params.profile} ${params.invocation}`;
-	const suggestions = [];
-	const nameIsDefault = params.nameIsDefault;
-	if (nameIsDefault) suggestions.push({
-		kind: "rename",
-		command: `${prefix} agent rename "<new name>"`
-	});
-	if (params.connectedNow) suggestions.push({
-		kind: "runtime_note",
-		command: `${prefix} agent runtime set`
-	});
-	return nameIsDefault === void 0 ? { suggestions } : {
-		nameIsDefault,
-		suggestions
-	};
-}
-//#endregion
 //#region src/oclif/agent-disconnect.ts
 var AgentDisconnectError = class extends Error {};
 function credentialDigest(profile) {
@@ -4751,4 +5256,4 @@ async function runDetached(params) {
 	}
 }
 //#endregion
-export { describeSessionHookItem as $, NetworkAdmissionPendingError as A, runContactRequest as B, pollCheckCommand as C, verificationReplySubmitted as D, RECEIVER_MODES as E, addressNoteTarget as F, receiverStatusCommand as G, agentInvitationHash as H, runAddressNotesRequest as I, recordHookMailCheck as J, savedReceiver as K, ContactsApiError as L, evaluateContactPolicy as M, canonicalContactSelector as N, ContactPolicyReadRetryError as O, AddressNotesApiError as P, describeSessionHookChange as Q, contactAddress as R, invitationProfileName as S, withOwnerMemberAddress as T, connectAgent as U, agentConnectionStatus as V, readAgentInvitation as W, claudeConfigDir as X, boundSessionProfiles as Y, currentCliLocation as Z, disconnectAgent as _, endSession as a, samePath as at, identitySuggestions as b, pendingSessionDisconnects as c, inspectManagedBlock as ct, registerSession as d, upsertManagedBlock as dt, ephemeralCliReason as et, retryPendingDisconnects as f, writeManagedFile as ft, AgentDisconnectError as g, enrollmentResumes as h, connectedProfilesForSession as i, repairClaudeHooks as it, createNotificationContactPolicy as j, NETWORK_ADMISSION_PENDING_RETRY_MS as k, psProcessInfo as l, jsonIndentation as lt, enrollAgent as m, OMP_MAIN as n, inspectClaudeHooks as nt, headlessClaudeRun as o, writeClaudeSettings as ot, runDetached as p, installClaudeWakeHook as q, agentConnectionState as r, readClaudeSettings as rt, machine_session_exports as s, MachineFileError as st, MACHINE_RUNTIMES as t, findOnPath as tt, readClaudeHookInput as u, readManagedFile as ut, cliInvocation as v, runAgentConnect as w, defaultAgentProfileName as x, generatedAgentName as y, contactAgentAddress as z };
+export { describeSessionHookItem as $, evaluateContactPolicy as A, agentInvitationHash as B, RECEIVER_MODES as C, NETWORK_ADMISSION_PENDING_RETRY_MS as D, ContactPolicyReadRetryError as E, ContactsApiError as F, saveConnectionName as G, readAgentInvitation as H, contactAddress as I, recordHookMailCheck as J, savedReceiver as K, contactAgentAddress as L, AddressNotesApiError as M, addressNoteTarget as N, NetworkAdmissionPendingError as O, runAddressNotesRequest as P, describeSessionHookChange as Q, runContactRequest as R, runAgentConnect as S, verificationReplySubmitted as T, receiverStatusCommand as U, connectAgent as V, refusalAfterReplacement as W, claudeConfigDir as X, boundSessionProfiles as Y, currentCliLocation as Z, disconnectAgent as _, withOwnerMemberAddress as _t, endSession as a, readClaudeSettings as at, invitationProfileName as b, pendingSessionDisconnects as c, writeClaudeSettings as ct, registerSession as d, jsonIndentation as dt, ensureHookLauncher as et, retryPendingDisconnects as f, readManagedFile as ft, AgentDisconnectError as g, refreshOwnerMemberAddressPeriodically as gt, enrollmentResumes as h, readHookLauncherWarning as ht, connectedProfilesForSession as i, inspectClaudeHooks as it, canonicalContactSelector as j, createNotificationContactPolicy as k, psProcessInfo as l, MachineFileError as lt, enrollAgent as m, writeManagedFile as mt, OMP_MAIN as n, findOnPath as nt, headlessClaudeRun as o, repairClaudeHooks as ot, runDetached as p, upsertManagedBlock as pt, installClaudeWakeHook as q, agentConnectionState as r, hasMachineSessionHooks as rt, machine_session_exports as s, samePath as st, MACHINE_RUNTIMES as t, ephemeralCliReason as tt, readClaudeHookInput as u, inspectManagedBlock as ut, connectWarnings as v, externalReceivingState as w, pollCheckCommand as x, defaultAgentProfileName as y, agentConnectionStatus as z };