u-foo 1.8.9 → 1.9.1

package/bin/uclaude.js

@@ -6,8 +6,18 @@
  */
 
 const AgentLauncher = require("../src/agent/launcher");
+const { resolveDefaultManualBootstrap } = require("../src/agent/defaultBootstrap");
 
 const launcher = new AgentLauncher("claude-code", "claude");
-const args = process.argv.slice(2);
+const resolved = resolveDefaultManualBootstrap({
+  projectRoot: process.cwd(),
+  agentType: "claude-code",
+  args: process.argv.slice(2),
+  env: process.env,
+});
 
-launcher.launch(args);
+for (const [key, value] of Object.entries(resolved.env || {})) {
+  process.env[key] = String(value);
+}
+
+launcher.launch(resolved.args);

package/bin/ucodex.js

@@ -6,8 +6,18 @@
  */
 
 const AgentLauncher = require("../src/agent/launcher");
+const { resolveDefaultManualBootstrap } = require("../src/agent/defaultBootstrap");
 
 const launcher = new AgentLauncher("codex", "codex");
-const args = process.argv.slice(2);
+const resolved = resolveDefaultManualBootstrap({
+  projectRoot: process.cwd(),
+  agentType: "codex",
+  args: process.argv.slice(2),
+  env: process.env,
+});
 
-launcher.launch(args);
+for (const [key, value] of Object.entries(resolved.env || {})) {
+  process.env[key] = String(value);
+}
+
+launcher.launch(resolved.args);

package/bin/ufoo.js

@@ -5,7 +5,7 @@ const { runDaemonCli } = require("../src/daemon/run");
 const { runChat } = require("../src/chat");
 const { runInternalRunner } = require("../src/agent/internalRunner");
 const { runPtyRunner } = require("../src/agent/ptyRunner");
-const { resolveGlobalControllerProjectRoot } = require("../src/globalMode");
+const { resolveGlobalControllerProjectRoot } = require("../src/projects");
 
 const rawArgv = process.argv.slice(2);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "1.8.9",
+  "version": "1.9.1",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/agent/defaultBootstrap.js

