overmux 0.0.3 → 0.0.5

package/dist/bin.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 import { createRequire, findPackageJSON } from "node:module";
-import { access, chmod, readFile, readdir, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { constants, cpSync, createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
+import { access, open, readFile, readdir, realpath } from "node:fs/promises";
 import { createConnection, isIP } from "node:net";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { createJiti } from "jiti";
 import { ZodError, z } from "zod";
-import { homedir, tmpdir } from "node:os";
-import { createHash } from "node:crypto";
+import { createJiti } from "jiti";
+import { homedir, hostname } from "node:os";
 import ts from "typescript";
 import { isDeepStrictEqual } from "node:util";
 import { fork, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { cpSync, createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -1825,6 +1825,35 @@ async function run(app, inputs, context) {
 /* v8 ignore if -- @preserve */
 /* v8 ignore else -- @preserve */
 //#endregion
+//#region ../shared/dist/index.js
+var safeRelativeNotificationLink = (link) => {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(link);
+	} catch {
+		return false;
+	}
+	return !decoded.startsWith("//") && !decoded.includes("\\") && ![...decoded].some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+};
+var notificationLinkSchema = z.union([z.string().max(4096).startsWith("/").refine(safeRelativeNotificationLink), z.string().max(4096).url().refine((link) => {
+	if (!URL.canParse(link)) return false;
+	const url = new URL(link);
+	return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+})]);
+var notificationSchema = z.object({
+	body: z.string().max(4096).optional(),
+	open: z.object({ link: notificationLinkSchema }).strict().optional(),
+	title: z.string().min(1).max(4096)
+}).strict();
+var instanceIdSchema$1 = z.string().max(253).regex(/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?![\s\S])/, "Expected a lowercase instance ID with only ASCII letters, digits, internal dots and hyphens");
+var createInstanceIdentity = (instanceId) => ({
+	instanceId: instanceIdSchema$1.parse(instanceId),
+	deepLinkPrefix: `overmux://${instanceId}`
+});
+//#endregion
 //#region ../shared/dist/node/index.js
 var durationPattern = /^([1-9]\d*)(ms|s|m|h|d)$/;
 var millisecondsByUnit = {
@@ -1842,6 +1871,7 @@ var durationToMilliseconds = (duration) => {
 	return Number.isSafeInteger(milliseconds) ? milliseconds : void 0;
 };
 var aiContextSnippets = ["package-source", "tech-stack-recommendations"];
+var instanceIdSchema = z.string().max(253).regex(/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?![\s\S])/, "Expected a lowercase instance ID with only ASCII letters, digits, internal dots and hyphens");
 var zodTypeSchema = z.custom((value) => value instanceof z.ZodType, "Expected a Zod schema");
 var functionSchema = z.custom((value) => typeof value === "function", "Expected a function");
 var contractRuntimeSchema = z.object({
@@ -1890,12 +1920,11 @@ var loopbackPeerSchema = z.string().refine((value) => isIP(value) !== 0 && (valu
 var authConfigRuntimeSchema = z.object({
 	mode: z.literal("cli-login"),
 	origins: z.array(exactOriginSchema).min(1).refine((origins) => new Set(origins).size === origins.length, "Expected unique origins").optional(),
-	sessionLifetime: z.union([z.literal("never"), authDurationSchema]).default("never"),
+	sessionLifetime: z.union([z.literal("forever"), authDurationSchema]).default("forever"),
 	trustedProxyPeer: loopbackPeerSchema.optional()
 }).strict();
 var serverConfigRuntimeSchema = z.object({
 	host: z.string().min(1).optional(),
-	logFile: z.string().min(1).optional(),
 	port: z.number().int().min(1).max(65535).optional(),
 	productionWebAssetsDir: z.string().min(1).optional(),
 	watch: z.boolean().optional()
@@ -1909,6 +1938,7 @@ var configDefinitionRuntimeSchema = serverConfigRuntimeSchema.extend({
 	aiContextSnippets: z.array(z.enum(aiContextSnippets)).optional(),
 	auth: authConfigRuntimeSchema,
 	debug: z.boolean().optional(),
+	instanceId: z.union([instanceIdSchema, z.custom((value) => typeof value === "function", "Expected an instance ID or a function of the bound port")]).optional(),
 	server: serverDefinitionRuntimeSchema,
 	vite: z.string().min(1).optional()
 });
@@ -1964,89 +1994,13 @@ var getOvermuxPaths = ({ environment = process.env, homeDir = homedir(), xdgCach
 	};
 };
 //#endregion
-//#region ../shared/dist/index.js
-var packageSourceSnippet = "package-source";
-var techStackRecommendationsSnippet = "tech-stack-recommendations";
-var safeRelativeNotificationLink = (link) => {
-	let decoded;
-	try {
-		decoded = decodeURIComponent(link);
-	} catch {
-		return false;
-	}
-	return !decoded.startsWith("//") && !decoded.includes("\\") && ![...decoded].some((character) => {
-		const codePoint = character.codePointAt(0) ?? 0;
-		return codePoint < 32 || codePoint === 127;
-	});
-};
-var notificationLinkSchema = z.union([z.string().max(4096).startsWith("/").refine(safeRelativeNotificationLink), z.string().max(4096).url().refine((link) => {
-	if (!URL.canParse(link)) return false;
-	const url = new URL(link);
-	return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
-})]);
-var notificationSchema = z.object({
-	body: z.string().max(4096).optional(),
-	open: z.object({ link: notificationLinkSchema }).strict().optional(),
-	title: z.string().min(1).max(4096)
-}).strict();
-var defaultAiContextSnippets = [...[packageSourceSnippet], techStackRecommendationsSnippet];
-var packageSourceSnippetContent = `Overmux ships with documentation and TypeScript source.
-
-Run \`overmux docs\` to find the installed documentation and source for the overmux cli.
-
-E.g. \`node_modules/overmux\` and \`node_modules/@overmux/xterm\`.
-
-Inspect these files so guidance matches the versions used by the application.`;
-var techStackRecommendationsSnippetContent = `Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.`;
-var aiContextContentBySnippet = {
-	[packageSourceSnippet]: packageSourceSnippetContent,
-	[techStackRecommendationsSnippet]: techStackRecommendationsSnippetContent
-};
-var composeAiContext = (snippets) => snippets.length === 0 ? "" : `${snippets.map((snippet) => `## ${snippet}\n\n${aiContextContentBySnippet[snippet]}`).join("\n\n")}\n`;
-//#endregion
 //#region src/internal/server/paths.ts
 var getDefaultConfigPath = (options = {}) => join(getOvermuxPaths(options).configDir, "overmux.config.ts");
 //#endregion
-//#region src/internal/cli/commands/ai.ts
-var printAiContext = async (flags, process) => {
-	const { config } = await loadOvermuxConfig({ configPath: flags.config });
-	process.stdout.write(composeAiContext(config.aiContextSnippets ?? defaultAiContextSnippets));
-};
-var createAiContextCommand = (process) => buildCommand({
-	func: (flags) => printAiContext(flags, process),
-	parameters: {
-		aliases: { c: "config" },
-		flags: { config: {
-			brief: "Configuration file",
-			default: getDefaultConfigPath(),
-			kind: "parsed",
-			parse: String,
-			placeholder: "path"
-		} }
-	},
-	docs: { brief: "Print the configured Overmux AI context" }
-});
-var createAiRoute = (process) => buildRouteMap({
-	docs: { brief: "Print Overmux AI context" },
-	routes: { context: createAiContextCommand(process) }
-});
-//#endregion
-//#region src/internal/server/notifications/private-json-file.ts
-var missingFile = (cause) => cause.code === "ENOENT";
-var readPrivateJson = async (path, schema) => {
-	try {
-		const contents = await readFile(path, "utf8");
-		await chmod(path, 384);
-		return schema.parse(JSON.parse(contents));
-	} catch (cause) {
-		if (missingFile(cause)) return;
-		throw cause;
-	}
-};
-//#endregion
 //#region src/internal/server/auth/instance-control.ts
 var maxControlMessageBytes = 16384;
 z.discriminatedUnion("type", [
+	z.object({ type: z.literal("get-instance") }).strict(),
 	z.object({ type: z.literal("ping") }).strict(),
 	z.object({ type: z.literal("create-login") }).strict(),
 	z.object({ type: z.literal("issue-bearer") }).strict(),
@@ -2072,6 +2026,10 @@ var sessionSchema = z.object({
 	revokedAt: z.string().optional()
 }).strict();
 var controlResponseSchemas = {
+	"get-instance": z.object({
+		instanceId: instanceIdSchema$1,
+		ok: z.literal(true)
+	}).strict(),
 	"create-login": z.object({
 		login: loginGrantSchema,
 		ok: z.literal(true)
@@ -2109,12 +2067,36 @@ var registrationSchema = z.object({
 	port: z.number().int().min(1).max(65535),
 	url: z.string().url()
 });
+var currentUid = () => {
+	if (!process.getuid) throw new Error("Overmux instance control requires a Unix user ID");
+	return process.getuid();
+};
 var runtimeDirectory = () => {
-	const paths = getOvermuxPaths();
-	const preferred = paths.runtimeDir ?? join(paths.stateDir, "runtime");
+	const fallback = `/tmp/overmux-${currentUid()}`;
+	const preferred = getOvermuxPaths().runtimeDir;
+	if (!preferred) return fallback;
 	if (Buffer.byteLength(preferred) <= 80) return preferred;
-	const suffix = createHash("sha256").update(preferred).digest("hex").slice(0, 12);
-	return join(tmpdir(), `overmux-${process.getuid?.() ?? "user"}-${suffix}`);
+	return `${fallback}-${createHash("sha256").update(preferred).digest("hex").slice(0, 12)}`;
+};
+var secureRuntimeDirectory = async (directory) => {
+	const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+	try {
+		const metadata = await handle.stat();
+		if (!metadata.isDirectory() || metadata.uid !== currentUid()) throw new Error(`Unsafe Overmux runtime directory: ${directory}`);
+		await handle.chmod(448);
+	} finally {
+		await handle.close();
+	}
+};
+var readRegistration = async (path) => {
+	const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	try {
+		const metadata = await handle.stat();
+		if (!metadata.isFile() || metadata.uid !== currentUid() || (metadata.mode & 63) !== 0) return;
+		return registrationSchema.parse(JSON.parse(await handle.readFile("utf8")));
+	} finally {
+		await handle.close();
+	}
 };
 var readNewlineFrame = ({ maximumBytes, socket, timeout }) => new Promise((resolve, reject) => {
 	let buffer = Buffer.alloc(0);
@@ -2166,12 +2148,13 @@ var discoverInstance = async (port) => {
 	const directory = runtimeDirectory();
 	let names;
 	try {
+		await secureRuntimeDirectory(directory);
 		names = await readdir(directory);
 	} catch (cause) {
 		if (cause.code === "ENOENT") throw new Error("No running Overmux server was found");
 		throw cause;
 	}
-	const candidates = (await Promise.all(names.filter((name) => name.endsWith(".json")).map((name) => readPrivateJson(join(directory, name), registrationSchema).catch(() => void 0)))).filter((registration) => Boolean(registration && processIsLive(registration.pid) && (port === void 0 || registration.port === port)));
+	const candidates = (await Promise.all(names.filter((name) => name.endsWith(".json")).map((name) => readRegistration(join(directory, name)).catch(() => void 0)))).filter((registration) => Boolean(registration && processIsLive(registration.pid) && (port === void 0 || registration.port === port)));
 	const registrations = (await Promise.all(candidates.map(async (registration) => {
 		try {
 			await sendControlRequest(registration, { type: "ping" });
@@ -2217,24 +2200,24 @@ var issueLoginGrant = async (port) => {
 var printLoginFallback = (port, { stdout }) => {
 	stdout.write(`Login with \`overmux auth login --port ${port}\`\n`);
 };
-var printLoginGrant = ({ login, output, port }) => {
+var printLoginGrant = ({ login, output }) => {
 	const expiresIn = Math.max(0, Math.ceil((Date.parse(login.expiresAt) - Date.now()) / 6e4));
 	output.stdout.write([
-		`Code: ${login.code}`,
-		...login.urls.map((url) => `Open: ${url}`),
-		"This single-use grant authenticates one origin. Create another grant to authenticate another origin.",
-		"Enter the code on the login page shown by an unauthenticated Overmux origin.",
-		`Expires at ${login.expiresAt} (in ${expiresIn} minutes).`,
-		`Need another grant? Run \`overmux auth login --port ${port}\`.`,
+		`Code: ${login.code} (enter on the login page)`,
+		"",
+		...login.urls.length === 1 ? [`Login URL: ${login.urls[0]}`] : ["Login URLs:", ...login.urls.map((url) => `  ${url}`)],
+		"",
+		`Expiry in ${expiresIn} minutes (at ${login.expiresAt}).`,
+		"",
 		""
 	].join("\n"));
-	output.stderr.write("The login URL is a temporary credential; avoid sharing terminal output or screenshots.\n");
+	output.stderr.write(`Keep the code and link${login.urls.length === 1 ? "" : "s"} private.\n`);
 };
 //#endregion
 //#region src/internal/cli/parse-port.ts
 var parsePort = (value) => {
 	const port = Number(value);
-	return serverConfigRuntimeSchema.shape.port.safeParse(port).success ? port : /* @__PURE__ */ new Error(`Invalid port: ${value}`);
+	return port > 0 && serverConfigRuntimeSchema.shape.port.safeParse(port).success ? port : /* @__PURE__ */ new Error(`Invalid port: ${value}`);
 };
 //#endregion
 //#region src/internal/cli/commands/auth.ts
@@ -2415,7 +2398,7 @@ z.object({ endpoint: backgroundNotificationSubscriptionSchema.shape.endpoint }).
 z.object({
 	debug: z.boolean(),
 	operations: z.array(z.string().min(1)),
-	protocolVersion: z.literal(9),
+	protocolVersion: z.literal(10),
 	resources: z.array(z.string().min(1)),
 	streams: z.array(z.string().min(1))
 });
@@ -2521,7 +2504,12 @@ var protocolErrorMessageSchema = z.object({
 	subscriptionId: operationIdSchema.optional(),
 	type: z.literal("error")
 });
+var serverInfoMessageSchema = z.object({
+	type: z.literal("server-info"),
+	instanceId: instanceIdSchema$1
+}).strict();
 z.discriminatedUnion("type", [
+	serverInfoMessageSchema,
 	resourceResultMessageSchema,
 	resourceInvalidatedMessageSchema,
 	streamOpenedMessageSchema,
@@ -2533,6 +2521,31 @@ z.discriminatedUnion("type", [
 	notificationEventSchema
 ]);
 //#endregion
+//#region src/internal/server/runtime/runtime-instance.ts
+var defaultInstanceId = ({ port }) => `${hostname()}-${port}`;
+var createRuntimeInstance = (configured) => {
+	let identity;
+	const get = () => {
+		if (!identity) throw new Error("Overmux instance identity is not ready");
+		return identity;
+	};
+	return {
+		context: {
+			getInstanceId: () => get().instanceId,
+			getDeepLinkPrefix: () => get().deepLinkPrefix
+		},
+		establish: (port) => {
+			if (identity) throw new Error("Overmux instance identity is already established");
+			try {
+				identity = createInstanceIdentity(typeof configured === "function" ? configured({ port }) : configured);
+			} catch (cause) {
+				throw new Error("Invalid Overmux instance ID; configure instanceId with a canonical lowercase ID", { cause });
+			}
+			return identity;
+		}
+	};
+};
+//#endregion
 //#region src/internal/server/runtime/runtime-lifecycle.ts
 var asError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
 var disposeAll = async (disposers) => {
@@ -2623,6 +2636,26 @@ var createRuntimeOperations = ({ context, definitions, notifications }) => {
 		names: [...operations.keys()]
 	};
 };
+//#endregion
+//#region ../ai-context/dist/index.js
+var packageSourceSnippet = "package-source";
+var techStackRecommendationsSnippet = "tech-stack-recommendations";
+var defaultAiContextSnippets = [...[packageSourceSnippet], techStackRecommendationsSnippet];
+var packageSourceSnippetContent = `Overmux ships with documentation and TypeScript source.
+
+Run \`overmux docs path\` to find the installed documentation directory for the Overmux CLI. This prints a documentation directory, not source paths.
+
+Inspect TypeScript source in installed packages, e.g. \`node_modules/overmux/src\` and \`node_modules/@overmux/xterm/src\`.
+
+Inspect these files so guidance matches the versions used by the application.`;
+var techStackRecommendationsSnippetContent = `Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.`;
+var aiContextContentBySnippet = {
+	[packageSourceSnippet]: packageSourceSnippetContent,
+	[techStackRecommendationsSnippet]: techStackRecommendationsSnippetContent
+};
+//#endregion
+//#region src/public/ai-context.ts
+var composeAiContext = (snippets) => snippets.length === 0 ? "" : `${snippets.map((snippet) => `## ${snippet}\n\n${aiContextContentBySnippet[snippet]}`).join("\n\n")}\n`;
 z.void();
 var jsonValueSchema = z.lazy(() => z.union([
 	z.string(),
@@ -2699,14 +2732,10 @@ var getInvalidatedResourceIds = (graph, resourceId) => {
 };
 //#endregion
 //#region src/internal/server/runtime/runtime-resources.ts
-var createRuntimeResources = ({ definitions, lifecycle }) => {
+var createRuntimeResources = ({ definitions, instance, lifecycle }) => {
 	const graph = createResourceDependencyGraph(definitions);
 	const invalidationListeners = /* @__PURE__ */ new Set();
-	const contracts = /* @__PURE__ */ new Map();
 	const resources = /* @__PURE__ */ new Map();
-	Object.entries(definitions).forEach(([id, definition]) => {
-		contracts.set(definition.contract, [...contracts.get(definition.contract) ?? [], id]);
-	});
 	const invalidateResource = (id, input, allInputs = false) => {
 		if (lifecycle.signal.aborted) return;
 		const ids = getInvalidatedResourceIds(graph, id);
@@ -2714,16 +2743,14 @@ var createRuntimeResources = ({ definitions, lifecycle }) => {
 			if (ids.has(entry.resourceId) && (allInputs || isDeepStrictEqual(entry.input, input))) entry.listener();
 		});
 	};
-	const invalidate = (contract, input) => {
-		const ids = contracts.get(contract) ?? Object.entries(definitions).filter(([, definition]) => definition.contract.input === contract.input && definition.contract.output === contract.output).map(([id]) => id);
-		if (!ids.length) throw new Error("Cannot invalidate a resource outside this runtime");
-		ids.forEach((id) => {
-			const definition = definitions[id];
-			const parsedInput = input === void 0 ? void 0 : definition.contract.input.parse(input);
-			invalidateResource(id, parsedInput, input === void 0);
-		});
+	const invalidate = (resourceId, input) => {
+		if (!resources.has(resourceId)) throw new Error(`Unknown resource ID: ${resourceId}`);
+		const definition = definitions[resourceId];
+		const parsedInput = input === void 0 ? void 0 : definition.contract.input.parse(input);
+		invalidateResource(resourceId, parsedInput, input === void 0);
 	};
 	const context = (signal) => ({
+		instance,
 		invalidate,
 		signal: lifecycle.requestSignal(signal)
 	});
@@ -2856,11 +2883,13 @@ var createRuntimeStreams = ({ context, definitions, lifecycle }) => {
 };
 //#endregion
 //#region src/internal/server/runtime/create-runtime.ts
-var createRuntime = async ({ config, debug = false, notifications = { send: async () => void 0 }, signal }) => {
+var createRuntime = async ({ config, debug = true, notifications = { send: async () => void 0 }, signal }) => {
 	const lifecycle = createRuntimeLifecycle(signal);
+	const instance = createRuntimeInstance(config.instanceId ?? defaultInstanceId);
 	try {
 		const resources = createRuntimeResources({
 			definitions: config.server.resources ?? {},
+			instance: instance.context,
 			lifecycle
 		});
 		const context = resources.context;
@@ -2876,14 +2905,17 @@ var createRuntime = async ({ config, debug = false, notifications = { send: asyn
 		});
 		lifecycle.signal.throwIfAborted();
 		lifecycle.completePreparation();
+		const manifest = {
+			debug,
+			operations: [...operations.names],
+			protocolVersion: 10,
+			resources: [...resources.names],
+			streams: [...streams.names]
+		};
 		return {
-			manifest: {
-				debug,
-				operations: [...operations.names],
-				protocolVersion: 9,
-				resources: [...resources.names],
-				streams: [...streams.names]
-			},
+			instance: instance.context,
+			establishInstance: instance.establish,
+			manifest,
 			dispose: lifecycle.dispose,
 			getOperation: operations.get,
 			getResource: resources.get,
@@ -3098,7 +3130,6 @@ var childOptionsSchema = z.object({
 	debug: z.boolean().optional(),
 	developmentWebTarget: z.url().optional(),
 	host: z.string().optional(),
-	logFile: z.string().optional(),
 	port: z.number().int().min(0).max(65535).optional(),
 	productionWebAssetsDir: z.string().optional(),
 	watch: z.boolean().optional()
@@ -3796,6 +3827,25 @@ var desktopRoute = buildRouteMap({
 	}
 });
 //#endregion
+//#region src/internal/cli/commands/docs-ai-context.ts
+var createAiContextCommand = (process) => buildCommand({
+	func: async (flags) => {
+		const { config } = await loadOvermuxConfig({ configPath: flags.config });
+		process.stdout.write(composeAiContext(config.aiContextSnippets ?? defaultAiContextSnippets));
+	},
+	parameters: {
+		aliases: { c: "config" },
+		flags: { config: {
+			brief: "Configuration file",
+			default: getDefaultConfigPath(),
+			kind: "parsed",
+			parse: String,
+			placeholder: "path"
+		} }
+	},
+	docs: { brief: "Print the configured Overmux AI context" }
+});
+//#endregion
 //#region src/internal/cli/commands/docs.ts
 var resolveInstalledDocsRoot = (moduleUrl) => {
 	const docsRoot = [
@@ -3806,13 +3856,23 @@ var resolveInstalledDocsRoot = (moduleUrl) => {
 	if (!docsRoot) throw new Error("Installed Overmux documentation is missing");
 	return resolve(docsRoot);
 };
-var createDocsCommand = ({ docsRoot, output }) => buildCommand({
+var createDocsPathCommand = ({ docsRoot, output }) => buildCommand({
 	func: () => {
 		output.write(`${resolve(docsRoot)}\n`);
 	},
 	parameters: {},
 	docs: { brief: "Print the installed documentation directory" }
 });
+var createDocsRoute = ({ docsRoot, process }) => buildRouteMap({
+	docs: { brief: "Find documentation and print coding-agent guidance" },
+	routes: {
+		path: createDocsPathCommand({
+			docsRoot,
+			output: process.stdout
+		}),
+		"ai-context": createAiContextCommand(process)
+	}
+});
 //#endregion
 //#region src/internal/cli/commands/init-template.ts
 var initScaffoldPaths = [
@@ -3854,7 +3914,7 @@ var packageJson = (overmuxVersion) => `${JSON.stringify({
 }, null, 2)}\n`;
 var createInitScaffold = ({ overmuxVersion, toolchain }) => ({
 	".gitignore": "node_modules\ndist\n",
-	"AGENTS.md": "Immediately run `overmux ai context` for documentation about Overmux.\n",
+	"AGENTS.md": "Immediately run `overmux docs ai-context` for documentation about Overmux.\n",
 	"CLAUDE.md": "@AGENTS.md\n",
 	...toolchain === "mise" ? { "mise.toml": `[tools]
 node = "22"
@@ -4144,6 +4204,38 @@ var integrationCommand = buildRouteMap({
 	}) }
 });
 //#endregion
+//#region src/internal/cli/commands/instance.ts
+var runInstance = async (flags, output) => {
+	const port = flags.port === void 0 ? void 0 : parsePort(flags.port);
+	if (port instanceof Error) throw port;
+	const identity = createInstanceIdentity((await sendControlRequest(await discoverInstance(port), { type: "get-instance" })).instanceId);
+	output.write(flags.json ? `${JSON.stringify(identity)}\n` : `Instance ID: ${identity.instanceId}\nDeep-link prefix: ${identity.deepLinkPrefix}\n`);
+};
+var createInstanceCommand = (output) => buildCommand({
+	func: (flags) => runInstance(flags, output),
+	parameters: {
+		aliases: { p: "port" },
+		flags: {
+			json: {
+				brief: "Print machine-readable JSON",
+				kind: "boolean",
+				optional: true
+			},
+			port: {
+				brief: "Running local server port",
+				kind: "parsed",
+				optional: true,
+				parse: String
+			}
+		},
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	docs: { brief: "Print the identity of a running Overmux server" }
+});
+//#endregion
 //#region src/internal/shared/routes.ts
 var viteHmrPath = "/_overmux/vite/hmr";
 //#endregion
@@ -4393,6 +4485,7 @@ var announceServeLogin = async ({ createLogin, port, process }) => {
 		...await issueLoginGrant(port),
 		output: process
 	});
+	process.stdout.write(`\nNeed another grant? Run \`overmux auth login --port ${port}\`.\n`);
 };
 var runServe = async ({ environment, flags, process }) => {
 	if (flags.noBuild && !flags.production) throw new Error("--no-build requires --production");
@@ -5053,17 +5146,17 @@ var detectCliEnvironment = async (process = globalThis.process) => {
 var createCliApp = (process = globalThis.process) => buildApplication(buildRouteMap({
 	docs: { brief: "Initialize and manage Overmux applications" },
 	routes: {
-		ai: createAiRoute(process),
 		auth: authRoute,
 		check: checkCommand,
 		call: callCommand,
 		desktop: desktopRoute,
-		docs: createDocsCommand({
+		docs: createDocsRoute({
 			docsRoot: resolveInstalledDocsRoot(import.meta.url),
-			output: process.stdout
+			process
 		}),
 		init: createInitCommand(process),
 		integration: integrationCommand,
+		instance: createInstanceCommand(process.stdout),
 		serve: serveCommand
 	}
 }), {