@rudderhq/cli 0.3.5-canary.2 → 0.3.5-canary.21

package/dist/index.js

@@ -768,7 +768,7 @@ var init_adapter_skills = __esm({
 
 // ../packages/shared/dist/validators/chat.js
 import { z as z4 } from "zod";
-var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, addChatMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema;
+var chatConversationStatusSchema, chatIssueCreationModeSchema, chatMessageRoleSchema, chatMessageKindSchema, chatMessageStatusSchema, chatContextEntityTypeSchema, createChatContextLinkSchema, createChatConversationSchema, setChatProjectContextSchema, updateChatConversationSchema, addChatMessageSchema, chatRichReferenceDisplaySchema, chatIssueIdentifierSchema, chatAskUserIdentifierSchema, chatAskUserOptionSchema, chatAskUserQuestionSchema, chatAskUserRequestSchema, chatIssueRichReferenceSchema, chatIssueCommentRichReferenceSchema, chatRichReferenceSchema, chatRichReferencesSchema, chatAutomationCreateSchema, createChatAttachmentMetadataSchema, chatIssueProposalSchema, convertChatToIssueSchema, chatOperationProposalSchema, resolveChatOperationProposalSchema, updateChatConversationUserStateSchema, updateMessengerThreadUserStateSchema, createMessengerCustomGroupSchema, updateMessengerCustomGroupSchema, reorderMessengerCustomGroupsSchema, assignMessengerCustomGroupEntrySchema, reorderMessengerCustomGroupEntriesSchema;
 var init_chat = __esm({
   "../packages/shared/dist/validators/chat.js"() {
     "use strict";
@@ -951,6 +951,25 @@ var init_chat = __esm({
     updateMessengerThreadUserStateSchema = z4.object({
       pinned: z4.boolean().optional()
     });
+    createMessengerCustomGroupSchema = z4.object({
+      name: z4.string().trim().min(1).max(80),
+      icon: z4.string().trim().min(1).max(24).optional().nullable()
+    });
+    updateMessengerCustomGroupSchema = z4.object({
+      name: z4.string().trim().min(1).max(80).optional(),
+      icon: z4.string().trim().min(1).max(24).optional().nullable(),
+      collapsed: z4.boolean().optional(),
+      sortOrder: z4.number().int().min(0).optional()
+    });
+    reorderMessengerCustomGroupsSchema = z4.object({
+      groupIds: z4.array(z4.string().uuid()).max(200)
+    });
+    assignMessengerCustomGroupEntrySchema = z4.object({
+      threadKey: z4.string().trim().min(1).max(240)
+    });
+    reorderMessengerCustomGroupEntriesSchema = z4.object({
+      threadKeys: z4.array(z4.string().trim().min(1).max(240)).max(500)
+    });
   }
 });
 
@@ -1107,7 +1126,7 @@ var init_organization_intelligence_profile = __esm({
     upsertOrganizationIntelligenceProfileSchema = z7.object({
       agentRuntimeType: z7.enum(AGENT_RUNTIME_TYPES),
       agentRuntimeConfig: organizationIntelligenceProfileConfigSchema.default({}),
-      status: organizationIntelligenceProfileStatusSchema.optional().default("configured")
+      status: organizationIntelligenceProfileStatusSchema.optional().default("disabled")
     });
   }
 });
@@ -7054,15 +7073,6 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "",
   "When you create or copy a skill under `$AGENT_HOME/skills/<slug>/`, check the agent's Skills snapshot before claiming it will load in future runs. If it is installed but not enabled, say exactly that future runs will not load it until enabled, and offer to enable it with `rudder agent skills enable <agent-id> <selection-ref>` when you have permission.",
   "",
-  "## Self-Improvement and Automation Requests",
-  "",
-  "When the user asks to improve, optimize, or remember a workflow, treat it as a request to update the durable operating surface that controls future behavior, not as a request for advice only. First identify the surface: an automation, an agent-private skill, an organization skill, memory, instructions, or a project Library document. Then inspect the existing surface and apply the smallest governed update you are authorized to make.",
-  "",
-  "- For automation behavior, read the current automation or chat context first, then use the Rudder automation commands such as `rudder automation list`, `rudder automation get`, and `rudder automation update` instead of only describing what should change.",
-  "- For skill improvement, find real evidence before editing: use `rudder runs by-skill <skill> --org-id <id>` or `rudder runs list --used-skill <skill>` to locate runs, then inspect the relevant transcripts or errors with `rudder runs transcript` / `rudder runs errors`.",
-  "- For personal memory, use the `para-memory-files` skill; for agent-private skills, prefer `rudder agent skills create ... --enable` or editing `$AGENT_HOME/skills`; for organization skills, follow the bundled `rudder` skill's organization-skill workflow.",
-  "- Do not silently mutate broad shared behavior when the request is ambiguous, risky, or outside your authority. Make the proposed change reviewable, ask for approval when needed, and report exactly which durable surface changed.",
-  "",
   "When you write issue comments or chat replies, match the language of the user's or board's most recent substantive message unless they explicitly ask for a different language.",
   "When you mention a web page, issue URL, external dashboard, or other user-openable target in an issue comment or chat reply, write it as a clickable Markdown link with a descriptive label, for example `[NameSilo transfer page](https://www.namesilo.com/account_domain_manage_transfer.php)`. Do not put action URLs in backticks or code blocks unless you are showing literal code or a command.",
   "",
@@ -7070,16 +7080,16 @@ var RUDDER_AGENT_OPERATING_CONTRACT = [
   "",
   "When you mention Rudder entities in any user-visible Markdown output, prefer Rudder's renderable Markdown link syntax over plain IDs, bare URLs, or backticked references so the UI can render chips and navigate correctly.",
   "",
-  "- Issues: use `[<identifier-or-title>](issue://<issue-id>)`; include `?c=<comment-id>` when linking to a specific comment.",
-  "- Agents: use `[<agent-name>](agent://<agent-id>)` for reference-only links. In issue comments, use `[<agent-name>](agent://<agent-id>?intent=wake)` only when you intentionally want to wake that agent for attention or collaboration.",
-  "- Projects: use `[<project-name>](project://<project-id>)` when citing a Rudder project.",
-  "- Chat threads: use `[<chat-title>](chat://<conversation-id>)` when citing a Rudder chat conversation.",
-  "- Skills: use `[$<skill-ref>](<path-or-url-ending-in-SKILL.md>)` when citing a Rudder skill reference; the label may use `org/<org-url-key>/<skill-slug>`, `org/<org-url-key>/<agent-url-key>/<skill-slug>`, or `rudder/<skill-slug>`.",
+  "- Issues: use `[](issue://<issue-id>)`; include `?c=<comment-id>` when linking to a specific comment.",
+  "- Agents: use `[](agent://<agent-id>)` for reference-only links. In issue comments, use `[](agent://<agent-id>?intent=wake)` only when you intentionally want to wake that agent for attention or collaboration.",
+  "- Projects: use `[](project://<project-id>)` when citing a Rudder project.",
+  "- Chat threads: use `[](chat://<conversation-id>)` when citing a Rudder chat conversation.",
+  "- Skills: use `[](skill://<skill-ref>)` when citing a Rudder skill reference. The skill ref may be an org skill, agent skill, bundled Rudder skill, or local-machine skill ref; the UI resolves the display label when metadata is available.",
   '- Library files: use the `markdownLink` returned by `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json`; do not hand-write `library-entry://...` links, and treat `library-file://...` as legacy path syntax only.',
   "",
   "Write these as normal Markdown links, not inside code spans or code blocks, unless you are literally documenting the syntax.",
   "",
-  "Mention-triggered comment wakes arrive with `RUDDER_WAKE_COMMENT_ID`; read that wake comment before acting. Issue comments can wake an agent only with an explicit wake-intent agent link serialized as `agent://agent-id?intent=wake`. Plain structured links such as `agent://agent-id` are reference-only links for rendering and navigation, and plain text agent names are not wake requests. Use wake-intent links only when you intentionally want to wake another agent for attention or collaboration; omit the wake intent for ordinary references. Mentioning an agent requests attention or collaboration; it does not transfer issue ownership unless the comment also makes an explicit handoff and normal checkout rules allow it.",
+  "Mention-triggered comment wakes arrive with `RUDDER_WAKE_COMMENT_ID`; read that wake comment before acting. Issue comments can wake an agent only with an explicit wake-intent agent link serialized as `agent://agent-id?intent=wake`. Plain structured links such as `agent://agent-id` are reference-only links for rendering and navigation, and plain text agent names are not wake requests. Use wake-intent links only when you intentionally want to wake another agent for attention or collaboration; omit the wake intent for ordinary references. Mentioning an agent requests attention or collaboration; it does not transfer issue ownership unless the comment also makes an explicit handoff and normal checkout rules allow it. If a comment wakes you on an issue not assigned to you, including user-owned or unassigned issues, and the comment does not explicitly ask you to implement, modify files, close the issue, or take ownership, strictly respond to the comment's content instead of turning the wake into issue execution; answer questions, acknowledge corrections, explain status, or handle only the narrow action the comment explicitly requests.",
   "",
   "When an issue comment, done comment, or blocker comment cites visual evidence from a local screenshot/image path, attach the image with the Rudder CLI `--image <path>` option instead of leaving only the filesystem path in the text.",
   "",
@@ -7111,7 +7121,7 @@ var RUDDER_AGENT_HEARTBEAT_INSTRUCTION = [
   "1. Identify yourself and inspect wake context, including `RUDDER_TASK_ID`, `RUDDER_WAKE_REASON`, `RUDDER_WAKE_COMMENT_ID`, and `RUDDER_APPROVAL_ID` when present.",
   "2. Handle approval follow-up first: read the approval and linked issues, then close resolved work or comment on what remains.",
   "3. Inspect your Rudder inbox. Prioritize reviewer rows in `in_review` or `blocked`, then assignee `in_progress`, then assignee `todo`. Do not look for unassigned work.",
-  "4. For mention wakes, read the wake comment before acting. Mentions request attention; they do not transfer ownership unless the comment explicitly says so.",
+  "4. For mention wakes, read the wake comment before acting. Mentions request attention; they do not transfer ownership unless the comment explicitly says so. If the issue is not assigned to you, including user-owned or unassigned issues, and the comment does not explicitly ask you to implement, modify files, close the issue, or take ownership, respond to the comment itself instead of executing the whole issue.",
   "5. Checkout before doing assignee task work. A `409` means another agent owns the task; do not retry it.",
   "6. Load compact issue context, do one bounded useful chunk, and preserve evidence.",
   "7. Before exiting active work, leave exactly one durable signal: progress, done, blocked, explicit handoff, or structured review decision.",
@@ -7547,6 +7557,18 @@ var AGENT_CLI_CAPABILITIES = [
     requiresRunId: false,
     attachesRunIdWhenAvailable: true
   },
+  {
+    id: "user.activity",
+    command: "rudder user activity --user me --since today --json",
+    category: "user",
+    description: "Read a user-centered activity ledger with safe excerpts and provenance across chats, issue comments, approval comments, and user actor activity.",
+    mutating: false,
+    contract: "agent-v1",
+    requiresOrgId: true,
+    requiresAgentId: false,
+    requiresRunId: false,
+    attachesRunIdWhenAvailable: false
+  },
   {
     id: "library.file.list",
     command: "rudder library file list [directory]",
@@ -8145,6 +8167,7 @@ var CATEGORY_TITLES = {
   runs: "Runs",
   approval: "Approval",
   skill: "Skill",
+  user: "User",
   library: "Library"
 };
 function getAgentCliCapabilities() {
@@ -9489,6 +9512,11 @@ function formatChatMessage(row, maxOutputChars = 1200) {
     role: row.role,
     kind: row.kind,
     status: row.status,
+    ...row.runId ? {
+      runId: row.runId,
+      runCommand: `rudder runs get ${row.runId}`,
+      transcriptCommand: `rudder runs transcript ${row.runId}`
+    } : {},
     createdAt: row.createdAt,
     body: clip(row.body, 220),
     transcriptEntries: row.transcriptSummary?.entryCount ?? row.transcript?.length ?? 0,
@@ -9501,6 +9529,11 @@ function formatChatTranscriptMessage(row, maxChars) {
     role: row.role,
     kind: row.kind,
     status: row.status,
+    ...row.runId ? {
+      runId: row.runId,
+      runCommand: `rudder runs get ${row.runId}`,
+      transcriptCommand: `rudder runs transcript ${row.runId}`
+    } : {},
     createdAt: row.createdAt,
     body: clip(row.body, 220)
   };
@@ -12241,6 +12274,59 @@ function parseCsv5(value) {
   return rows.length > 0 ? rows : void 0;
 }
 
+// src/commands/client/user.ts
+function appendParam(params, key, value) {
+  if (value && value.trim()) params.set(key, value.trim());
+}
+function formatUserActivityItem(item) {
+  const time = new Date(item.occurredAt);
+  const hhmm = Number.isNaN(time.getTime()) ? item.occurredAt : time.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  const related = item.related.find((entry) => entry.type === "issue" || entry.type === "chat" || entry.type === "approval");
+  const label = related?.label || related?.id || item.source.id;
+  const excerpt = item.excerpt ? ` - ${item.excerpt}` : "";
+  return `${hhmm} ${item.kind} ${label}: ${item.summary}${excerpt}`;
+}
+function registerUserCommands(program) {
+  const user = program.command("user").description("User-oriented Rudder context commands");
+  addCommonClientOptions(
+    user.command("activity").description("List a user's recent Rudder activity ledger").option("-O, --org-id <id>", "Organization ID").option("--user <id>", "User ID or 'me'", "me").option("--since <value>", "Start time: today, 24h, 7d, or ISO timestamp", "today").option("--until <value>", "End time: ISO timestamp").option("--include <items>", "Comma-separated sources: chat,comments,issues,approvals,activity").option("--agent-id <id>", "Filter by related agent ID").option("--project-id <id>", "Filter by related project ID").option("--issue-id <id>", "Filter by related issue ID").option("--limit <n>", "Maximum items to return").option("--cursor <cursor>", "Pagination cursor from a prior response").action(async (opts) => {
+      try {
+        const ctx = resolveCommandContext(opts, { requireCompany: true });
+        const userId = opts.user?.trim() || "me";
+        const params = new URLSearchParams();
+        appendParam(params, "since", opts.since);
+        appendParam(params, "until", opts.until);
+        appendParam(params, "include", opts.include);
+        appendParam(params, "agentId", opts.agentId);
+        appendParam(params, "projectId", opts.projectId);
+        appendParam(params, "issueId", opts.issueId);
+        appendParam(params, "limit", opts.limit);
+        appendParam(params, "cursor", opts.cursor);
+        const query = params.toString();
+        const path23 = `/api/orgs/${ctx.orgId}/users/${encodeURIComponent(userId)}/activity-ledger${query ? `?${query}` : ""}`;
+        const result = await ctx.api.get(path23);
+        if (ctx.json) {
+          printOutput(result, { json: true });
+          return;
+        }
+        if (!result?.items?.length) {
+          printOutput([], { json: false });
+          return;
+        }
+        for (const item of result.items) {
+          console.log(formatUserActivityItem(item));
+        }
+        if (result.nextCursor) {
+          console.log(`nextCursor=${result.nextCursor}`);
+        }
+      } catch (err) {
+        handleCommandError(err);
+      }
+    }),
+    { includeCompany: false }
+  );
+}
+
 // src/commands/configure.ts
 init_home();
 init_schema();
@@ -13035,7 +13121,7 @@ init_install2();
 init_install();
 import * as p15 from "@clack/prompts";
 import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createWriteStream, constants as fsConstants, mkdirSync, readFileSync as readFileSync2 } from "node:fs";
 import { access, chmod, copyFile, cp, mkdir as mkdir3, mkdtemp, readdir as readdir3, readFile as readFile6, rm as rm2, stat as stat4, utimes, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
@@ -13171,6 +13257,8 @@ var DEFAULT_DESKTOP_ASSET_CACHE_MAX_ENTRIES = 2;
 var DEFAULT_DESKTOP_ASSET_CACHE_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1e3;
 var DEFAULT_DESKTOP_ASSET_CACHE_MAX_BYTES = 768 * 1024 * 1024;
 var DEFAULT_DESKTOP_ASSET_CACHE_KEEP_PREVIOUS = 1;
+var DESKTOP_INSTALL_LOCK_TIMEOUT_MS = 60 * 60 * 1e3;
+var DESKTOP_INSTALL_LOCK_POLL_MS = 250;
 function normalizeProgressTotal(totalBytes) {
   return typeof totalBytes === "number" && Number.isFinite(totalBytes) && totalBytes > 0 ? totalBytes : null;
 }
@@ -13814,6 +13902,70 @@ async function pathExists2(targetPath) {
     return false;
   }
 }
+function resolveDesktopInstallLockPath(paths) {
+  const installRootHash = createHash("sha256").update(path21.resolve(paths.installRoot)).digest("hex").slice(0, 16);
+  return path21.join(path21.dirname(paths.appPath), `.rudder-desktop-install-${installRootHash}.lock`);
+}
+async function readDesktopInstallLock(lockPath) {
+  try {
+    const parsed = JSON.parse(await readFile6(lockPath, "utf8"));
+    if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0 || typeof parsed.lockId !== "string" || typeof parsed.installRoot !== "string" || typeof parsed.createdAt !== "string") {
+      return null;
+    }
+    return {
+      lockId: parsed.lockId,
+      pid: parsed.pid,
+      installRoot: parsed.installRoot,
+      createdAt: parsed.createdAt
+    };
+  } catch {
+    return null;
+  }
+}
+async function withDesktopInstallLock(paths, fn, options = {}) {
+  const lockPath = resolveDesktopInstallLockPath(paths);
+  const lockDir = path21.dirname(lockPath);
+  const timeoutMs = options.timeoutMs ?? DESKTOP_INSTALL_LOCK_TIMEOUT_MS;
+  const pollMs = options.pollMs ?? DESKTOP_INSTALL_LOCK_POLL_MS;
+  const startedAt = Date.now();
+  const payload = {
+    lockId: randomUUID(),
+    pid: process.pid,
+    installRoot: path21.resolve(paths.installRoot),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await mkdir3(lockDir, { recursive: true });
+  while (true) {
+    try {
+      await writeFile3(lockPath, `${JSON.stringify(payload, null, 2)}
+`, { encoding: "utf8", flag: "wx" });
+      break;
+    } catch (error) {
+      const err = error;
+      if (err.code !== "EEXIST") throw error;
+      const existing = await readDesktopInstallLock(lockPath);
+      const stale = !existing || !processExists(existing.pid);
+      if (stale) {
+        await rm2(lockPath, { force: true });
+        continue;
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new Error(
+          `Timed out waiting for Rudder Desktop install lock for ${paths.appPath}. Held by pid ${existing.pid} for ${existing.installRoot}.`
+        );
+      }
+      await delay2(pollMs);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    const existing = await readDesktopInstallLock(lockPath);
+    if (existing?.lockId === payload.lockId) {
+      await rm2(lockPath, { force: true });
+    }
+  }
+}
 function runChecked(command, args, options = {}) {
   const result = spawnSync3(command, args, {
     encoding: "utf8",
@@ -14266,152 +14418,154 @@ async function startCommand(opts) {
       p15.outro(pc15.green("Dry run complete."));
       return;
     }
-    const directReleaseVersion = resolveDesktopReleaseVersion(tag);
-    const progressFactory = desktopProgressJson ? createDesktopProgressFactory() : createByteProgress;
-    let release = null;
-    try {
-      release = await runStartPhase(
-        "Resolving Desktop release...",
-        "Desktop release resolved.",
-        () => fetchGithubRelease(repo, tag),
-        desktopProgressJson ? "resolving_release" : null
-      );
-    } catch (error) {
-      if (!directReleaseVersion) throw error;
-      p15.log.warn(
-        `Desktop release metadata could not be resolved; falling back to deterministic download URLs. ${formatFetchError(error)}`
-      );
-    }
-    const releaseTag = release?.tag_name ?? (directReleaseVersion ? tag : null);
-    if (!releaseTag) {
-      throw new Error(`Unable to resolve Rudder Desktop release tag for ${repo}@${tag}.`);
-    }
-    const assetCandidates = resolveDesktopAssetCandidates({
-      releaseAssets: release?.assets ?? [],
-      target,
-      repo,
-      tag,
-      directReleaseVersion,
-      allowShellAssets: runtimeSupportsShellAssets
-    });
-    if (assetCandidates.length === 0) {
-      throw new Error(`No Rudder Desktop portable asset found for ${target.platform}/${target.arch} in ${repo}@${releaseTag}.`);
-    }
-    const checksumAsset = selectChecksumAsset(release?.assets ?? []) ?? (directReleaseVersion ? buildGithubReleaseAsset(repo, tag, DESKTOP_CHECKSUM_ASSET_NAME) : null);
-    const checksums = await downloadChecksums(checksumAsset, outputDir, progressFactory);
-    let selectedCandidate;
-    try {
-      selectedCandidate = selectChecksummedDesktopAssetCandidate(assetCandidates, checksums);
-    } catch (error) {
-      throw new Error(`No checksummed Rudder Desktop asset found for ${target.platform}/${target.arch} in ${repo}@${releaseTag}.`);
-    }
-    for (const warning of selectedCandidate.warnings) p15.log.warn(warning);
-    let selectedAsset = selectedCandidate.asset;
-    let selectedAssetKind = selectedCandidate.kind;
-    let expectedChecksum = selectedCandidate.expectedChecksum;
-    const metadata = await readInstallMetadata(installPaths.metadataPath);
-    if (isInstalledDesktopCurrent(metadata, releaseTag, selectedAsset.name, expectedChecksum) && await pathExists2(installPaths.executablePath)) {
-      p15.log.success(`Rudder Desktop is already installed at ${pc15.cyan(installPaths.appPath)}.`);
-      await runStartPhase(
-        "Refreshing Desktop launchers...",
-        "Desktop launchers ready.",
-        async () => {
-          await removeMacQuarantine(installPaths, target);
-          await createPlatformLaunchers(installPaths, target);
-        },
-        desktopProgressJson ? "preparing_restart" : null
-      );
-    } else {
-      let cachedAsset;
+    await withDesktopInstallLock(installPaths, async () => {
+      const directReleaseVersion = resolveDesktopReleaseVersion(tag);
+      const progressFactory = desktopProgressJson ? createDesktopProgressFactory() : createByteProgress;
+      let release = null;
       try {
-        cachedAsset = await downloadDesktopAssetWithCache(selectedAsset, expectedChecksum, {
-          outputDir,
-          progressFactory
-        });
+        release = await runStartPhase(
+          "Resolving Desktop release...",
+          "Desktop release resolved.",
+          () => fetchGithubRelease(repo, tag),
+          desktopProgressJson ? "resolving_release" : null
+        );
       } catch (error) {
-        const fullCandidate = assetCandidates.find((candidate) => candidate.kind === "full");
-        if (selectedAssetKind !== "shell" || !fullCandidate) throw error;
+        if (!directReleaseVersion) throw error;
         p15.log.warn(
-          `Layered Desktop shell asset download failed; falling back to the full portable asset. ${formatFetchError(error)}`
+          `Desktop release metadata could not be resolved; falling back to deterministic download URLs. ${formatFetchError(error)}`
         );
-        selectedAsset = fullCandidate.asset;
-        selectedAssetKind = fullCandidate.kind;
-        expectedChecksum = resolveAssetChecksum(checksums, selectedAsset.name);
-        cachedAsset = await downloadDesktopAssetWithCache(selectedAsset, expectedChecksum, {
-          outputDir,
-          progressFactory
-        });
       }
-      if (cachedAsset.cacheStatus === "hit") {
-        p15.log.success(`Desktop asset cache hit at ${pc15.cyan(cachedAsset.path)}.`);
-        if (desktopProgressJson) {
+      const releaseTag = release?.tag_name ?? (directReleaseVersion ? tag : null);
+      if (!releaseTag) {
+        throw new Error(`Unable to resolve Rudder Desktop release tag for ${repo}@${tag}.`);
+      }
+      const assetCandidates = resolveDesktopAssetCandidates({
+        releaseAssets: release?.assets ?? [],
+        target,
+        repo,
+        tag,
+        directReleaseVersion,
+        allowShellAssets: runtimeSupportsShellAssets
+      });
+      if (assetCandidates.length === 0) {
+        throw new Error(`No Rudder Desktop portable asset found for ${target.platform}/${target.arch} in ${repo}@${releaseTag}.`);
+      }
+      const checksumAsset = selectChecksumAsset(release?.assets ?? []) ?? (directReleaseVersion ? buildGithubReleaseAsset(repo, tag, DESKTOP_CHECKSUM_ASSET_NAME) : null);
+      const checksums = await downloadChecksums(checksumAsset, outputDir, progressFactory);
+      let selectedCandidate;
+      try {
+        selectedCandidate = selectChecksummedDesktopAssetCandidate(assetCandidates, checksums);
+      } catch (error) {
+        throw new Error(`No checksummed Rudder Desktop asset found for ${target.platform}/${target.arch} in ${repo}@${releaseTag}.`);
+      }
+      for (const warning of selectedCandidate.warnings) p15.log.warn(warning);
+      let selectedAsset = selectedCandidate.asset;
+      let selectedAssetKind = selectedCandidate.kind;
+      let expectedChecksum = selectedCandidate.expectedChecksum;
+      const metadata = await readInstallMetadata(installPaths.metadataPath);
+      if (isInstalledDesktopCurrent(metadata, releaseTag, selectedAsset.name, expectedChecksum) && await pathExists2(installPaths.executablePath)) {
+        p15.log.success(`Rudder Desktop is already installed at ${pc15.cyan(installPaths.appPath)}.`);
+        await runStartPhase(
+          "Refreshing Desktop launchers...",
+          "Desktop launchers ready.",
+          async () => {
+            await removeMacQuarantine(installPaths, target);
+            await createPlatformLaunchers(installPaths, target);
+          },
+          desktopProgressJson ? "preparing_restart" : null
+        );
+      } else {
+        let cachedAsset;
+        try {
+          cachedAsset = await downloadDesktopAssetWithCache(selectedAsset, expectedChecksum, {
+            outputDir,
+            progressFactory
+          });
+        } catch (error) {
+          const fullCandidate = assetCandidates.find((candidate) => candidate.kind === "full");
+          if (selectedAssetKind !== "shell" || !fullCandidate) throw error;
+          p15.log.warn(
+            `Layered Desktop shell asset download failed; falling back to the full portable asset. ${formatFetchError(error)}`
+          );
+          selectedAsset = fullCandidate.asset;
+          selectedAssetKind = fullCandidate.kind;
+          expectedChecksum = resolveAssetChecksum(checksums, selectedAsset.name);
+          cachedAsset = await downloadDesktopAssetWithCache(selectedAsset, expectedChecksum, {
+            outputDir,
+            progressFactory
+          });
+        }
+        if (cachedAsset.cacheStatus === "hit") {
+          p15.log.success(`Desktop asset cache hit at ${pc15.cyan(cachedAsset.path)}.`);
+          if (desktopProgressJson) {
+            writeDesktopProgress({
+              phase: "downloading_asset",
+              message: `Desktop asset cache hit for ${selectedAsset.name}.`,
+              percent: 100
+            });
+          }
+        }
+        const checksum = await runStartPhase(
+          "Verifying Desktop checksum...",
+          `Verified ${pc15.cyan(path21.basename(cachedAsset.path))}.`,
+          () => assertChecksumMatch(cachedAsset.path, expectedChecksum),
+          desktopProgressJson ? "verifying_checksum" : null
+        );
+        if (desktopProgressJson && opts.desktopWaitForApply === true) {
           writeDesktopProgress({
-            phase: "downloading_asset",
-            message: `Desktop asset cache hit for ${selectedAsset.name}.`,
+            phase: "ready_to_install",
+            message: "Desktop update is downloaded and verified.",
             percent: 100
           });
+          await waitForDesktopApplySignal();
+          writeDesktopProgress({
+            phase: "preparing_restart",
+            message: "Applying Desktop update..."
+          });
         }
+        await runStartPhase(
+          "Replacing existing Rudder Desktop if needed...",
+          "Existing Desktop install is ready for replacement.",
+          () => prepareForDesktopReplace(installPaths, target, { waitForActiveRuns: opts.waitForActiveRuns === true }),
+          desktopProgressJson ? opts.waitForActiveRuns === true ? "waiting_for_active_runs" : "preparing_restart" : null
+        );
+        await runStartPhase(
+          "Installing portable Desktop app...",
+          `Installed Rudder Desktop to ${pc15.cyan(installPaths.appPath)}.`,
+          () => installPortableDesktop(cachedAsset.path, installPaths, target),
+          desktopProgressJson ? "preparing_restart" : null
+        );
+        await runStartPhase(
+          "Preparing Desktop launchers...",
+          "Desktop launchers ready.",
+          async () => {
+            await removeMacQuarantine(installPaths, target);
+            await createPlatformLaunchers(installPaths, target);
+          },
+          desktopProgressJson ? "preparing_restart" : null
+        );
+        await writeInstallMetadata(installPaths, releaseTag, selectedAsset.name, checksum, selectedAssetKind);
       }
-      const checksum = await runStartPhase(
-        "Verifying Desktop checksum...",
-        `Verified ${pc15.cyan(path21.basename(cachedAsset.path))}.`,
-        () => assertChecksumMatch(cachedAsset.path, expectedChecksum),
-        desktopProgressJson ? "verifying_checksum" : null
-      );
-      if (desktopProgressJson && opts.desktopWaitForApply === true) {
-        writeDesktopProgress({
-          phase: "ready_to_install",
-          message: "Desktop update is downloaded and verified.",
-          percent: 100
-        });
-        await waitForDesktopApplySignal();
-        writeDesktopProgress({
-          phase: "preparing_restart",
-          message: "Applying Desktop update..."
-        });
-      }
-      await runStartPhase(
-        "Replacing existing Rudder Desktop if needed...",
-        "Existing Desktop install is ready for replacement.",
-        () => prepareForDesktopReplace(installPaths, target, { waitForActiveRuns: opts.waitForActiveRuns === true }),
-        desktopProgressJson ? opts.waitForActiveRuns === true ? "waiting_for_active_runs" : "preparing_restart" : null
-      );
-      await runStartPhase(
-        "Installing portable Desktop app...",
-        `Installed Rudder Desktop to ${pc15.cyan(installPaths.appPath)}.`,
-        () => installPortableDesktop(cachedAsset.path, installPaths, target),
-        desktopProgressJson ? "preparing_restart" : null
-      );
-      await runStartPhase(
-        "Preparing Desktop launchers...",
-        "Desktop launchers ready.",
-        async () => {
-          await removeMacQuarantine(installPaths, target);
-          await createPlatformLaunchers(installPaths, target);
-        },
-        desktopProgressJson ? "preparing_restart" : null
-      );
-      await writeInstallMetadata(installPaths, releaseTag, selectedAsset.name, checksum, selectedAssetKind);
-    }
-    const desktopAssetPrune = await maybePruneDesktopAssetCache({
-      protectedChecksums: [expectedChecksum]
-    });
-    if (desktopAssetPrune) {
-      if (desktopAssetPrune.deleted.length > 0) {
-        p15.log.success(
-          `Pruned ${desktopAssetPrune.deleted.length} old Desktop asset cache(s), freed ${formatBytes(desktopAssetPrune.freedBytes)}.`
+      const desktopAssetPrune = await maybePruneDesktopAssetCache({
+        protectedChecksums: [expectedChecksum]
+      });
+      if (desktopAssetPrune) {
+        if (desktopAssetPrune.deleted.length > 0) {
+          p15.log.success(
+            `Pruned ${desktopAssetPrune.deleted.length} old Desktop asset cache(s), freed ${formatBytes(desktopAssetPrune.freedBytes)}.`
+          );
+        }
+        for (const warning of desktopAssetPrune.warnings) p15.log.warn(warning);
+      }
+      if (opts.open !== false) {
+        await runStartPhase(
+          "Launching Rudder Desktop...",
+          "Rudder Desktop launched.",
+          () => launchDesktop(installPaths, target),
+          desktopProgressJson ? "closing" : null
         );
       }
-      for (const warning of desktopAssetPrune.warnings) p15.log.warn(warning);
-    }
-    if (opts.open !== false) {
-      await runStartPhase(
-        "Launching Rudder Desktop...",
-        "Rudder Desktop launched.",
-        () => launchDesktop(installPaths, target),
-        desktopProgressJson ? "closing" : null
-      );
-    }
+    });
   }
   p15.outro(pc15.green("Rudder start complete."));
 }
@@ -14511,6 +14665,7 @@ function createProgram() {
   registerAgentCommands(program);
   registerApprovalCommands(program);
   registerActivityCommands(program);
+  registerUserCommands(program);
   registerDashboardCommands(program);
   registerSkillCommands(program);
   registerLibraryCommands(program);