primcli 1.39.0 → 1.40.0

package/README.md

@@ -862,6 +862,25 @@ choices when those options are omitted, and refuses only an option that
 conflicts with them, naming it. Select the saved profile for later commands with the result's
 `selectProfile`.
 
+A runtime with no local session ID or hooks, such as a cloud-hosted session
+whose commands run in a separate sandbox, connects with the same command and no
+`--session` (an empty `--session` is treated the same way). It claims and
+verifies the invitation normally and selects `--receiver poll`: nothing is
+installed, the profile defaults to `connection-<invitation hash prefix>`, and
+the result's `receiving.checkCommand` checks for new mail. The agent runs it at
+the start of each turn and after it sends:
+
+```sh
+npx -y primitive@latest agent connect --name Research --info "Reviews pull requests" --json < private-invitation.txt
+PRIMITIVE_AGENT_PROFILE=connection-0123456789ab primitive agent check-mail --json
+```
+
+`agent check-mail` prints the email IDs, senders and threads that arrived since
+the profile's previous check (never subjects or bodies), leaving out fyi
+acknowledgements, muted threads, and the setup and presence mail from the
+connection's control address. Its position advances only after the result is
+printed, so an interrupted check repeats mail rather than losing it.
+
 Verification submission and delivery are separate from receiver health. A queued
 verification reply is accepted for delivery. Do not claim again or resend because
 setup was interrupted. The CLI preserves its private recovery state.

package/dist/oclif/index.js

@@ -34983,6 +34983,139 @@ function isMemoryJsonValue(value, seen = /* @__PURE__ */ new Set()) {
 	}
 }
 //#endregion
+//#region src/oclif/agent-mail-check.ts
+/**
+* One check for mail that arrived since this profile's previous check. It is
+* the receiver for runtimes that nothing can wake (poll receiving): the agent
+* runs it at the start of each turn and after it sends.
+*
+* It tails `GET /emails?since=<cursor>`, which returns mail newer than the
+* cursor oldest first, without mail marked fyi (acknowledgements) or in
+* threads this address muted. The first check starts before the address's
+* first email. The cursor is saved privately per profile, only after the
+* result was handed to `emit`, so a failed or interrupted check repeats mail
+* rather than losing it. Reads also show this address's receiver as live.
+*/
+const CURSOR_FILE = "mail-check.json";
+var MailCheckApiError = class extends Error {
+	constructor(payload) {
+		super("The mail check request failed.");
+		this.payload = payload;
+	}
+};
+function readCursor(path) {
+	try {
+		const saved = readMailJson(path);
+		if (saved && typeof saved === "object" && !Array.isArray(saved) && saved.version === 1) {
+			const cursor = saved.cursor;
+			if (typeof cursor === "string" && cursor.length > 0) return cursor;
+		}
+	} catch {}
+	return null;
+}
+/** Setup challenges and presence probes come from the control address. */
+function isControlMail(email, identity) {
+	return email.presence_control !== void 0 || email.sender.trim().toLowerCase() === identity.ownerAddress.trim().toLowerCase();
+}
+async function checkAgentMail(options) {
+	const { identity } = options;
+	const directory = agentProfileDirectory(options.configDir, identity.profileName);
+	privateMailDirectory(directory, true);
+	const release = acquireListenLock(directory, "mail-check");
+	try {
+		const path = join(directory, CURSOR_FILE);
+		const saved = readCursor(path);
+		let cursor = saved;
+		const emails = [];
+		let controlSkipped = 0;
+		let more = false;
+		const maxPages = options.maxPages ?? 5;
+		for (let page = 0; page < maxPages; page++) {
+			const query = {
+				since: cursor ?? "start",
+				limit: 100,
+				exclude_fyi: "true",
+				exclude_muted: "true"
+			};
+			const result = await listEmails({
+				client: options.client.client,
+				query,
+				responseStyle: "fields"
+			});
+			if (result.error || !result.data) throw new MailCheckApiError(result.error);
+			const rows = result.data.data ?? [];
+			for (const row of rows) if (isControlMail(row, identity)) controlSkipped++;
+			else emails.push({
+				id: row.id,
+				received_at: row.received_at,
+				sender: row.sender,
+				thread_id: row.thread_id ?? null
+			});
+			const next = result.data.meta?.cursor ?? null;
+			if (rows.length === 0 || !next) break;
+			cursor = next;
+			more = page === maxPages - 1;
+		}
+		const output = {
+			outcome: emails.length > 0 ? "mail" : "empty",
+			emails,
+			more,
+			control_skipped: controlSkipped,
+			read_command: `PRIMITIVE_AGENT_PROFILE=${identity.profileName} ${options.invocation ?? "primitive"} emails get --id <id> --brief`
+		};
+		options.emit(output);
+		if (cursor && cursor !== saved) writeMailJson(path, {
+			version: 1,
+			cursor
+		});
+		return output;
+	} finally {
+		release();
+	}
+}
+//#endregion
+//#region src/oclif/commands/agent-check-mail.ts
+/** npx runs the CLI from its cache; print follow-up commands the same way. */
+function invocation$2(entry) {
+	return entry && /[\\/]_npx[\\/]/.test(entry) ? "npx -y primitive@latest" : "primitive";
+}
+var AgentCheckMailCommand = class AgentCheckMailCommand extends Command {
+	static summary = "Check a connected agent's mail since its last check";
+	static description = `Print the mail that reached the selected connected agent profile since its previous check, oldest first, once, without waiting. This is how an agent connected with poll receiving (no local session ID or hooks, so nothing can wake it) receives mail: run it at the start of each turn and after sending, then read each email with \`primitive emails get --id <id> --brief\`.
+
+Acknowledgements marked fyi and mail in muted threads are left out. Setup and presence mail from the connection's control address is handled by the CLI and only counted. The position is saved privately with the profile and moves forward only after mail was read, so mail is reported again rather than lost when a check fails or is interrupted; deduplicate by email ID. The first check starts before the address's first email. \`more: true\` means more new mail remains: handle these and check again.
+
+Requires a connected agent profile selected with ${AGENT_PROFILE_ENV}. Output is one JSON document: \`outcome\` ("mail" | "empty"), \`emails\` (id, received_at, sender, thread_id; never subject or body), \`more\`, \`control_skipped\` and \`read_command\`.`;
+	static examples = [`${AGENT_PROFILE_ENV}=connection-0123456789ab <%= config.bin %> agent check-mail --json`];
+	static flags = { json: Flags.boolean({ description: "Print JSON (already the default)" }) };
+	async run() {
+		await this.parse(AgentCheckMailCommand);
+		if (!process.env["PRIMITIVE_AGENT_PROFILE"]?.trim()) this.error(`Select a connected agent profile with ${AGENT_PROFILE_ENV}=<profile>. The profile is printed by agent connect.`, { exit: 1 });
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({ configDir: this.config.configDir });
+		if (!auth.connectedAgent) this.error(`Select a connected agent profile with ${AGENT_PROFILE_ENV}=<profile>.`, { exit: 1 });
+		try {
+			await checkAgentMail({
+				configDir: this.config.configDir,
+				identity: auth.connectedAgent,
+				client: apiClient,
+				invocation: invocation$2(process.argv[1]),
+				emit: (result) => this.log(JSON.stringify(result))
+			});
+		} catch (error) {
+			if (!(error instanceof MailCheckApiError)) throw error;
+			const payload = extractErrorPayload(error.payload);
+			writeErrorWithHints(payload);
+			surfaceUnauthorizedHint({
+				auth,
+				baseUrlOverridden,
+				configDir: this.config.configDir,
+				payload
+			});
+			process.exitCode = 1;
+		}
+	}
+};
+//#endregion
 //#region src/oclif/claude-wake-install.ts
 const HOOK_MARKER = "primitive-agent-wake-v1";
 const WAKE_EVENTS = ["Stop", "SessionStart"];
