From b04ff0e6b83567fd12d0243e6d587f5604d0dd02 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Mon, 8 Jun 2026 23:53:54 +0800
Subject: [PATCH] Restore global agent listing (#1420)

---
 packages/cli/src/commands/agent/ls.test.ts | 30 +++++++++++++++++++++-
 packages/cli/src/commands/agent/ls.ts      | 12 +++++----
 packages/cli/tests/04-agent-ls.test.ts     |  2 ++
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/packages/cli/src/commands/agent/ls.test.ts b/packages/cli/src/commands/agent/ls.test.ts
index 479ccfeca..c66b34b94 100644
--- a/packages/cli/src/commands/agent/ls.test.ts
+++ b/packages/cli/src/commands/agent/ls.test.ts
@@ -23,11 +23,39 @@ describe("buildAgentLsFetchOptions", () => {
     });
   });
 
-  it("uses the unscoped archived query for -a", () => {
+  it("fetches global non-archived agents for -g", () => {
+    expect(buildAgentLsFetchOptions({ global: true })).toEqual({});
+  });
+
+  it("keeps -a within the active scope", () => {
     expect(buildAgentLsFetchOptions({ all: true })).toEqual({
+      scope: "active",
       filter: {
         includeArchived: true,
       },
     });
   });
+
+  it("fetches all global agents for -a -g", () => {
+    expect(buildAgentLsFetchOptions({ all: true, global: true })).toEqual({
+      filter: {
+        includeArchived: true,
+      },
+    });
+  });
+
+  it("applies filters to global queries", () => {
+    expect(
+      buildAgentLsFetchOptions({
+        global: true,
+        label: ["surface=workspace"],
+        thinking: " medium ",
+      }),
+    ).toEqual({
+      filter: {
+        labels: { surface: "workspace" },
+        thinkingOptionId: "medium",
+      },
+    });
+  });
 });
diff --git a/packages/cli/src/commands/agent/ls.ts b/packages/cli/src/commands/agent/ls.ts
index f4fa0831e..37f3d5733 100644
--- a/packages/cli/src/commands/agent/ls.ts
+++ b/packages/cli/src/commands/agent/ls.ts
@@ -13,7 +13,7 @@ export function addLsOptions(cmd: Command): Command {
   return cmd
     .description("List agents. By default excludes archived agents.")
     .option("-a, --all", "Include archived agents")
-    .option("-g, --global", "Legacy no-op (kept for compatibility)")
+    .option("-g, --global", "List agents across all directories")
     .option(
       "--label <key=value>",
       "Filter by label (can be used multiple times)",
@@ -107,7 +107,7 @@ export type AgentLsResult = ListResult<AgentListItem>;
 export interface AgentLsOptions extends CommandOptions {
   /** -a: Include archived agents */
   all?: boolean;
-  /** Legacy flag retained for CLI compatibility */
+  /** -g: List agents across all directories */
   global?: boolean;
   /** Filter by specific status */
   status?: string;
@@ -133,7 +133,7 @@ function parseLabelFilters(labels: string[] | undefined): Record<string, string>
 }
 
 export function buildAgentLsFetchOptions(
-  options: Pick<AgentLsOptions, "all" | "label" | "thinking">,
+  options: Pick<AgentLsOptions, "all" | "global" | "label" | "thinking">,
 ): FetchAgentsOptions {
   const labelFilters = parseLabelFilters(options.label);
   const normalizedThinkingOptionId = options.thinking?.trim();
@@ -150,7 +150,7 @@ export function buildAgentLsFetchOptions(
   }
 
   const fetchOptions: FetchAgentsOptions = {};
-  if (!options.all) {
+  if (!options.global) {
     fetchOptions.scope = "active";
   }
   if (Object.keys(daemonFilter).length > 0) {
@@ -162,7 +162,9 @@ export function buildAgentLsFetchOptions(
 /**
  * Agent ls command semantics:
  * - `paseo agent ls`    → active non-archived agents
- * - `paseo agent ls -a` → include archived agents
+ * - `paseo agent ls -g` → global non-archived agents
+ * - `paseo agent ls -a` → active agents, including archived
+ * - `paseo agent ls -ag` → global agents, including archived
  */
 export async function runLsCommand(
   options: AgentLsOptions,
diff --git a/packages/cli/tests/04-agent-ls.test.ts b/packages/cli/tests/04-agent-ls.test.ts
index dee96c4b8..586f5e221 100644
--- a/packages/cli/tests/04-agent-ls.test.ts
+++ b/packages/cli/tests/04-agent-ls.test.ts
@@ -50,6 +50,8 @@ try {
     assert(result.stdout.includes("--all"), "help should mention --all flag");
     assert(result.stdout.includes("-g"), "help should mention -g flag");
     assert(result.stdout.includes("--global"), "help should mention --global flag");
+    assert(result.stdout.includes("across all directories"), "help should describe global scope");
+    assert(!result.stdout.includes("Legacy no-op"), "help should not describe -g as a no-op");
     assert(result.stdout.includes("--host"), "help should mention --host option");
     assert(!result.stdout.includes("--ui"), "help should not mention --ui");
     console.log("✓ paseo ls --help shows options\n");