@tyvm/knowhow 0.0.147 → 0.0.149

package/src/agents/tools/startAgentTask.ts

@@ -34,6 +34,20 @@ export interface StartAgentTaskParams {
   _ctx?: { caller?: any; taskId?: string; [key: string]: any };
 }
 
+export interface StartAgentTaskResult {
+  success: boolean;
+  status: "started" | "completed" | "failed";
+  taskId: string;
+  pid?: number;
+  syncFs: boolean;
+  syncReady: boolean;
+  agentDir?: string;
+  logPath: string;
+  parentTaskId?: string;
+  exitCode?: number | null;
+  error?: string;
+}
+
 const PROCESSES_DIR = path.join(process.cwd(), ".knowhow", "processes");
 const AGENTS_DIR = path.join(process.cwd(), ".knowhow", "processes", "agents");
 
@@ -100,7 +114,7 @@ function subagentCapabilitiesNote(): string {
  *   .knowhow/processes/agents/{taskId}/input.txt
  * The agent will pick up the new content and process it as a new message.
  */
-export async function startAgentTask(params: StartAgentTaskParams): Promise<string> {
+export async function startAgentTask(params: StartAgentTaskParams): Promise<StartAgentTaskResult> {
   const {
     messageId,
     prompt,
@@ -138,7 +152,9 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
   // Default filesystem synchronization ON unless the caller explicitly opts out
   // (syncFs: false) or is using a messageId-based web sync. This ensures spawned
   // subagents always appear in `knowhow agents list` and can be attached/tailed.
-  const useSyncFs = syncFs !== false && !messageId;
+  // If the caller explicitly passes syncFs: true, honor it even when a messageId
+  // is also provided (messageId handles remote sync; syncFs handles local fs sync).
+  const useSyncFs = syncFs === true ? true : (syncFs !== false && !messageId);
 
   // Use provided taskId if given, otherwise generate one from the prompt
   const taskId = providedTaskId ?? generateTaskId(prompt);
@@ -161,7 +177,8 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
 
   if (messageId) {
     args.push("--message-id", messageId);
-  } else if (useSyncFs) {
+  }
+  if (useSyncFs) {
     args.push("--sync-fs");
   }
   // When syncRemote is requested, pass it through so the spawned agent pushes
@@ -235,43 +252,54 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
   child.stdin!.write(promptWithCaps, "utf8");
   child.stdin!.end();
 
-  return new Promise<string>((resolve) => {
+  return new Promise<StartAgentTaskResult>((resolve) => {
     let settled = false;
-    const done = (msg: string) => {
+    let exited = false;
+    const done = (result: StartAgentTaskResult) => {
       if (settled) return;
       settled = true;
       try { fs.closeSync(fd); } catch {}
-      resolve(msg);
+      resolve(result);
     };
 
     child.once("error", (e) => {
-      done(`Failed to start agent: ${String(e)}\nLogs: ${logPath}`);
+      done({
+        success: false, status: "failed", taskId, pid, syncFs: useSyncFs,
+        syncReady: false, agentDir: useSyncFs ? agentTaskDir : undefined,
+        logPath, parentTaskId, error: String(e),
+      });
     });
 
-    const syncFsNote = useSyncFs
-      ? `\nTask ID: ${taskId}\nAgent dir: ${agentTaskDir}\n` +
-        `To send agent messages, write to: ${agentTaskDir}/input.txt\n` +
-        `To check status, read: ${agentTaskDir}/status.txt\n`
-      : "";
-
     child.once("exit", (code) => {
-      done(
-        `Agent finished with exit code ${code}.\nLogs: ${logPath}\n` +
-        syncFsNote
-      );
+      exited = true;
+      done({
+        success: code === 0, status: code === 0 ? "completed" : "failed",
+        taskId, pid, syncFs: useSyncFs,
+        syncReady: useSyncFs && fs.existsSync(path.join(agentTaskDir, "metadata.json")),
+        agentDir: useSyncFs ? agentTaskDir : undefined, logPath, parentTaskId,
+        exitCode: code, ...(code === 0 ? {} : { error: `Agent exited with code ${code}` }),
+      });
     });
 
     if (!waitForCompletion) {
-      // Give the agent 5 seconds to finish before detaching (fire-and-forget mode)
-      const detachTime = 5 * 1000;
-      setTimeout(() => {
-        try { child.unref(); } catch {}
-        done(
-          `Agent started (pid=${pid}), running in background.\n` +
-          `Logs: ${logPath}\n` +
-          syncFsNote
-        );
-      }, detachTime);
+      // A spawn is not the same as an initialized fs-sync agent. Poll briefly
+      // so callers can distinguish those states without parsing log prose.
+      const deadline = Date.now() + (useSyncFs ? 5000 : 100);
+      const acknowledge = () => {
+        if (settled || exited) return;
+        const syncReady = useSyncFs && fs.existsSync(path.join(agentTaskDir, "metadata.json"));
+        if (!useSyncFs || syncReady || Date.now() >= deadline) {
+          try { child.unref(); } catch {}
+          done({
+            success: true, status: "started", taskId, pid, syncFs: useSyncFs,
+            syncReady, agentDir: useSyncFs ? agentTaskDir : undefined,
+            logPath, parentTaskId,
+          });
+          return;
+        }
+        setTimeout(acknowledge, 100);
+      };
+      setTimeout(acknowledge, 50);
     }
   });
 }

package/src/ai.ts

@@ -65,13 +65,16 @@ export async function singlePrompt(
     // This ensures generate agent runs produce readable output and are observable
     // via `knowhow agents list/tail/status`, matching `knowhow agent --input` behaviour.
     const { startAgentTask } = await import("./agents/tools/startAgentTask");
-    return startAgentTask({
+    const result = await startAgentTask({
       agentName: agent,
       prompt: userPrompt,
       model: model || undefined,
       waitForCompletion: true,
       ...(agentOptions ?? {}),
     });
+    // singlePrompt is a text API; keep generation pipelines compatible while
+    // the tool itself exposes a structured orchestration result.
+    return JSON.stringify(result);
   }
 
   if (!model) {

package/src/auth/keyAuth.ts

@@ -81,7 +81,7 @@ export async function authenticateWithKey(
   }
 }
 
-/** Register an Ed25519 CLI-auth key using the JWT obtained by browser PKCE. */
+/** Register an Ed25519 identity; the backend derives its scope from the source JWT. */
 export async function registerPublicKey(
   jwt: string,
   publicKeyBase64: string,
@@ -109,7 +109,13 @@ export async function registerPublicKey(
 
 export function storeJwt(jwt: string): void {
   const directory = path.dirname(JWT_FILE_PATH);
-  fs.mkdirSync(directory, { recursive: true });
-  fs.writeFileSync(JWT_FILE_PATH, jwt, { mode: 0o600 });
-  fs.chmodSync(JWT_FILE_PATH, 0o600);
+  const temporaryPath = `${JWT_FILE_PATH}.${process.pid}.tmp`;
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.writeFileSync(temporaryPath, jwt, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporaryPath, JWT_FILE_PATH);
+    fs.chmodSync(JWT_FILE_PATH, 0o600);
+  } finally {
+    fs.rmSync(temporaryPath, { force: true });
+  }
 }

package/src/auth/registerIdentity.ts

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { getOrCreatePublicKey } from "./keyManager";
+import { registerPublicKey, exchangePublicKeyJwt, storeJwt } from "./keyAuth";
+import { getConfig, updateConfig } from "../config";
+
+export interface RegisterIdentityOptions {
+  /** Optional Ed25519 private-key path. Defaults to ~/.knowhow/keys/id_ed25519. */
+  identityPath?: string;
+  /** API base URL. Defaults to KNOWHOW_API_URL or the production public API. */
+  apiUrl?: string;
+}
+
+/** Decode an unverified JWT payload for local routing information only. */
+export function decodeJwtPayload(jwt: string): Record<string, unknown> {
+  const parts = jwt.split(".");
+  if (parts.length !== 3) throw new Error("Invalid JWT format: expected 3 parts");
+  const base64 = (parts[1] ?? "").replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  try {
+    const payload: unknown = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new Error();
+    return payload as Record<string, unknown>;
+  } catch {
+    throw new Error("Invalid JWT payload: could not parse JSON");
+  }
+}
+
+export function extractOrgIdFromJwt(jwt: string): string {
+  const payload = decodeJwtPayload(jwt);
+  const orgId = payload["org"] ?? payload["orgId"] ?? payload["org_id"] ?? payload["organizationId"];
+  if (typeof orgId !== "string" || !orgId) {
+    throw new Error("JWT does not contain an organization claim (expected org, orgId, org_id, or organizationId)");
+  }
+  return orgId;
+}
+
+/**
+ * Register a CLI identity using the JWT already stored in the current project's
+ * .knowhow/.jwt, then replace that JWT with one obtained via key authentication.
+ * This is intentionally generic: authorization scope is derived by the backend
+ * from the verified source JWT.
+ */
+export async function registerIdentity(options: RegisterIdentityOptions = {}): Promise<void> {
+  const apiUrl = options.apiUrl ?? process.env.KNOWHOW_API_URL ?? "https://api.knowhow.tyvm.ai";
+  const jwtPath = path.join(process.cwd(), ".knowhow", ".jwt");
+  if (!fs.existsSync(jwtPath)) throw new Error(`JWT file not found: ${jwtPath}`);
+  const sourceJwt = fs.readFileSync(jwtPath, "utf8").trim();
+  if (!sourceJwt) throw new Error(`JWT file is empty: ${jwtPath}`);
+
+  const orgId = extractOrgIdFromJwt(sourceJwt);
+  const keyPair = getOrCreatePublicKey(options.identityPath);
+  await registerPublicKey(sourceJwt, keyPair.publicKeyBase64, apiUrl);
+  const identityJwt = await exchangePublicKeyJwt(orgId, apiUrl, options.identityPath);
+  storeJwt(identityJwt);
+
+  const config = await getConfig();
+  if (!config.modelProviders) config.modelProviders = [];
+  if (!config.modelProviders.some((provider: { provider: string }) => provider.provider === "knowhow")) {
+    config.modelProviders.push({ provider: "knowhow" });
+  }
+  config.orgId = orgId;
+  config.cliIdentityPath = path.resolve(options.identityPath ?? keyPair.privateKeyPath);
+  await updateConfig(config);
+
+  console.log(`✅ Identity registered. Identity: ${keyPair.fingerprint}, Org: ${orgId}`);
+}

package/src/chat/CliChatService.ts

@@ -20,6 +20,12 @@ import fs from "fs";
 import path from "path";
 import { services } from "../services";
 import { logger } from "../logger";
+import { ModuleExtension } from "../services/ExtensionsService";
+
+export interface ChatExtension extends ModuleExtension {
+  type: "chat";
+  commands: ChatCommand[];
+}
 
 export class CliChatService implements ChatService {
   private context: ChatContext;
@@ -59,6 +65,7 @@ export class CliChatService implements ChatService {
         }
       },
     });
+    this.refreshExtensions();
     this.loadInputHistory();
 
     // Set up callback to add entries to inputHistory immediately when user presses Enter
@@ -151,7 +158,12 @@ export class CliChatService implements ChatService {
   }
 
   registerCommand(command: ChatCommand): void {
-    this.commands.push(command);
+    const existing = this.commands.findIndex((item) => item.name === command.name);
+    if (existing >= 0) {
+      this.commands[existing] = command;
+    } else {
+      this.commands.push(command);
+    }
   }
 
   registerMode(mode: ChatMode): void {
@@ -163,9 +175,17 @@ export class CliChatService implements ChatService {
   }
 
   getCommands(): ChatCommand[] {
+    this.refreshExtensions();
     return this.commands;
   }
 
+  /** Re-read the registry so services created before module setup still work. */
+  refreshExtensions(): void {
+    for (const extension of services().Extensions.list<ChatExtension>("chat")) {
+      for (const command of extension.commands ?? []) this.registerCommand(command);
+    }
+  }
+
   /**
    * Get commands available in the current mode
    */
@@ -176,6 +196,7 @@ export class CliChatService implements ChatService {
   }
 
   getCommandsForActiveModes(): ChatCommand[] {
+    this.refreshExtensions();
     const activeModes = this.modes
       .filter((mode) => mode.active)
       .map((mode) => mode.name);
@@ -216,7 +237,7 @@ export class CliChatService implements ChatService {
       const command = availableCommands.find((cmd) => cmd.name === commandName);
 
       if (command) {
-        const result = await command.handler(args);
+        const result = await command.handler(args, this);
 
         // If handler returns a CommandResult and it's not handled, pass to modules
         if (result && typeof result === "object" && "handled" in result) {

package/src/chat/modules/AgentModule.ts

@@ -8,6 +8,7 @@ import {
   TaskRegistry,
   SyncedAgentWatcher,
   SyncerService,
+  AgentService,
 } from "../../services/index";
 import { AttachableAgent } from "../../services/SyncedAgentWatcher";
 import * as fs from "fs";
@@ -77,10 +78,15 @@ export class AgentModule extends BaseChatModule {
     | { toolCall?: string; toolUsed?: string; agentSay?: string; done: string }
     | undefined;
 
+  private agentService: AgentService;
+  private eventService: EventService;
+
   constructor() {
     super();
     this.taskRegistry = new TaskRegistry();
     this.sessionManager = new SessionManager();
+    this.agentService = services().Agents;
+    this.eventService = services().Events;
   }
 
   /**
@@ -327,7 +333,7 @@ export class AgentModule extends BaseChatModule {
     await super.initialize(service);
 
     // Set up plugin log event handler - use setListener so re-init doesn't double-subscribe
-    const Events = services().Events;
+    const Events = this.eventService;
     Events.setListener(
       { key: "agentModule:pluginLog", event: Events.eventTypes.pluginLog },
       (logEvent: any) => {
@@ -405,7 +411,7 @@ export class AgentModule extends BaseChatModule {
         // Set selected agent in context and enable agent mode
         if (context) {
           // Create a temporary agent instance to read its default model/provider
-          const agentContext = services().Agents.getAgentContext();
+          const agentContext = this.agentService.getAgentContext();
           const tempAgent = createAgent(
             agentName as AgentName,
             agentContext
@@ -427,6 +433,25 @@ export class AgentModule extends BaseChatModule {
           this.chatService.setMode("agent");
         }
 
+        console.log(
+          `Agent mode enabled. Selected agent: ${agentName}. Type your task to get started.`
+        );
+      } else if (this.agentService.listAgents().includes(agentName)) {
+        // Config agent from knowhow.json
+        if (context) {
+          const configAgent = this.agentService.getAgent<BaseAgent>(agentName);
+          context.selectedAgent = configAgent;
+          context.agentMode = true;
+          context.currentAgent = agentName;
+          const clientInfo = await configAgent.clientService.getClient(
+            undefined,
+            configAgent.getModel()
+          );
+          context.currentModel = clientInfo.model;
+          context.currentProvider = clientInfo.provider;
+
+          this.chatService.setMode("agent");
+        }
         console.log(
           `Agent mode enabled. Selected agent: ${agentName}. Type your task to get started.`
         );
@@ -601,12 +626,16 @@ export class AgentModule extends BaseChatModule {
    */
   async handleAgentsCommand(args: string[]): Promise<void> {
     try {
-      const agentNames = Object.keys(agentConstructors);
+      const builtinNames = Object.keys(agentConstructors);
+      const configAgentNames = this.agentService.listAgents();
+      // Merge, deduplicate, preserving built-ins first
+      const agentNames = [...new Set([...builtinNames, ...configAgentNames])];
 
       if (agentNames.length > 0) {
         console.log("\nAvailable agents:");
         agentNames.forEach((name) => {
-          console.log(`  - ${name}`);
+          const isConfig = !builtinNames.includes(name);
+          console.log(`  - ${name}${isConfig ? " (config)" : ""}`);
         });
         console.log("─".repeat(80), "\n");
 
@@ -700,11 +729,14 @@ export class AgentModule extends BaseChatModule {
       const agentName = session.agentName || context.currentAgent;
       const previousAgentMode = context?.agentMode;
 
-      if (!agentName || !agentConstructors[agentName as AgentName]) {
+      if (!agentName) {
         console.error(`Agent ${agentName} not found.`);
         return;
       }
 
+      // setupAgent resolves both built-in agents and custom ConfigAgents. Do
+      // not reject config-defined agents here before it gets that opportunity.
+
       // Start agent with Knowhow task context and restored message history
       const remoteTaskId = asRemoteTaskId(session.knowhowTaskId);
       const { agent, taskId } = await this.setupAgent({
@@ -817,7 +849,7 @@ export class AgentModule extends BaseChatModule {
     enabledTools?: string[];
   }) {
     const { input, chatHistory = [], agentName } = options;
-    const agentContext = services().Agents.getAgentContext();
+    const agentContext = this.agentService.getAgentContext();
 
     // Resolve agent: built-in agents first, then fall back to ConfigAgents from knowhow.json
     let agent: BaseAgent;
@@ -826,7 +858,7 @@ export class AgentModule extends BaseChatModule {
     } else {
       // Try to find a ConfigAgent registered via loadAgentsFromConfig (from knowhow.json agents[])
       try {
-        const configAgent = services().Agents.getAgent(options.agentName);
+        const configAgent = this.agentService.getAgent(options.agentName);
         agent = configAgent as unknown as BaseAgent;
       } catch {
         throw new Error(

package/src/chat/modules/InternalChatModule.ts

@@ -10,6 +10,7 @@ import { SystemModule } from "./SystemModule";
 import { SetupModule } from "./SetupModule";
 import { CustomCommandsModule } from "./CustomCommandsModule";
 import { ShellCommandModule } from "./ShellCommandModule";
+import { ToolCommandModule } from "./ToolCommandModule";
 import { RendererModule } from "./RendererModule";
 import { SessionsModule } from "./SessionsModule";
 import { RemoteSyncModule } from "./RemoteSyncModule";
@@ -32,6 +33,7 @@ export class InternalChatModule implements ChatModule {
   private setupModule: SetupModule;
   private customCommandsModule = new CustomCommandsModule();
   private shellCommandModule = new ShellCommandModule();
+  private toolCommandModule = new ToolCommandModule();
   private rendererModule: RendererModule;
   private remoteSyncModule: RemoteSyncModule;
 
@@ -61,6 +63,7 @@ export class InternalChatModule implements ChatModule {
     await this.customCommandsModule.initialize(chatService);
     await this.remoteSyncModule.initialize(chatService);
     await this.shellCommandModule.initialize(chatService);
+    await this.toolCommandModule.initialize(chatService);
     await this.clipboardImageModule.initialize(chatService);
     
     // Register our own commands (exit and multi) - not duplicated by BaseChatModule
@@ -93,6 +96,7 @@ export class InternalChatModule implements ChatModule {
       ...this.setupModule.getCommands(),
       ...this.customCommandsModule.getCommands(),
       ...this.shellCommandModule.getCommands(),
+      ...this.toolCommandModule.getCommands(),
       ...this.rendererModule.getCommands(),
       ...this.remoteSyncModule.getCommands(),
       {
@@ -120,6 +124,7 @@ export class InternalChatModule implements ChatModule {
       ...this.setupModule.getModes(),
       ...this.customCommandsModule.getModes(),
       ...this.shellCommandModule.getModes(),
+      ...this.toolCommandModule.getModes(),
       ...this.rendererModule.getModes(),
     ];
   }

package/src/chat/modules/ToolCommandModule.ts

@@ -0,0 +1,102 @@
+import { ToolCall } from "../../clients/types";
+import { services } from "../../services";
+import { BaseChatModule } from "./BaseChatModule";
+import { ChatCommand, ChatContext, CommandResult } from "../types";
+
+/** Execute registered tools directly from interactive chat. */
+export class ToolCommandModule extends BaseChatModule {
+  name = "tool-command";
+  description = "Execute a tool with /tool";
+
+  public getCommands(): ChatCommand[] {
+    return [
+      {
+        name: "tool",
+        description: "Execute a tool call from JSON",
+        handler: (args: string[]) => this.handleToolCommand(args),
+      },
+    ];
+  }
+
+  private async handleToolCommand(args: string[]): Promise<CommandResult> {
+    const input = args.join(" ").trim();
+    if (!input) {
+      console.log('Usage: /tool {"name":"toolName","arguments":{"key":"value"}}');
+      return { handled: true };
+    }
+
+    let toolCall: ToolCall;
+    try {
+      toolCall = this.parseToolCall(input);
+    } catch (error: any) {
+      console.error(`Invalid tool call JSON: ${error.message}`);
+      return { handled: true };
+    }
+
+    const tools = this.chatService.getTools() || services().Tools;
+    if (!tools) {
+      console.error("Tool execution failed: no tool service is available");
+      return { handled: true };
+    }
+
+    try {
+      const context = this.chatService.getContext();
+      const result = await tools.callTool(
+        toolCall,
+        tools.getFunctionNames(),
+        {
+          caller: context.selectedAgent,
+          taskId: context.activeAgentTaskId,
+        }
+      );
+
+      const toolError = result.toolMessages?.find(
+        (message: any) => message.name === "error"
+      );
+      if (toolError) {
+        console.error(`Tool execution failed: ${toolError.content}`);
+      } else {
+        const output = result.functionResp;
+        console.log(
+          typeof output === "object"
+            ? JSON.stringify(output, null, 2)
+            : String(output)
+        );
+      }
+    } catch (error: any) {
+      console.error(`Tool execution failed: ${error.message || String(error)}`);
+    }
+
+    return { handled: true };
+  }
+
+  private parseToolCall(input: string): ToolCall {
+    const parsed = JSON.parse(input);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+
+    const fn = parsed.function || parsed;
+    if (!fn || typeof fn.name !== "string" || !fn.name.trim()) {
+      throw new Error('expected a non-empty "name" (or "function.name")');
+    }
+
+    const args = fn.arguments === undefined ? {} : fn.arguments;
+    if (typeof args !== "string" && (args === null || typeof args !== "object")) {
+      throw new Error('"arguments" must be a JSON object, array, or JSON string');
+    }
+
+    return {
+      id: typeof parsed.id === "string" ? parsed.id : `chat_tool_${Date.now()}`,
+      type: "function",
+      function: {
+        name: fn.name,
+        arguments: typeof args === "string" ? args : JSON.stringify(args),
+      },
+    };
+  }
+
+  async handleInput(input: string, context: ChatContext): Promise<boolean> {
+    return false;
+  }
+}

package/src/chat/modules/index.ts

@@ -4,4 +4,5 @@ export { AgentModule } from './AgentModule';
 export { VoiceModule } from './VoiceModule';
 export { InternalChatModule } from './InternalChatModule';
 export { ShellCommandModule } from './ShellCommandModule';
+export { ToolCommandModule } from './ToolCommandModule';
 export { RendererModule } from './RendererModule';

package/src/chat/types.ts

@@ -45,7 +45,7 @@ export interface CommandResult {
 export interface ChatCommand {
   name: string;
   description: string;
-  handler: (args: string[]) => Promise<void | CommandResult>;
+  handler: (args: string[], chatService?: ChatService) => Promise<void | CommandResult>;
   modes?: string[]; // Commands can specify which modes they're available in
 }
 

package/src/cli.ts

@@ -62,6 +62,7 @@ import { addSkillsCommand } from "./commands/skills";
 import { addAgentsCommand } from "./commands/agents";
 import { addHashCommand } from "./commands/hash";
 import { addSandboxCommand } from "./commands/sandbox";
+import { addProcessesCommand } from "./commands/processes";
 
 // Handle unhandled promise rejections gracefully — particularly from MCP SDK
 // which fires errors via event emitters that can bypass Promise.allSettled.
@@ -131,15 +132,21 @@ async function main() {
   addAgentsCommand(program, getChatService);
   addHashCommand(program);
   addSandboxCommand(program);
+  addProcessesCommand(program);
 
   // Load global modules early (before parse) so they can register CLI subcommands.
   // We pass only the Program in context — no services are spun up at this stage.
   // Each module's command action is responsible for calling setupServices() as needed.
   try {
     const globalConfig = await getGlobalConfig();
+    const globalModules = [...new Set(globalConfig.modules || [])];
+    const localModules = [...new Set(config.modules || [])];
+    // Local modules take precedence: if a module appears in both global and
+    // local configs, use the local version so it resolves against local
+    // node_modules first. This prevents duplicate command registration errors.
     const allModulePaths = [
-      ...(globalConfig.modules || []),
-      ...(config.modules || []),
+      ...globalModules.filter((m) => !localModules.includes(m)),
+      ...localModules,
     ];
     if (allModulePaths.length) {
       const earlyModulesService = new ModulesService();