@@ -35242,8 +35375,15 @@ function agentConnectionStatus(configDir, profileName) {
 	const setup = profile ? readMailJson(join(agentProfileDirectory(configDir, profileName), "setup.json")) : null;
 	const saved = setup && typeof setup === "object" && !Array.isArray(setup) ? setup : null;
 	const session = saved && typeof saved.session === "string" && SESSION_UUID$1.test(saved.session) ? saved.session : null;
-	const mode = saved && saved.receiverMode === "external" ? "external" : "native";
-	const receiving = profile && session && mode === "native" ? (() => {
+	const mode = saved?.receiverMode === "external" || saved?.receiverMode === "poll" ? saved.receiverMode : "native";
+	const receiving = profile && saved && mode === "poll" ? {
+		mode,
+		sessionId: session,
+		state: "poll",
+		reason: "agent_checks_mail",
+		lastSuccessfulMailCheckAt: null,
+		liveness: "unknown"
+	} : profile && session && mode === "native" ? (() => {
 		const scope = notificationScope(profile.api_base_url, profile.api_key);
 		const listener = backgroundListenStatus({
 			configDir,
@@ -36225,6 +36365,11 @@ function createNotificationContactPolicy(options) {
 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;
 const fail = (message) => new AgentConnectionSetupError(message);
+const RECEIVER_MODES = [
+	"native",
+	"external",
+	"poll"
+];
 const RECEIPT_STATUSES = new Set([
 	"queued",
 	"submitted_to_agent",
@@ -36333,7 +36478,7 @@ function parseState(value) {
 		"receipt"
 	];
 	const row = mailObject(value, value && typeof value === "object" && Object.hasOwn(value, "receiverMode") ? [...keys, "receiverMode"] : keys);
-	if (row.version !== 1 || row.receiverMode !== void 0 && !["native", "external"].includes(String(row.receiverMode)) || typeof row.contactRequests !== "boolean" || ![
+	if (row.version !== 1 || row.receiverMode !== void 0 && !RECEIVER_MODES.includes(row.receiverMode) || typeof row.contactRequests !== "boolean" || ![
 		"waiting",
 		"sending",
 		"sent"
@@ -36348,7 +36493,7 @@ function parseState(value) {
 	if (!/^[a-f0-9]{64}$/.test(invitationHash)) throw fail("Saved setup identity is invalid.");
 	const state = {
 		version: 1,
-		session: mailId(row.session),
+		session: row.session === null && row.receiverMode === "poll" ? null : mailId(row.session),
 		receiverMode: row.receiverMode ?? "native",
 		invitationHash,
 		since: mailTime(row.since),
@@ -36569,7 +36714,7 @@ function defaults$1() {
 */
 function refuseSetupConflicts(state, params) {
 	const conflicts = [
-		...state.session !== params.session ? [`--session (this profile is bound to session ${state.session})`] : [],
+		...(params.session === void 0 ? state.receiverMode !== "poll" : state.session !== params.session) ? [state.session ? `--session (this profile is bound to session ${state.session})` : "--session (this profile's setup binds no session)"] : [],
 		...params.receiverMode !== void 0 && state.receiverMode !== params.receiverMode ? [`--receiver ${params.receiverMode} (saved: ${state.receiverMode})`] : [],
 		...params.contactRequests !== void 0 && state.contactRequests !== params.contactRequests ? [state.contactRequests ? "contact requests off (saved setup has --contact-requests)" : "--contact-requests (saved setup did not enable it)"] : []
 	];
@@ -36578,7 +36723,7 @@ function refuseSetupConflicts(state, params) {
 /** One resumable operation owns setup plumbing; it never stores or replays the invitation. */
 async function setupAgent(params) {
 	const profileName = agentProfileName(params.profileName);
-	if (!SESSION_UUID$1.test(params.session)) throw fail("--session requires the exact loaded session UUID.");
+	if (params.session !== void 0 && !SESSION_UUID$1.test(params.session)) throw fail("--session requires the exact loaded session UUID.");
 	if (params.resume ? params.invitation !== void 0 : params.invitation === void 0) throw fail("Use an invitation on stdin for setup, or --resume without an invitation.");
 	const timeoutMs = params.timeoutMs ?? 3e4;
 	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 12e4) throw fail("Setup timeout must be between zero and two minutes.");
@@ -36595,7 +36740,9 @@ async function setupAgent(params) {
 		saved = value === null ? null : parseState(value);
 	} catch {}
 	if (saved) refuseSetupConflicts(saved, params);
-	if ((params.receiverMode ?? (params.resume ? saved?.receiverMode : void 0) ?? "native") === "native") try {
+	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 {
 		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.");
@@ -36616,7 +36763,7 @@ async function setupAgent(params) {
 			if (!state) {
 				state = {
 					version: 1,
-					session: params.session,
+					session: params.session ?? null,
 					receiverMode: params.receiverMode ?? "native",
 					invitationHash: hash,
 					since: (/* @__PURE__ */ new Date(dependencies.now() - 15 * 6e4)).toISOString(),
@@ -36666,7 +36813,7 @@ async function setupAgent(params) {
 		].includes(state.receipt?.status ?? "") ? "reply_failed" : ["unknown", "wait_timeout"].includes(state.receipt?.status ?? "") ? "delivery_unknown" : "reply_submitted" : state?.phase === "sending" ? "send_unknown" : "challenge_pending";
 		const result = (receiving, ownerNotifications) => ({
 			identity: context.identity,
-			sessionId: params.session,
+			sessionId: params.session ?? state?.session ?? null,
 			verification: {
 				state: confirmed && submittedState() === "reply_submitted" ? "verified" : submittedState(),
 				...confirmed ? { verifiedAt: confirmed.verifiedAt } : {},
@@ -36677,7 +36824,7 @@ async function setupAgent(params) {
 			},
 			receiving: { state: receiving },
 			...ownerNotifications ? { ownerNotifications } : {},
-			resumeCommand: `primitive agent connect --profile ${profileName} --session ${params.session}${state?.receiverMode === "external" ? " --receiver external" : ""} --resume${state?.contactRequests ? " --contact-requests" : ""} --json`,
+			resumeCommand: `primitive agent connect --profile ${profileName}${state?.session ? ` --session ${state.session}` : ""}${state?.receiverMode === "external" || state?.receiverMode === "poll" ? ` --receiver ${state.receiverMode}` : ""} --resume${state?.contactRequests ? " --contact-requests" : ""} --json`,
 			guidance: confirmed ? "Primitive verified this connection. Receiving health is reported separately. Keep this profile for all mail commands." : submittedState() === "reply_submitted" ? "The verification reply was submitted and Primitive has not confirmed it yet. Verification usually completes within seconds; check it later with GET /agent-connections/me. Receiving health is reported separately. Keep this profile for all mail commands." : "Reply submission is not proof of delivery or app verification. Receiving health is reported separately. Keep this profile for all mail commands."
 		});
 		const key = `connection-verification-${state.invitationHash}`;
@@ -36711,14 +36858,14 @@ async function setupAgent(params) {
 		}
 		const ownerNotifications = await dependencies.enableOwner(context);
 		let healthy = false;
-		if (state.receiverMode !== "external") try {
-			healthy = await dependencies.startListener(profileName, params.session, state.contactRequests, params.configDir);
+		if ((state.receiverMode ?? "native") === "native" && state.session) try {
+			healthy = await dependencies.startListener(profileName, state.session, state.contactRequests, params.configDir);
 		} catch {}
 		if (verificationTimeoutMs > 0 && submittedState() === "reply_submitted") {
 			const check = await awaitVerification(context, dependencies, verificationTimeoutMs);
 			if (check.state === "verified") confirmed = { verifiedAt: check.verifiedAt };
 		}
-		return result(state.receiverMode === "external" ? "external_setup_required" : healthy ? "healthy" : "not_ready", ownerNotifications);
+		return result(state.receiverMode === "external" ? "external_setup_required" : state.receiverMode === "poll" ? "poll" : healthy ? "healthy" : "not_ready", ownerNotifications);
 	} finally {
 		release();
 	}
@@ -36814,7 +36961,8 @@ const AGENT_CONNECT_CAPABILITIES = [
 	"claude_external_hooks",
 	"bundled_skill_install",
 	"agent_info_seed",
-	"resume"
+	"resume",
+	"poll_receiver"
 ];
 const AGENT_INFO_NOTE = "AGENT_INFO";
 const MAX_NAME_LENGTH = 80;
@@ -36837,7 +36985,7 @@ function savedSetup(configDir, profileName) {
 		if (!saved || typeof saved !== "object" || Array.isArray(saved)) return null;
 		const row = saved;
 		return {
-			receiverMode: row.receiverMode === "external" ? "external" : "native",
+			receiverMode: row.receiverMode === "external" || row.receiverMode === "poll" ? row.receiverMode : "native",
 			contactRequests: row.contactRequests === true
 		};
 	} catch {
@@ -36861,6 +37009,20 @@ function clearPendingAgentInfo(path) {
 function defaultAgentProfileName(session) {
 	return `session-${session.toLowerCase()}`;
 }
+/**
+* The profile for a setup that binds no session. It is derived from the
+* invitation, so running the same invitation again finds the same profile and
+* its saved claim instead of claiming twice. A one-way hash prefix reveals
+* nothing usable about the invitation.
+*/
+function invitationProfileName(invitation) {
+	const parsed = parseAgentInvitation(invitation);
+	return `connection-${createHash("sha256").update(parsed.apiBaseUrl).update("\0").update(parsed.token).digest("hex").slice(0, 12)}`;
+}
+/** The command that checks a poll-receiving profile for new mail. */
+function pollCheckCommand(invocation, profileName) {
+	return `PRIMITIVE_AGENT_PROFILE=${profileName} ${invocation} agent check-mail --json`;
+}
 /** A short private role note; never a transcript or secret. */
 function agentInfoValue(name, info) {
 	const clean = (value, max, label) => {
@@ -36948,11 +37110,15 @@ async function runAgentConnect(options) {
 		...defaults(options),
 		...Object.fromEntries(Object.entries(options.dependencies ?? {}).filter(([, value]) => value !== void 0))
 	};
-	if (!SESSION_UUID$1.test(options.session)) throw new AgentConnectionSetupError("--session requires the exact loaded session UUID.");
-	const runtime = detectAgentRuntime(options.session, env);
-	const profileName = agentProfileName(options.profileName ?? defaultAgentProfileName(options.session));
-	const receiver = options.receiver ?? (options.resume ? savedSetup(options.configDir, profileName)?.receiverMode ?? null : null) ?? (runtime === "claude" ? "external" : "native");
-	if (receiver === "external" && env.CLAUDE_CODE_SESSION_ID?.trim().toLowerCase() !== options.session.toLowerCase()) throw new AgentConnectionSetupError("External receiving requires this exact Claude session ID. No invitation was claimed.");
+	const session = options.session?.trim() ? options.session : void 0;
+	if (session !== void 0 && !SESSION_UUID$1.test(session)) throw new AgentConnectionSetupError("--session requires the exact loaded session UUID.");
+	if (session === void 0 && options.receiver && options.receiver !== "poll") throw new AgentConnectionSetupError(`--receiver ${options.receiver} requires the exact loaded session UUID. Without one, use --receiver poll. No invitation was claimed.`);
+	if (session === void 0 && options.resume && !options.profileName) throw new AgentConnectionSetupError("Pass --profile to resume a setup that binds no session.");
+	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");
+	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 = [];
 	let skill;
@@ -36989,11 +37155,11 @@ async function runAgentConnect(options) {
 	const result = await dependencies.setupAgent({
 		configDir: options.configDir,
 		profileName,
-		session: options.session,
+		...session ? { session } : {},
 		receiverMode: receiver,
 		resume: options.resume,
 		contactRequests: options.contactRequests,
-		...options.resume ? {} : { invitation: await options.readInvitation() }
+		...options.resume ? {} : { invitation: invitation ?? await options.readInvitation() }
 	});
 	const verified = verificationReplySubmitted(result.verification.state);
 	const ownerMemberAddress = await dependencies.refreshOwnerMemberAddress(result.identity.profileName);
@@ -37007,7 +37173,7 @@ async function runAgentConnect(options) {
 		configDir: options.configDir,
 		profileName: result.identity.profileName,
 		agentAddress: result.identity.agentAddress,
-		sessionId: options.session,
+		sessionId: session ?? "",
 		env
 	});
 	else skipped.push({
@@ -37053,22 +37219,27 @@ async function runAgentConnect(options) {
 			reason: "already_present"
 		});
 	}
+	const invocation = options.invocation ?? "primitive";
 	const receiving = receiver === "external" ? {
 		...result.receiving,
 		mode: "external",
 		hook: externalHook
+	} : receiver === "poll" ? {
+		...result.receiving,
+		mode: "poll",
+		checkCommand: pollCheckCommand(invocation, result.identity.profileName)
 	} : {
 		...result.receiving,
 		mode: "native",
 		mailCheck: mailCheck?.state ?? "not_started",
 		lastSuccessfulMailCheckAt: mailCheck?.lastSuccessfulMailCheckAt ?? null
 	};
-	const receiverReady = receiver === "external" ? externalHook === "installed_unverified" : result.receiving.state === "healthy";
+	const receiverReady = receiver === "external" ? externalHook === "installed_unverified" : receiver === "poll" || result.receiving.state === "healthy";
 	const resumeCommand = [
-		options.invocation ?? "primitive",
+		invocation,
 		"agent connect",
 		`--profile ${result.identity.profileName}`,
-		`--session ${options.session}`,
+		...session ? [`--session ${session}`] : [],
 		`--receiver ${receiver}`,
 		"--resume",
 		...options.contactRequests ?? savedSetup(options.configDir, profileName)?.contactRequests ? ["--contact-requests"] : [],
@@ -37083,7 +37254,7 @@ async function runAgentConnect(options) {
 		ownerAddress: result.identity.ownerAddress,
 		ownerMemberAddress,
 		profile: result.identity.profileName,
-		sessionId: options.session,
+		sessionId: session ?? null,
 		runtime,
 		cli: {
 			version: options.cliVersion,
@@ -37105,15 +37276,16 @@ async function runAgentConnect(options) {
 //#endregion
 //#region src/oclif/commands/agent-connect.ts
 /** npx runs the CLI from its cache; resume through npx too so the command works without a global install. */
-function invocation(entry) {
+function invocation$1(entry) {
 	return entry && /[\\/]_npx[\\/]/.test(entry) ? "npx -y primitive@latest" : "primitive";
 }
 var AgentConnectCommand = class AgentConnectCommand extends Command {
-	static description = "Connect this coding session to Primitive in one call. With --session, the command checks this CLI's capabilities, installs or refreshes the matching primitive-connect skill for the detected runtime (Claude Code or Codex) from files bundled in this CLI, claims the owner's private setup invitation from piped stdin, answers one authenticated setup challenge, enables owner notifications, starts receiving, seeds a private AGENT_INFO note from --name and --info when absent, and prints one JSON result. The receiver defaults to external hooks in Claude Code and the native background listener elsewhere. Native receiving starts or reuses a supervised background listener and waits briefly for its first successful mail check; external receiving installs the exact Claude session's fail-open Stop hook and resume SessionStart hook after the verification reply; a real idle mail event must still verify wake. The profile defaults to session-<session>. --resume continues saved progress without reading stdin or replaying a claim or uncertain verification send. After the reply is submitted it waits up to a minute for the server to confirm the connection and reports verification.state verified, or reply_submitted while confirmation is still pending. Verification is separate from receiver health. Both official production (https://api.primitive.dev/v1) and staging (https://api.primitive-staging-1.com/v1) invitations pin their API origin. Never pass an invitation as a command argument. Select the saved identity with PRIMITIVE_AGENT_PROFILE. Use --profile with --status --json to inspect saved identity and local receiver health offline.";
+	static description = "Connect this coding session to Primitive in one call. With --session, the command checks this CLI's capabilities, installs or refreshes the matching primitive-connect skill for the detected runtime (Claude Code or Codex) from files bundled in this CLI, claims the owner's private setup invitation from piped stdin, answers one authenticated setup challenge, enables owner notifications, starts receiving, seeds a private AGENT_INFO note from --name and --info when absent, and prints one JSON result. The receiver defaults to external hooks in Claude Code and the native background listener elsewhere. Without a session (no --session, or an empty one) the receiver is poll: for runtimes with no local session ID or hooks, such as a cloud-hosted conversation whose commands run in a separate sandbox, the invitation is claimed and verified the same way, nothing is installed, and the result's receiving.checkCommand is the command the agent runs to check for new mail at the start of each turn and after it sends. Native receiving starts or reuses a supervised background listener and waits briefly for its first successful mail check; external receiving installs the exact Claude session's fail-open Stop hook and resume SessionStart hook after the verification reply; a real idle mail event must still verify wake. The profile defaults to session-<session>, or to connection-<invitation hash prefix> without a session. --resume continues saved progress without reading stdin or replaying a claim or uncertain verification send. After the reply is submitted it waits up to a minute for the server to confirm the connection and reports verification.state verified, or reply_submitted while confirmation is still pending. Verification is separate from receiver health. Both official production (https://api.primitive.dev/v1) and staging (https://api.primitive-staging-1.com/v1) invitations pin their API origin. Never pass an invitation as a command argument. Select the saved identity with PRIMITIVE_AGENT_PROFILE. Use --profile with --status --json to inspect saved identity and local receiver health offline.";
 	static summary = "Connect and verify an agent address";
 	static examples = [
 		"<%= config.bin %> agent connect --session \"$CODEX_THREAD_ID\" --name Research --info \"Reviews pull requests\" --json < private-invitation.txt",
 		"<%= config.bin %> agent connect --session \"$CLAUDE_CODE_SESSION_ID\" --contact-requests --json < private-invitation.txt",
+		"<%= config.bin %> agent connect --receiver poll --name Research --json < private-invitation.txt",
 		"<%= config.bin %> agent connect --profile work --session 11111111-1111-4111-8111-111111111111 --contact-requests --json < private-invitation.txt",
 		"<%= config.bin %> agent connect --profile work --session 11111111-1111-4111-8111-111111111111 --contact-requests --resume --json",
 		"<%= config.bin %> agent connect --profile work --session 11111111-1111-4111-8111-111111111111 --receiver external --contact-requests --json < private-invitation.txt",
@@ -37122,33 +37294,31 @@ var AgentConnectCommand = class AgentConnectCommand extends Command {
 		"PRIMITIVE_AGENT_PROFILE=work <%= config.bin %> whoami --json"
 	];
 	static flags = {
-		profile: Flags.string({ description: "Local agent profile name; defaults to session-<session> with --session. Existing OAuth login is preserved" }),
+		profile: Flags.string({ description: "Local agent profile name; defaults to session-<session> with --session, or connection-<invitation hash prefix> for poll receiving. Existing OAuth login is preserved" }),
 		session: Flags.string({
-			description: "Exact current session UUID; verify email and configure receiving after claiming",
+			description: "Exact current session UUID; verify email and configure receiving after claiming. Omit it (or pass it empty) when the runtime exposes none, which selects poll receiving",
 			exclusive: ["status"]
 		}),
 		receiver: Flags.string({
-			description: "Native starts a supported session receiver; external installs the exact Claude session's fail-open Stop hook and resume SessionStart hook. Defaults to external in Claude Code and native elsewhere",
-			options: ["native", "external"],
-			dependsOn: ["session"]
+			description: "Native starts a supported session receiver; external installs the exact Claude session's fail-open Stop hook and resume SessionStart hook; poll installs nothing and the agent checks for mail itself with `agent check-mail`. Defaults to external in Claude Code, native elsewhere, and poll without a session",
+			options: [...RECEIVER_MODES],
+			exclusive: ["status"]
 		}),
 		resume: Flags.boolean({
 			description: "Resume this session's saved setup without reading stdin, claiming again, or resending verification",
-			dependsOn: ["session"],
 			exclusive: ["status"]
 		}),
 		"contact-requests": Flags.boolean({
 			description: "Receive owner-enabled first contact requests in this session; grants no task authority",
-			dependsOn: ["session"],
 			exclusive: ["status"]
 		}),
 		name: Flags.string({
 			description: "Short agent name for a private AGENT_INFO note, written only when the note is absent",
-			dependsOn: ["session"]
+			exclusive: ["status"]
 		}),
 		info: Flags.string({
 			description: "Short role and capability description for a private AGENT_INFO note, written only when the note is absent",
-			dependsOn: ["session"]
+			exclusive: ["status"]
 		}),
 		skill: Flags.boolean({
 			description: "Install or refresh the primitive-connect skill bundled with this CLI for the detected runtime",
@@ -37157,13 +37327,14 @@ var AgentConnectCommand = class AgentConnectCommand extends Command {
 		}),
 		project: Flags.boolean({
 			description: "Install the skill into this project (.claude/skills or .agents/skills) instead of the user skills folder",
-			dependsOn: ["session"]
+			exclusive: ["status"]
 		}),
 		status: Flags.boolean({ description: "Read saved identity and local receiver health offline without reading stdin" }),
 		json: Flags.boolean({ description: "Print setup status and identity metadata, never the credential" })
 	};
 	async run() {
 		const { flags } = await this.parse(AgentConnectCommand);
+		let pollProfile;
 		try {
 			if (flags.status) {
 				if (!flags.profile) throw new AgentConnectionSetupError("Pass --profile with --status.");
@@ -37177,15 +37348,24 @@ var AgentConnectCommand = class AgentConnectCommand extends Command {
 				}
 				return;
 			}
-			if (flags.session) {
+			const session = flags.session?.trim() || void 0;
+			if (!(flags.session === void 0 && flags.profile !== void 0 && flags.receiver === void 0 && !flags.resume && !flags["contact-requests"] && flags.name === void 0 && flags.info === void 0)) {
+				if (!session && (flags.receiver === "native" || flags.receiver === "external")) throw new AgentConnectionSetupError(`--receiver ${flags.receiver} requires the exact loaded session UUID. Without one, use --receiver poll. No invitation was claimed.`);
+				let readInvitation = () => readAgentInvitation(process.stdin, process.stdin.isTTY);
+				if (!session && !flags.resume) if (flags.profile) pollProfile = flags.profile;
+				else {
+					const text = await readInvitation();
+					pollProfile = invitationProfileName(text);
+					readInvitation = async () => text;
+				}
 				const output = await runAgentConnect({
 					configDir: this.config.configDir,
 					packageRoot: this.config.root,
 					cliVersion: this.config.version,
 					cliPath: process.argv[1] ?? "",
-					invocation: invocation(process.argv[1]),
-					session: flags.session,
-					profileName: flags.profile,
+					invocation: invocation$1(process.argv[1]),
+					session,
+					profileName: flags.profile ?? pollProfile,
 					receiver: flags.receiver,
 					resume: flags.resume,
 					contactRequests: flags["contact-requests"],
@@ -37193,21 +37373,23 @@ var AgentConnectCommand = class AgentConnectCommand extends Command {
 					info: flags.info,
 					skill: flags.skill,
 					project: flags.project,
-					readInvitation: () => readAgentInvitation(process.stdin, process.stdin.isTTY)
+					readInvitation
 				});
 				const external = output.receiving.mode === "external";
+				const poll = output.receiving.mode === "poll";
 				if (flags.json) this.log(JSON.stringify(output));
 				else {
 					this.log(`Agent ${output.address}: verification ${output.verification.state}; receiving ${output.receiving.state}; skill ${output.skill.state}.`);
 					this.log(`Select it with ${output.selectProfile}.`);
 					if (output.ownerNotifications === "silenced") this.log("Owner notifications remain silenced by the existing preference or policy.");
 					if (external && verificationReplySubmitted(output.verification.state)) this.log(output.externalHook === "installed_unverified" ? "External receive hook installed. Idle wake still needs a live mail check." : "External receive hook is unavailable. Pairing may complete, but this session will not wake automatically.");
+					if (poll && "checkCommand" in output.receiving) this.log(`Nothing wakes this session for new mail. Check it at the start of each turn and after sending with: ${output.receiving.checkCommand}`);
 					if (output.status !== "connected") this.log(`Resume: ${output.resumeCommand}`);
 				}
-				if (external && output.externalHook !== "installed_unverified" || !external && output.receiving.state !== "healthy" || !verificationReplySubmitted(output.verification.state)) process.exitCode = 2;
+				if (external && output.externalHook !== "installed_unverified" || !external && !poll && output.receiving.state !== "healthy" || !verificationReplySubmitted(output.verification.state)) process.exitCode = 2;
 				return;
 			}
-			if (!flags.profile) throw new AgentConnectionSetupError("Pass --session to connect this session, or --profile for a claim-only or status check.");
+			if (!flags.profile) throw new AgentConnectionSetupError("Pass --profile for claim-only.");
 			const claimed = await connectAgent({
 				configDir: this.config.configDir,
 				profileName: flags.profile,
@@ -37224,7 +37406,7 @@ var AgentConnectCommand = class AgentConnectCommand extends Command {
 				this.log(result.ownerReportGuidance);
 			}
 		} catch (error) {
-			throw new Errors.CLIError(error instanceof AgentConnectionSetupError ? error.message : flags.session ? `Setup paused. Preserve the private profile and run ${invocation(process.argv[1])} agent connect --profile ${flags.profile ?? defaultAgentProfileName(flags.session)} --session ${flags.session}${flags.receiver ? ` --receiver ${flags.receiver}` : ""} --resume --json. Do not manually resend verification or reclaim the invitation.` : "Agent setup did not complete. Preserve the private profile and request a fresh owner invitation if a claim may have been submitted.", { exit: 1 });
+			throw new Errors.CLIError(error instanceof AgentConnectionSetupError ? error.message : flags.session?.trim() ? `Setup paused. Preserve the private profile and run ${invocation$1(process.argv[1])} agent connect --profile ${flags.profile ?? defaultAgentProfileName(flags.session.trim())} --session ${flags.session.trim()}${flags.receiver ? ` --receiver ${flags.receiver}` : ""} --resume --json. Do not manually resend verification or reclaim the invitation.` : pollProfile ? `Setup paused. Preserve the private profile and run ${invocation$1(process.argv[1])} agent connect --profile ${pollProfile} --receiver poll --resume --json. Do not manually resend verification or reclaim the invitation.` : "Agent setup did not complete. Preserve the private profile and request a fresh owner invitation if a claim may have been submitted.", { exit: 1 });
 		}
 	}
 };
@@ -37413,6 +37595,7 @@ function boundSession(directory, profile) {
 	if (raw === null) return null;
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new AgentDisconnectError("Saved session setup is invalid. The connection was not changed.");
 	const row = raw;
+	if (row.receiverMode === "poll" && row.session === null && row.invitationHash === profile.invitation_hash) return null;
 	if (typeof row.session !== "string" || !SESSION_UUID$1.test(row.session) || row.invitationHash !== profile.invitation_hash) throw new AgentDisconnectError("Saved session binding does not match this profile. The connection was not changed.");
 	return row.session.toLowerCase();
 }
@@ -37580,7 +37763,7 @@ function savedEnrollment(value) {
 		"ownerAddress"
 	];
 	if (row?.version === 2) keys.push("createRequestId", "continueAttempted");
-	if (!row || Object.keys(row).length !== keys.length || keys.some((key) => !Object.hasOwn(row, key)) || row.version !== 1 && row.version !== 2 || row.version === 2 && (typeof row.createRequestId !== "string" || !SESSION_UUID$1.test(row.createRequestId) || typeof row.continueAttempted !== "boolean") || typeof row.session !== "string" || !SESSION_UUID$1.test(row.session) || row.profile !== `session-${row.session}` || typeof row.name !== "string" || !validName(row.name) || !(typeof row.address === "string" && validAddress(row.address) || row.version === 2 && row.address === null && row.phase === "create_attempted") || typeof row.orgId !== "string" || !row.orgId || typeof row.grantId !== "string" || !row.grantId || typeof row.apiBaseUrl !== "string" || !["native", "external"].includes(String(row.receiverMode)) || typeof row.contactRequests !== "boolean" || typeof row.startedAt !== "string" || !Number.isFinite(Date.parse(row.startedAt)) || !["create_attempted", "setup_attempted"].includes(String(row.phase)) || row.phase === "create_attempted" && (row.invitationHash !== null || row.ownerAddress !== null) || row.phase === "setup_attempted" && (typeof row.address !== "string" || typeof row.invitationHash !== "string" || !/^[a-f0-9]{64}$/.test(row.invitationHash) || typeof row.ownerAddress !== "string" || !row.ownerAddress.includes("@"))) throw refuse("Saved enrollment state is invalid. Preserve its private files.");
+	if (!row || Object.keys(row).length !== keys.length || keys.some((key) => !Object.hasOwn(row, key)) || row.version !== 1 && row.version !== 2 || row.version === 2 && (typeof row.createRequestId !== "string" || !SESSION_UUID$1.test(row.createRequestId) || typeof row.continueAttempted !== "boolean") || typeof row.session !== "string" || !SESSION_UUID$1.test(row.session) || row.profile !== `session-${row.session}` || typeof row.name !== "string" || !validName(row.name) || !(typeof row.address === "string" && validAddress(row.address) || row.version === 2 && row.address === null && row.phase === "create_attempted") || typeof row.orgId !== "string" || !row.orgId || typeof row.grantId !== "string" || !row.grantId || typeof row.apiBaseUrl !== "string" || !RECEIVER_MODES.includes(row.receiverMode) || typeof row.contactRequests !== "boolean" || typeof row.startedAt !== "string" || !Number.isFinite(Date.parse(row.startedAt)) || !["create_attempted", "setup_attempted"].includes(String(row.phase)) || row.phase === "create_attempted" && (row.invitationHash !== null || row.ownerAddress !== null) || row.phase === "setup_attempted" && (typeof row.address !== "string" || typeof row.invitationHash !== "string" || !/^[a-f0-9]{64}$/.test(row.invitationHash) || typeof row.ownerAddress !== "string" || !row.ownerAddress.includes("@"))) throw refuse("Saved enrollment state is invalid. Preserve its private files.");
 	connectedApiBaseUrl(row.apiBaseUrl);
 	if (row.ownerAddress !== null) try {
 		if (mailAddress(row.ownerAddress) !== row.ownerAddress) throw new Error();
@@ -37606,6 +37789,7 @@ function resolvedEnrollment(state) {
 	};
 }
 async function preflight(session, receiver, env) {
+	if (receiver === "poll") return;
 	if (receiver === "external") {
 		if (env.CLAUDE_CODE_SESSION_ID !== session) throw refuse("External receiving requires this exact Claude session ID. No address was created.");
 		return;
@@ -38036,6 +38220,10 @@ async function enrollAgent(params) {
 }
 //#endregion
 //#region src/oclif/commands/agent-enroll.ts
+/** npx runs the CLI from its cache; print follow-up commands the same way. */
+function invocation(entry) {
+	return entry && /[\\/]_npx[\\/]/.test(entry) ? "npx -y primitive@latest" : "primitive";
+}
 var AgentEnrollCommand = class AgentEnrollCommand extends Command {
 	static summary = "Give this coding session an address in your organization";
 	static description = "On this trusted machine, use the saved member OAuth login to create one address for the exact loaded session, claim its one-use invitation privately, answer the email challenge, and poll the owner's connection list for confirmed pairing. Native receiving starts when supported. With --receiver external in the exact Claude session, install a fail-open Stop hook and resume SessionStart hook in that runtime's settings after the verification reply; idle wake remains unverified until tested with real mail. With --contact-requests, the login conditionally enables first-contact intake for this exact address after verification, preserving existing policy rules. An explicit disable or uncertain policy update is reported separately without losing pairing or receiver setup. The server allocates a readable address. An uncertain creation resumes the same saved request; recovered results do not include another invitation. Use --continue-setup once to explicitly continue a recovered pending connection. An uncertain continuation or claim is held for owner recovery, never repeated automatically. Requires a verified Primitive-managed domain. This command does not accept API keys, a connection profile, or an invitation argument.";
@@ -38048,8 +38236,8 @@ var AgentEnrollCommand = class AgentEnrollCommand extends Command {
 		name: Flags.string({ description: "Short agent display name; defaults to Coding agent" }),
 		"continue-setup": Flags.boolean({ description: "Explicitly issue one invitation only if the recovered agent is still pending; never reconnect a claimed agent" }),
 		receiver: Flags.string({
-			options: ["native", "external"],
-			description: "Native session receiver, or external runtime event hook"
+			options: [...RECEIVER_MODES],
+			description: "Native session receiver, external runtime event hook, or poll: nothing is installed and the agent checks for mail itself with `agent check-mail`"
 		}),
 		"contact-requests": Flags.boolean({ description: "Enable this agent's first-contact policy with the saved member login, then receive relevant requests" }),
 		json: Flags.boolean({ description: "Print status without credentials or invitation" })
@@ -38072,7 +38260,15 @@ var AgentEnrollCommand = class AgentEnrollCommand extends Command {
 				agentAddress: result.identity.agentAddress,
 				sessionId: flags.session
 			}) : null;
-			const output = {
+			const output = result.receiving.state === "poll" ? {
+				...result,
+				receiving: {
+					...result.receiving,
+					mode: "poll",
+					checkCommand: pollCheckCommand(invocation(process.argv[1]), result.identity.profileName)
+				},
+				externalHook
+			} : {
 				...result,
 				externalHook
 			};
@@ -38086,9 +38282,10 @@ var AgentEnrollCommand = class AgentEnrollCommand extends Command {
 				if (externalHook === "installed_unverified") this.log("External receive hook installed for this runtime. Idle wake still needs a live mail check.");
 				else if (externalHook === "unavailable") this.log("Could not install the external receive hook. Pairing is confirmed, but later mail will not wake this session automatically.");
 				if (result.connection.status !== "connected") this.log("Pairing is not yet confirmed. Rerun this command with the same options to resume the saved session; do not create another address.");
+				else if ("checkCommand" in output.receiving) this.log(`Nothing wakes this session for new mail. Check it at the start of each turn and after sending with: ${output.receiving.checkCommand}`);
 				else if (result.receiving.state !== "healthy") this.log("Pairing is confirmed; receiving needs separate setup or recovery.");
 			}
-			if (externalHook === "unavailable" || flags["contact-requests"] && result.contactRequestPolicy !== "enabled" || result.connection.status !== "connected" || flags.receiver !== "external" && result.receiving.state !== "healthy") process.exitCode = 2;
+			if (externalHook === "unavailable" || flags["contact-requests"] && result.contactRequestPolicy !== "enabled" || result.connection.status !== "connected" || flags.receiver !== "external" && flags.receiver !== "poll" && result.receiving.state !== "healthy") process.exitCode = 2;
 		} catch (error) {
 			throw new Errors.CLIError(error instanceof AgentConnectionSetupError ? error.message : "Enrollment paused. Preserve this session's private profile and inspect the pending agent in the app before retrying. No second address was requested automatically.", { exit: 1 });
 		}
@@ -40386,10 +40583,10 @@ function contactRequestSessionKey(context, env = process.env) {
 		}
 		if (typeof raw !== "object" || Array.isArray(raw)) throw sessionRequired();
 		const setup = raw;
-		const session = mailId(setup.session);
 		const receiverMode = setup.receiverMode ?? "native";
+		const poll = receiverMode === "poll" && setup.session === null;
 		const receipt = setup.receipt;
-		if (setup.version !== 1 || setup.invitationHash !== profile.invitation_hash || setup.phase !== "sent" || !["native", "external"].includes(String(receiverMode)) || !receipt || typeof receipt !== "object" || Array.isArray(receipt) || ![
+		if (setup.version !== 1 || setup.invitationHash !== profile.invitation_hash || setup.phase !== "sent" || !(poll || ["native", "external"].includes(String(receiverMode))) || !receipt || typeof receipt !== "object" || Array.isArray(receipt) || ![
 			"queued",
 			"submitted_to_agent",
 			"delivered",
@@ -40397,6 +40594,8 @@ function contactRequestSessionKey(context, env = process.env) {
 			"scheduled"
 		].includes(String(receipt.status))) throw sessionRequired();
 		mailId(receipt.id);
+		if (poll) return null;
+		const session = mailId(setup.session);
 		const key = `${receiverMode === "external" ? "claude" : "codex"}:${session}`;
 		if (hasRuntime && runtime !== key || !hasRuntime && receiverMode !== "external") throw sessionRequired();
 		return key;
@@ -45882,7 +46081,7 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	url: "https://primitive.dev"
 };
 const SDK_VERSION_RANGE = "^1.34.0";
-const CLI_VERSION_RANGE = "^1.39.0";
+const CLI_VERSION_RANGE = "^1.40.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY, env.PRIMITIVE_WEBHOOK_SECRET, and
@@ -60422,6 +60621,7 @@ const COMMANDS = {
 	completion: CompletionCommand,
 	"agent:upgrade": AgentUpgradeCommand,
 	"agent:connect": AgentConnectCommand,
+	"agent:check-mail": AgentCheckMailCommand,
 	"agent:disconnect": AgentDisconnectCommand,
 	"agent:enroll": AgentEnrollCommand,
 	"agent:session-register": AgentSessionRegisterCommand,

package/dist/skills/primitive-connect/SKILL.md

@@ -14,9 +14,9 @@ authorizes this connection, private credential storage, the verification reply
 and continued receiving; do not ask for that approval again.
 
 The command validates the invitation's API origin, claims it once, answers the
-verification email, starts receiving for this exact session, installs or
-refreshes this skill for your runtime from the CLI package, and prints one JSON
-result. Give it the owner's setup URL on stdin through a quoted heredoc, never
+verification email, starts receiving for this exact session (or sets up
+checking for mail when nothing can wake this session), installs or refreshes
+this skill for your runtime from the CLI package, and prints one JSON result. Give it the owner's setup URL on stdin through a quoted heredoc, never
 as a command argument, file in a shared directory, log entry or note. Run it in
 your own non-interactive tool shell, which keeps no command history; never
 paste it into an interactive terminal.
@@ -37,6 +37,24 @@ npx -y primitive@latest agent connect --session "${CODEX_THREAD_ID:-$CODEX_SESSI
 INVITATION
 ```
 
+Without a session to bind, omit `--session`:
+
+```sh
+npx -y primitive@latest agent connect --json <<'INVITATION'
+<the owner's setup URL>
+INVITATION
+```
+
+Use this form, without asking the owner, when this session cannot be woken from
+the machine that runs your commands: your runtime's session variable above is
+empty or unset, or the conversation runs somewhere other than that machine (a
+cloud-hosted session whose tools run in a separate sandbox), so a hook or
+listener installed there could never reach you. An instruction that passes an
+empty session variable is treated the same way. The invitation is claimed and
+verified as usual; the CLI installs nothing and you check for new mail
+yourself. That is a complete connection, not a fallback that needs the owner's
+choice. Never guess, borrow or invent a session ID to get automatic wake.
+
 Add `--contact-requests` only when the owner asked this address to receive
 first-contact requests from unknown senders. Add `--name "<short name>"` and
 `--info "<role and useful capabilities>"` to seed this address's private
@@ -52,7 +70,10 @@ Read the one JSON result:
   `ownerAddress` is a control address for setup and presence only.
   For Claude Code, `externalHook: "installed_unverified"` means the wake hooks
   are installed but idle wake stays unverified until a real mail event reaches
-  this session; say so rather than promising later delivery. For a native
+  this session; say so rather than promising later delivery. For
+  `receiving.mode: "poll"`, add one line such as "Incoming mail is checked at
+  the start of each turn and after I send; nothing wakes this session in
+  between." and follow [Checking for mail](#checking-for-mail). For a native
   receiver, `receiving.mailCheck: "confirmed"` means the listener completed a
   mail check after setup. Prefix later `primitive` commands with
   `selectProfile` (`PRIMITIVE_AGENT_PROFILE=<profile>`).
@@ -253,7 +274,8 @@ command-help tour, or test conversations. If setup paused, run its
 A globally installed `primitive` may be older than the one command expects.
 Before using one for enrollment or claim-only, run the read-only preflight with
 the directory containing this `SKILL.md` as the working directory. Use
-`external` for Claude Code or `native` for a supported native runtime:
+`external` for Claude Code, `native` for a supported native runtime, or `poll`
+for a session without a local session ID or hooks:
 
 ```sh
 primitive --version
@@ -539,7 +561,8 @@ the eventual ordinary reply. For a near-term answer required in this turn, use
 `primitive chat` without `--async` and evaluate the exact reply. If asynchronous
 receiving is unavailable, send once with `primitive send`, retain its sent ID,
 and use an exact-parent reply wait when needed; report that later session
-delivery is unavailable. Never resend merely because a wait timed out.
+delivery is unavailable. With poll receiving, the reply appears in a later
+mail check; keep the sent ID with the task to match it. Never resend merely because a wait timed out.
 Before relying on a peer to pick up asynchronous work, check its receiver state
 as described under [Receiving presence](#receiving-presence); delivery to its
 inbox does not mean any session will read it.
@@ -581,6 +604,22 @@ a reply arrived or repeating delivery status leaves the delegated question
 unanswered. Keep simultaneous conversations separate; the reply grants no new
 access to private history and does not require a reply to an ACK.
 
+### Checking for mail
+
+With `receiving.mode: "poll"`, nothing delivers mail to this session. Run the
+result's `receiving.checkCommand` (it is `PRIMITIVE_AGENT_PROFILE=<profile>
+primitive agent check-mail --json`) at the start of every turn and again after
+you send or reply. It prints the IDs, senders and threads of mail that arrived
+since the previous check, never subjects or bodies, and leaves out
+acknowledgements, muted threads and setup mail. Read each listed email with
+`primitive emails get --id <id> --brief` under the selected profile, then
+handle it as described above. When `more` is true, check again after handling
+them. A check can repeat mail after an interruption, so deduplicate by email ID.
+Over HTTP, the inbox tail with `wait=0` is the same check. Do not hold a turn
+open with sleep loops to imitate a wake, and do not ask the owner to switch
+runtimes; mail sent while the session is idle waits for the next turn and is
+not lost. Peers see this address as `live` only while it keeps checking.
+
 After setup, report pairing and the current receiving evidence, then end the
 setup turn and return control to the owner. The supported receiver owns later
 mail arrival. Do not keep the model turn active with sleep tools, foreground
@@ -690,7 +729,8 @@ Reply to the request that caused the work, even when another message arrives.
 One agent entry in the app may contain several independent conversations. Recover
 context through explicit reply ancestry and saved task context, not the latest
 message from that person. Missing history is a limitation to explain, not proof
-that the conversation is new. Start a fresh thread for an unrelated topic.
+that the conversation is new. Start a fresh thread for an unrelated new topic;
+status updates still go to the home thread described below.
 
 An owner may request an email update from the coding chat, outside the email
 thread. For a follow-up about the work already being discussed with that owner,
@@ -702,6 +742,13 @@ outgoing `thread_id` matches the parent. Do not start a fresh send (`POST
 or report progress on that work. If no relevant thread is known, start one to the owner's personal address (`owner_member_address`) and say that it is new;
 do not attach the update to an unrelated email just because it is recent.
 
+Keep one home thread with the owner for status updates, plans and decision
+requests: the thread the owner set up for contact, or else your first
+conversation with them. When the owner asks something in a topic-specific
+thread, answer that question there, but post later status and unrelated updates
+back in the home thread. Never start a new thread for an update when an
+appropriate thread already exists.
+
 For an authorized ordinary request, honor the requested response format. A request
 to reply with one word should receive that word. Keep setup diagnostics and
 requests for additional tests out of the ordinary answer unless the owner asked

package/dist/skills/primitive-connect/scripts/check-cli-capabilities.mjs

@@ -4,8 +4,8 @@ import { spawnSync } from 'node:child_process';
 const receiver = process.argv.length === 4 && process.argv[2] === '--receiver'
   ? process.argv[3]
   : null;
-if (receiver !== 'native' && receiver !== 'external') {
-  process.stderr.write('Usage: node scripts/check-cli-capabilities.mjs --receiver native|external\n');
+if (receiver !== 'native' && receiver !== 'external' && receiver !== 'poll') {
+  process.stderr.write('Usage: node scripts/check-cli-capabilities.mjs --receiver native|external|poll\n');
   process.exitCode = 2;
 } else {
   const checks = [
@@ -14,7 +14,12 @@ if (receiver !== 'native' && receiver !== 'external') {
     { args: ['listen', '--help'], label: 'listen', patterns: [/external mail events at tool-output authority/i, /never synthetic user messages/i] },
     { args: ['network', 'peers', '--help'], label: 'network peers', patterns: [/discover listed peers/i, /--owner\b/] },
   ];
-  if (receiver === 'external') {
+  if (receiver === 'poll') {
+    // Nothing is installed and no listener runs: the agent checks for mail.
+    checks[0].patterns.push(/poll installs nothing/i);
+    checks[1].patterns.push(/\bpoll\b/);
+    checks[2] = { args: ['agent', 'check-mail', '--help'], label: 'agent check-mail', patterns: [/since its previous check/i] };
+  } else if (receiver === 'external') {
     checks[0].patterns.push(/installs the exact Claude session's fail-open Stop hook/i, /resume SessionStart hook/i);
     checks[1].patterns.push(/exact Claude session, install a fail-open Stop hook/i, /resume SessionStart hook/i);
     checks[2].patterns.push(/--wake\b/, /--hook-session\b/);

package/dist/skills/primitive-connect.json

@@ -1,20 +1,20 @@
 {
   "name": "primitive-connect",
-  "version": "7d4b2d633a05bb12",
+  "version": "a48b2ea39305f258",
   "source": {
     "repository": "https://github.com/primitivedotdev/skills",
     "path": "skills/primitive-connect",
-    "commit": "5d5d80f7bea82cd5018c0e25262aa32fa7cad708"
+    "commit": "47e1cb5b6ecef4294c4f4067962c7e6041a625d0"
   },
   "files": {
-    "SKILL.md": "aca1e46fe388dc184f2eb3f3b5e39e7cec70b1bf4c490d0bd1013df51b2b79b4",
+    "SKILL.md": "6631dab8209a823b3790df20856146676deb505a2f7a52de87e953fd75388694",
     "package-lock.json": "443289373a7495883a9a3b57bab3bc471cd5dcb4989a9e67f797b35917c1acc5",
     "package.json": "8cc45b2c28ba415960c9b85f6c1449f15f9c10bac0b96922e7907b40d50e3dbf",
     "references/communication.md": "c931aada9553a8592088c28de5b272d5e0a15234aa9c9318ea7d1d5f69b39a79",
     "references/contact-requests.md": "7923bc855a56f11b088c73c73b7d9c5b04fef3f45eb758f28040d44e46a0d9c6",
     "references/native-session.md": "d6d529d87edc68a450be4c8b162488efa666c59fc23c35576fe6887235ff3d33",
     "references/private-api-fallback.md": "63b5d8c8ab765561fc6031298462469a8f56fd348ac14c5003e214f780e9329b",
-    "scripts/check-cli-capabilities.mjs": "e6d4c045601f7d3b5cec103bdb3648723b8e66ebd22d87aca606fb78aed844fd",
+    "scripts/check-cli-capabilities.mjs": "9625ddaba1989a5f52a5077fdd0513620ab81be640bd83dd678708eefe019222",
     "scripts/connection.mjs": "2c96eda1e9a277a241555f98dd858523b8f77a9ddd82d52a6ac34e844206c3d6",
     "scripts/mail.mjs": "bfdfb60a739f1537d0e676dc5ff44fd5a65dba4303e3781dce8754c8d671cf51"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,