@@ -0,0 +1,144 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { SHARED_UFOO_PROTOCOL } = require("../group/bootstrap");
+const { getUfooPaths } = require("../ufoo/paths");
+
+function asTrimmedString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function hasArg(args = [], names = []) {
+  if (!Array.isArray(args) || args.length === 0) return false;
+  const known = new Set((Array.isArray(names) ? names : []).map((item) => asTrimmedString(item)).filter(Boolean));
+  return args.some((item) => {
+    const text = asTrimmedString(item);
+    if (!text) return false;
+    if (known.has(text)) return true;
+    const eqIndex = text.indexOf("=");
+    if (eqIndex <= 0) return false;
+    return known.has(text.slice(0, eqIndex).trim());
+  });
+}
+
+function hasMetaCommandArgs(args = []) {
+  return hasArg(args, ["-h", "--help", "-v", "--version"]);
+}
+
+/**
+ * Load the team activity timeline for prompt injection.
+ * The daemon syncs manual inputs every ~30s; bus messages are appended in real-time.
+ * Agent startup only reads — no build triggered here.
+ */
+function loadTeamActivityContext(projectRoot) {
+  try {
+    const { renderTimelineForPrompt } = require("../history/inputTimeline");
+    return renderTimelineForPrompt(projectRoot, 20) || "";
+  } catch {
+    return "";
+  }
+}
+
+function buildDefaultStartupBootstrapPrompt({ agentType = "", projectRoot = "" } = {}) {
+  const normalizedAgent = asTrimmedString(agentType).toLowerCase();
+  const displayAgent = normalizedAgent === "claude-code"
+    ? "Claude"
+    : (normalizedAgent === "codex" ? "Codex" : "agent");
+
+  const segments = [
+    `Session bootstrap for ${displayAgent}.`,
+    "Adopt the following ufoo coordination protocol silently.",
+    "Do not reply to this bootstrap message unless the user explicitly asks about it. After applying it, continue the active task or wait for user input.",
+    SHARED_UFOO_PROTOCOL,
+  ];
+
+  const root = asTrimmedString(projectRoot) || process.cwd();
+  const teamActivity = loadTeamActivityContext(root);
+  if (teamActivity) {
+    segments.push(teamActivity);
+  }
+
+  return segments.join("\n\n");
+}
+
+function defaultBootstrapFile(projectRoot, agentType = "") {
+  const safeAgentType = asTrimmedString(agentType).replace(/[^a-zA-Z0-9._-]/g, "-") || "agent";
+  return path.join(getUfooPaths(projectRoot).agentDir, safeAgentType, "default-bootstrap.md");
+}
+
+function prepareDefaultBootstrapFile({
+  projectRoot,
+  agentType = "",
+  promptText = "",
+  targetFile = "",
+} = {}) {
+  const root = asTrimmedString(projectRoot) || process.cwd();
+  const file = asTrimmedString(targetFile) || defaultBootstrapFile(root, agentType);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, String(promptText || ""), "utf8");
+  return { ok: true, file };
+}
+
+function resolveDefaultManualBootstrap({
+  projectRoot,
+  agentType = "",
+  args = [],
+  env = process.env,
+} = {}) {
+  const normalizedAgent = asTrimmedString(agentType).toLowerCase();
+  const currentEnv = env && typeof env === "object" ? env : {};
+  const currentArgs = Array.isArray(args) ? args.slice() : [];
+  if (
+    currentEnv.UFOO_SKIP_DEFAULT_BOOTSTRAP === "1"
+    || currentEnv.UFOO_STARTUP_BOOTSTRAP_TEXT
+    || hasMetaCommandArgs(currentArgs)
+  ) {
+    return { args: currentArgs, env: {}, mode: "skip" };
+  }
+
+  if (normalizedAgent === "claude-code") {
+    if (hasArg(currentArgs, ["--append-system-prompt", "--system-prompt"])) {
+      return { args: currentArgs, env: {}, mode: "skip" };
+    }
+    const promptText = buildDefaultStartupBootstrapPrompt({ agentType: normalizedAgent, projectRoot });
+    const prepared = prepareDefaultBootstrapFile({
+      projectRoot,
+      agentType: normalizedAgent,
+      promptText,
+    });
+    return {
+      args: [...currentArgs, "--append-system-prompt", prepared.file],
+      env: {},
+      mode: "system-prompt-file",
+      file: prepared.file,
+      promptText,
+    };
+  }
+
+  if (normalizedAgent === "codex") {
+    if (currentArgs.length > 0) {
+      return { args: currentArgs, env: {}, mode: "skip" };
+    }
+    const promptText = buildDefaultStartupBootstrapPrompt({ agentType: normalizedAgent, projectRoot });
+    return {
+      args: currentArgs,
+      env: {
+        UFOO_STARTUP_BOOTSTRAP_TEXT: promptText,
+      },
+      mode: "post-launch-inject",
+      promptText,
+    };
+  }
+
+  return { args: currentArgs, env: {}, mode: "skip" };
+}
+
+module.exports = {
+  hasArg,
+  hasMetaCommandArgs,
+  buildDefaultStartupBootstrapPrompt,
+  defaultBootstrapFile,
+  prepareDefaultBootstrapFile,
+  resolveDefaultManualBootstrap,
+};

package/src/agent/launcher.js

@@ -224,6 +224,42 @@ function computeInjectedSubmitDelayMs(agentType, text) {
   return delayMs;
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function logInjectedCommand(wrapper, source, commandText) {
+  if (!wrapper || !wrapper.logger) return;
+  const text = String(commandText || "");
+  if (!text) return;
+  const logEntry = {
+    ts: Date.now(),
+    dir: "in",
+    data: { text, encoding: "utf8", size: text.length },
+    source,
+  };
+  wrapper.logger.write(JSON.stringify(logEntry) + "\n");
+}
+
+async function injectPtyCommand(wrapper, agentType, commandText, source = "inject") {
+  const text = String(commandText || "");
+  if (!wrapper || !text) return false;
+  const normalizedAgentType = String(agentType || "").trim().toLowerCase();
+  const submitDelayMs = computeInjectedSubmitDelayMs(agentType, text);
+  wrapper.write(text);
+  if (normalizedAgentType === "claude-code") {
+    await sleep(submitDelayMs);
+    wrapper.write("\r");
+  } else {
+    await sleep(submitDelayMs);
+    wrapper.write("\x1b");
+    await sleep(100);
+    wrapper.write("\r");
+  }
+  logInjectedCommand(wrapper, source, text);
+  return true;
+}
+
 async function resolveHostRegistrationData(launchMode) {
   if (launchMode !== "host") {
     return {
@@ -451,6 +487,7 @@ class AgentLauncher {
     return new Promise((resolve, reject) => {
       let buffer = "";
       let settled = false;
+      const registerTimeoutMs = parseInt(process.env.UFOO_REGISTER_TIMEOUT_MS, 10) || 8000;
       const timeout = setTimeout(() => {
         if (settled) return;
         settled = true;
@@ -460,7 +497,7 @@ class AgentLauncher {
           // ignore
         }
         reject(new Error("register_agent timeout"));
-      }, 8000);
+      }, registerTimeoutMs);
 
       const cleanup = () => {
         clearTimeout(timeout);
@@ -607,6 +644,7 @@ class AgentLauncher {
       }
 
       // 7. 启动命令（PTY wrapper或直接spawn）
+      const startupBootstrapText = String(process.env.UFOO_STARTUP_BOOTSTRAP_TEXT || "").trim();
 
       // 7.1 PTY启用条件（显式开关 + 自动检测）
       let shouldUsePty = false;
@@ -704,6 +742,10 @@ class AgentLauncher {
               }
             }
 
+            if (startupBootstrapText && wrapper.pty) {
+              await injectPtyCommand(wrapper, this.agentType, startupBootstrapText, "startup-bootstrap");
+            }
+
             await notifyDaemonAgentReady(daemonSockPath, subscriberId, wrapper.pty ? wrapper.pty.pid : 0);
           });
 
@@ -812,37 +854,8 @@ class AgentLauncher {
                       continue;
                     }
                     // 注入命令到PTY（带延迟确保输入完成）
-                    // Claude Code (Ink TUI) interprets ESC+CR within ~100ms as
-                    // Alt+Enter (newline) instead of two separate keys. Use a
-                    // longer gap so the escape sequence parser times out.
-                    const commandText = String(req.command);
-                    const submitDelayMs = computeInjectedSubmitDelayMs(this.agentType, commandText);
-                    wrapper.write(commandText);
-                    if (normalizedAgentType === "claude-code") {
-                      // Claude Code: send CR directly without ESC.
-                      // ESC before CR is interpreted as Alt+Enter (newline).
-                      setTimeout(() => {
-                        wrapper.write("\r");
-                      }, submitDelayMs);
-                    } else {
-                      // Codex/others: ESC dismisses autocomplete, then CR submits.
-                      setTimeout(() => {
-                        wrapper.write("\x1b");
-                        setTimeout(() => {
-                          wrapper.write("\r");
-                        }, 100);
-                      }, submitDelayMs);
-                    }
+                    void injectPtyCommand(wrapper, this.agentType, req.command, "inject");
                     client.write(JSON.stringify({ ok: true }) + "\n");
-                    if (wrapper.logger) {
-                      const logEntry = {
-                        ts: Date.now(),
-                        dir: "in",
-                        data: { text: req.command, encoding: "utf8", size: req.command.length },
-                        source: "inject",
-                      };
-                      wrapper.logger.write(JSON.stringify(logEntry) + "\n");
-                    }
                   } else if (req.type === PTY_SOCKET_MESSAGE_TYPES.RAW && req.data) {
                     // Raw PTY write (no Enter appended) - for TTY view passthrough
                     wrapper.write(req.data);
@@ -952,5 +965,6 @@ class AgentLauncher {
 AgentLauncher._sanitizeNickname = (nick) => nick.replace(/[^a-zA-Z0-9_-]/g, "");
 AgentLauncher._findPreviousSession = findPreviousSession;
 AgentLauncher._notifyDaemonAgentReady = notifyDaemonAgentReady;
+AgentLauncher._injectPtyCommand = injectPtyCommand;
 
 module.exports = AgentLauncher;

package/src/agent/ufooAgent.js

@@ -11,8 +11,7 @@ const {
 } = require("../code/nativeRunner");
 const { DEFAULT_ASSISTANT_TIMEOUT_MS } = require("../assistant/constants");
 const { normalizeAgentTypeAlias } = require("../bus/utils");
-const { listProjectRuntimes } = require("../projects/registry");
-const { isGlobalControllerProjectRoot } = require("../globalMode");
+const { listProjectRuntimes, isGlobalControllerProjectRoot } = require("../projects");
 
 function loadSessionState(projectRoot) {
   const dir = getUfooPaths(projectRoot).agentDir;

package/src/bus/daemon.js

@@ -19,17 +19,21 @@ function isBusyActivityState(value = "") {
  * Bus Daemon - 监控消息并自动注入命令
  */
 class BusDaemon {
-  constructor(busDir, agentsFile, daemonDir, interval = 2000) {
+  constructor(busDir, agentsFile, daemonDir, interval = 2000, projectRoot = "") {
     this.busDir = busDir;
     this.agentsFile = agentsFile;
     this.interval = interval;
     this.daemonDir = daemonDir;
+    this.projectRoot = projectRoot || path.resolve(busDir, "..", "..");
     this.pidFile = path.join(this.daemonDir, "daemon.pid");
     this.logFile = path.join(this.daemonDir, "daemon.log");
     this.countsDir = path.join(this.daemonDir, "counts", `${process.pid}`);
     this.running = false;
     this.cleanupCounter = 0;
     this.cleanupInterval = 5; // 每 5 个周期清理一次
+    this.timelineSyncCounter = 0;
+    // 每 15 个周期同步一次 manual inputs (~15 × interval, default ~30s)
+    this.timelineSyncInterval = 15;
 
     this.queueManager = new QueueManager(busDir);
     this.injector = new Injector(busDir, agentsFile);
@@ -233,6 +237,13 @@ class BusDaemon {
           this.cleanupCounter = 0;
         }
 
+        // 定期同步 timeline（manual inputs from session files, ~15 × interval）
+        this.timelineSyncCounter++;
+        if (this.timelineSyncCounter >= this.timelineSyncInterval) {
+          this.syncTimeline();
+          this.timelineSyncCounter = 0;
+        }
+
         // 检查所有订阅者的队列
         await this.checkQueues();
       } catch (err) {
@@ -244,6 +255,20 @@ class BusDaemon {
     }
   }
 
+  /**
+   * 增量同步 timeline — 捕获 manual inputs（bus 消息已在 send() 时实时追加）
+   */
+  syncTimeline() {
+    try {
+      const { buildTimeline } = require("../history/inputTimeline");
+      buildTimeline(this.projectRoot);
+    } catch (err) {
+      if (process.env.UFOO_HISTORY_DEBUG === "1") {
+        console.error("[daemon][history] syncTimeline failed:", err.message);
+      }
+    }
+  }
+
   /**
    * 检查所有队列
    */

package/src/bus/index.js

@@ -328,6 +328,23 @@ class EventBus {
           `Event sent: event=${eventName} seq=${result.seq} -> ${result.targets.join(", ")}`
         );
       }
+
+      // Real-time timeline append for message events
+      if (eventName === "message" && message) {
+        try {
+          const { appendBusEntry } = require("../history/inputTimeline");
+          appendBusEntry(this.projectRoot, {
+            seq: result.seq,
+            timestamp: new Date().toISOString(),
+            publisher,
+            target,
+            message,
+          });
+        } catch {
+          // non-critical
+        }
+      }
+
       return result;
     } catch (err) {
       logError(err.message);
@@ -364,7 +381,10 @@ class EventBus {
     console.log();
 
     for (const event of pending) {
-      console.log(`  ${colors.yellow}@you${colors.reset} from ${colors.cyan}${event.publisher}${colors.reset}`);
+      const publisherMeta = this.busData.agents?.[event.publisher];
+      const nick = publisherMeta?.nickname;
+      const fromLabel = nick ? `${event.publisher}(${nick})` : event.publisher;
+      console.log(`  ${colors.yellow}[ufoo]<from:${fromLabel}>${colors.reset}`);
       console.log(`  Type: ${event.type}/${event.event}`);
       console.log(`  Content: ${JSON.stringify(event.data)}`);
       console.log();
@@ -731,7 +751,7 @@ class EventBus {
 
       if (countAfter > countBefore) {
         await sleep(50);
-        const daemon = new BusDaemon(this.busDir, this.agentsFile, this.paths.busDaemonDir, 2000);
+        const daemon = new BusDaemon(this.busDir, this.agentsFile, this.paths.busDaemonDir, 2000, this.projectRoot);
         await daemon.injector.inject(target, options.command || "");
         if (options.shake !== false) {
           const tty = daemon.injector.readTty(target);
@@ -829,7 +849,7 @@ class EventBus {
    */
   async daemon(action, options = {}) {
     const interval = options.interval || 2000;
-    const daemon = new BusDaemon(this.busDir, this.agentsFile, this.paths.busDaemonDir, interval);
+    const daemon = new BusDaemon(this.busDir, this.agentsFile, this.paths.busDaemonDir, interval, this.projectRoot);
 
     switch (action) {
       case "start":

package/src/chat/commandExecutor.js

@@ -6,8 +6,9 @@ const { runGroupCoreCommand } = require("../cli/groupCoreCommands");
 const { loadConfig: loadProjectConfig, saveConfig: saveProjectConfig, loadGlobalUcodeConfig, saveGlobalUcodeConfig } = require("../config");
 const { resolveTransport } = require("../code/nativeRunner");
 const { parseIntervalMs, formatIntervalMs } = require("./cronScheduler");
-const { isGlobalControllerProjectRoot, resolveGlobalControllerUfooDir } = require("../globalMode");
+const { isGlobalControllerProjectRoot, resolveGlobalControllerUfooDir } = require("../projects");
 const { loadPromptProfileRegistry } = require("../group/promptProfiles");
+const { resolveSoloAgentType } = require("../solo/commands");
 
 function defaultCreateDoctor(projectRoot) {
   const UfooDoctor = require("../doctor");
@@ -528,10 +529,15 @@ function createCommandExecutor(options = {}) {
       return;
     }
 
-    const target = String(args[0] || "").trim();
-    const profile = String(args[1] || "").trim();
+    const target = action === "assign"
+      ? String(args[1] || "").trim()
+      : String(args[0] || "").trim();
+    const profile = action === "assign"
+      ? String(args[2] || "").trim()
+      : String(args[1] || "").trim();
     if (!target || !profile) {
-      logMessage("error", "{white-fg}✗{/white-fg} Usage: /role <agent-id|nickname> <prompt-profile>");
+      logMessage("error", "{white-fg}✗{/white-fg} Usage: /role assign <agent-id|nickname> <prompt-profile>");
+      logMessage("error", "       /role <agent-id|nickname> <prompt-profile>");
       logMessage("error", "       /role list");
       return;
     }
@@ -548,6 +554,95 @@ function createCommandExecutor(options = {}) {
     }
   }
 
+  async function handleSoloCommand(args = []) {
+    const subcommand = String(args[0] || "").trim().toLowerCase();
+    if (!subcommand) {
+      logMessage("error", "{white-fg}✗{/white-fg} Usage: /solo <run|list> ...");
+      return;
+    }
+
+    if (subcommand === "list" || subcommand === "ls") {
+      try {
+        const registry = loadPromptProfileRegistry(projectRoot);
+        const profiles = registry.profiles || [];
+        if (profiles.length === 0) {
+          logMessage("system", "{white-fg}⚙{/white-fg} No solo roles found.");
+          return;
+        }
+        logMessage("system", `{white-fg}⚙{/white-fg} Available solo roles (${profiles.length}):`);
+        for (const p of profiles) {
+          const aliases = p.aliases && p.aliases.length > 0 ? ` {gray-fg}(${p.aliases.join(", ")}){/gray-fg}` : "";
+          const source = p.source ? ` {cyan-fg}[${p.source}]{/cyan-fg}` : "";
+          const summary = p.summary ? `  ${p.summary}` : "";
+          logMessage("system", `  {bold}${escapeBlessed(p.id)}{/bold}${aliases}${source}`);
+          if (summary) {
+            logMessage("system", `    ${escapeBlessed(summary)}`);
+          }
+        }
+      } catch (err) {
+        logMessage("error", `{white-fg}✗{/white-fg} Failed to list solo roles: ${escapeBlessed(err.message)}`);
+      }
+      return;
+    }
+
+    if (subcommand !== "run") {
+      logMessage("error", `{white-fg}✗{/white-fg} Unknown solo action: ${escapeBlessed(subcommand)}`);
+      return;
+    }
+
+    const profile = String(args[1] || "").trim();
+    if (!profile) {
+      logMessage("error", "{white-fg}✗{/white-fg} Usage: /solo run <prompt-profile> [agent=codex|claude|ucode] [nickname=<name>] [scope=inplace|window]");
+      return;
+    }
+
+    const parsedOptions = {};
+    for (let i = 2; i < args.length; i += 1) {
+      const arg = args[i];
+      if (arg.includes("=")) {
+        const [key, value] = arg.split("=", 2);
+        parsedOptions[key] = value;
+      }
+    }
+
+    function normalizeLaunchScopeOption(value, fallback = "inplace") {
+      const raw = String(value || "").trim().toLowerCase();
+      if (!raw) return fallback;
+      if (raw === "inplace" || raw === "same" || raw === "current" || raw === "tab" || raw === "pane") {
+        return "inplace";
+      }
+      if (raw === "window" || raw === "separate" || raw === "new" || raw === "new-window" || raw === "external") {
+        return "window";
+      }
+      return "";
+    }
+
+    const config = loadConfig(projectRoot);
+    const agent = resolveSoloAgentType(config, parsedOptions.agent || parsedOptions.type || "");
+    const nickname = String(parsedOptions.nickname || "").trim();
+    const scopeRaw = parsedOptions.scope || parsedOptions.launch_scope || "";
+    const launchScope = normalizeLaunchScopeOption(scopeRaw, "inplace");
+    if (scopeRaw && !launchScope) {
+      logMessage("error", "{white-fg}✗{/white-fg} scope must be inplace|window");
+      return;
+    }
+
+    try {
+      send({
+        type: IPC_REQUEST_TYPES.LAUNCH_AGENT,
+        agent: agent === "ucode" ? "ufoo" : agent,
+        count: 1,
+        nickname,
+        prompt_profile: profile,
+        launch_scope: launchScope,
+        ...collectHostLaunchRequestContext(),
+      });
+      schedule(requestStatus, 1000);
+    } catch (err) {
+      logMessage("error", `{white-fg}✗{/white-fg} Solo launch failed: ${escapeBlessed(err.message)}`);
+    }
+  }
+
   async function handleResumeCommand(args = []) {
     const action = String(args[0] || "").toLowerCase();
     if (action === "list" || action === "ls") {
@@ -1218,6 +1313,9 @@ function createCommandExecutor(options = {}) {
       case "role":
         await handleRoleCommand(args);
         return true;
+      case "solo":
+        await handleSoloCommand(args);
+        return true;
       case "cron":
         await handleCronCommand(args);
         return true;
@@ -1250,6 +1348,7 @@ function createCommandExecutor(options = {}) {
     handleResumeCommand,
     handleProjectCommand,
     handleRoleCommand,
+    handleSoloCommand,
     handleCronCommand,
     handleGroupCommand,
     handleSettingsCommand,

package/src/chat/commands.js

@@ -67,7 +67,15 @@ const COMMAND_TREE = {
   "/role": {
     desc: "Assign preset role to an existing agent",
     children: {
-      list: { desc: "List available prompt profiles" },
+      assign: { desc: "Assign a role to an existing agent", order: 1 },
+      list: { desc: "List available prompt profiles", order: 2 },
+    },
+  },
+  "/solo": {
+    desc: "Solo role agent operations",
+    children: {
+      run: { desc: "Launch a solo role agent", order: 1 },
+      list: { desc: "List available solo roles", order: 2 },
     },
   },
   "/resume": {
@@ -111,10 +119,20 @@ function buildCommandRegistry(tree) {
       const entry = { cmd, desc: node.desc || "" };
       if (node.children) {
         entry.subcommands = Object.keys(node.children)
-          .sort((a, b) => a.localeCompare(b, "en", { sensitivity: "base" }))
+          .sort((a, b) => {
+            const aNode = node.children[a] || {};
+            const bNode = node.children[b] || {};
+            const aOrder = Number.isFinite(aNode.order) ? aNode.order : Number.POSITIVE_INFINITY;
+            const bOrder = Number.isFinite(bNode.order) ? bNode.order : Number.POSITIVE_INFINITY;
+            if (aOrder !== bOrder) return aOrder - bOrder;
+            return a.localeCompare(b, "en", { sensitivity: "base" });
+          })
           .map((sub) => ({
             cmd: sub,
             desc: (node.children[sub] && node.children[sub].desc) || "",
+            order: Number.isFinite(node.children[sub] && node.children[sub].order)
+              ? node.children[sub].order
+              : undefined,
           }));
       }
       return entry;