feat(cli): add agent ps command

Implements the `paseo agent ps` command for listing agents:
- Lists running agents by default
- `-a, --all` flag to include archived agents
- `--status <status>` filter by agent status
- `--cwd <path>` filter by working directory
- Supports all output formats (table, json, yaml, quiet)
- Graceful error handling when daemon not running

Output format:
AGENT ID    NAME              PROVIDER  STATUS   CWD                    CREATED
a1b2c3d     🎭 Test fixer     claude    running  ~/dev/paseo            2 minutes ago

Phase 3 of CLI implementation (TDD checklist 3.1-3.5)

packages/cli/src/cli.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander'
+import { createAgentCommand } from './commands/agent/index.js'
 import { createDaemonCommand } from './commands/daemon/index.js'
 
 const VERSION = '0.1.0'
@@ -16,15 +17,10 @@ export function createCli(): Command {
     .option('--no-headers', 'omit table headers')
     .option('--no-color', 'disable colored output')
 
-  // Placeholder subcommands
-  program
-    .command('agent')
-    .description('Manage agents')
-    .action(() => {
-      console.log('agent command (not yet implemented)')
-    })
+  // Agent commands
+  program.addCommand(createAgentCommand())
 
-  // Real daemon command
+  // Daemon commands
   program.addCommand(createDaemonCommand())
 
   program

packages/cli/src/commands/agent/index.ts

@@ -0,0 +1,18 @@
+import { Command } from 'commander'
+import { runPsCommand } from './ps.js'
+import { withOutput } from '../../output/index.js'
+
+export function createAgentCommand(): Command {
+  const agent = new Command('agent').description('Manage agents')
+
+  agent
+    .command('ps')
+    .description('List agents')
+    .option('-a, --all', 'include archived agents')
+    .option('--status <status>', 'filter by status (running, idle, error)')
+    .option('--cwd <path>', 'filter by working directory')
+    .option('--host <host>', 'Daemon host:port (default: localhost:6767)')
+    .action(withOutput(runPsCommand))
+
+  return agent
+}

packages/cli/src/commands/agent/ps.ts

@@ -0,0 +1,159 @@
+import type { Command } from 'commander'
+import { connectToDaemon, getDaemonHost } from '../../utils/client.js'
+import type { CommandOptions, ListResult, OutputSchema, CommandError } from '../../output/index.js'
+
+/** Minimal agent snapshot type (from daemon client) */
+interface AgentSnapshot {
+  id: string
+  provider: string
+  cwd: string
+  createdAt: string
+  status: string
+  title: string | null
+  archivedAt?: string | null
+}
+
+/** Agent list item for display */
+export interface AgentListItem {
+  id: string
+  shortId: string
+  name: string
+  provider: string
+  status: string
+  cwd: string
+  created: string
+}
+
+/** Helper to get relative time string */
+function relativeTime(date: Date | string): string {
+  const now = Date.now()
+  const then = new Date(date).getTime()
+  const seconds = Math.floor((now - then) / 1000)
+
+  if (seconds < 60) return 'just now'
+  if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes ago`
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago`
+  return `${Math.floor(seconds / 86400)} days ago`
+}
+
+/** Shorten home directory in path */
+function shortenPath(path: string): string {
+  const home = process.env.HOME
+  if (home && path.startsWith(home)) {
+    return '~' + path.slice(home.length)
+  }
+  return path
+}
+
+/** Schema for agent ps output */
+export const agentPsSchema: OutputSchema<AgentListItem> = {
+  idField: 'shortId',
+  columns: [
+    { header: 'AGENT ID', field: 'shortId', width: 12 },
+    { header: 'NAME', field: 'name', width: 20 },
+    { header: 'PROVIDER', field: 'provider', width: 10 },
+    {
+      header: 'STATUS',
+      field: 'status',
+      width: 10,
+      color: (value) => {
+        if (value === 'running') return 'green'
+        if (value === 'idle') return 'yellow'
+        if (value === 'error') return 'red'
+        return undefined
+      },
+    },
+    { header: 'CWD', field: 'cwd', width: 30 },
+    { header: 'CREATED', field: 'created', width: 15 },
+  ],
+}
+
+/** Transform agent snapshot to AgentListItem */
+function toListItem(agent: AgentSnapshot): AgentListItem {
+  return {
+    id: agent.id,
+    shortId: agent.id.slice(0, 7),
+    name: agent.title ?? '-',
+    provider: agent.provider,
+    status: agent.status,
+    cwd: shortenPath(agent.cwd),
+    created: relativeTime(agent.createdAt),
+  }
+}
+
+export type AgentPsResult = ListResult<AgentListItem>
+
+export interface AgentPsOptions extends CommandOptions {
+  all?: boolean
+  status?: string
+  cwd?: string
+}
+
+export async function runPsCommand(
+  options: AgentPsOptions,
+  _command: Command
+): Promise<AgentPsResult> {
+  const host = getDaemonHost({ host: options.host as string | undefined })
+
+  let client
+  try {
+    client = await connectToDaemon({ host: options.host as string | undefined })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const error: CommandError = {
+      code: 'DAEMON_NOT_RUNNING',
+      message: `Cannot connect to daemon at ${host}: ${message}`,
+      details: 'Start the daemon with: paseo daemon start',
+    }
+    throw error
+  }
+
+  try {
+    // Request session state to get agent information
+    client.requestSessionState()
+
+    // Wait a moment for the session state to be populated
+    await new Promise((resolve) => setTimeout(resolve, 500))
+
+    let agents = client.listAgents()
+
+    // Filter out archived agents unless -a flag is set
+    if (!options.all) {
+      agents = agents.filter((a) => !a.archivedAt)
+    }
+
+    // Filter by status if specified
+    if (options.status) {
+      agents = agents.filter((a) => a.status === options.status)
+    }
+
+    // Filter by cwd if specified
+    if (options.cwd) {
+      const filterCwd = options.cwd
+      agents = agents.filter((a) => {
+        // Normalize paths for comparison
+        const agentCwd = a.cwd.replace(/\/$/, '')
+        const targetCwd = filterCwd.replace(/\/$/, '')
+        return agentCwd === targetCwd || agentCwd.startsWith(targetCwd + '/')
+      })
+    }
+
+    await client.close()
+
+    const items = agents.map(toListItem)
+
+    return {
+      type: 'list',
+      data: items,
+      schema: agentPsSchema,
+    }
+  } catch (err) {
+    await client.close().catch(() => {})
+    const message = err instanceof Error ? err.message : String(err)
+    const error: CommandError = {
+      code: 'LIST_AGENTS_FAILED',
+      message: `Failed to list agents: ${message}`,
+    }
+    throw error
+  }
+}

packages/cli/tests/04-agent-ps.test.mts

@@ -0,0 +1,147 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Phase 3: Agent PS Command Tests
+ *
+ * Tests the agent ps command - listing agents.
+ * Since daemon may not be running, we test both:
+ * - Help and argument parsing
+ * - Graceful error handling when daemon not running
+ * - JSON output format
+ *
+ * Tests:
+ * - agent --help shows subcommands
+ * - agent ps --help shows options
+ * - agent ps returns empty list or error when no daemon
+ * - agent ps --format json returns valid JSON (or error)
+ * - agent ps -a flag is accepted
+ * - agent ps --status flag is accepted
+ * - agent ps --cwd flag is accepted
+ */
+
+import assert from 'node:assert'
+import { $ } from 'zx'
+import { mkdtemp, rm } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+$.verbose = false
+
+console.log('=== Agent PS Command Tests ===\n')
+
+// Get random port that's definitely not in use (never 6767)
+const port = 10000 + Math.floor(Math.random() * 50000)
+const paseoHome = await mkdtemp(join(tmpdir(), 'paseo-test-home-'))
+
+try {
+  // Test 1: agent --help shows subcommands
+  {
+    console.log('Test 1: agent --help shows subcommands')
+    const result = await $`npx paseo agent --help`.nothrow()
+    assert.strictEqual(result.exitCode, 0, 'agent --help should exit 0')
+    assert(result.stdout.includes('ps'), 'help should mention ps subcommand')
+    console.log('✓ agent --help shows subcommands\n')
+  }
+
+  // Test 2: agent ps --help shows options
+  {
+    console.log('Test 2: agent ps --help shows options')
+    const result = await $`npx paseo agent ps --help`.nothrow()
+    assert.strictEqual(result.exitCode, 0, 'agent ps --help should exit 0')
+    assert(result.stdout.includes('-a'), 'help should mention -a flag')
+    assert(result.stdout.includes('--all'), 'help should mention --all flag')
+    assert(result.stdout.includes('--status'), 'help should mention --status option')
+    assert(result.stdout.includes('--cwd'), 'help should mention --cwd option')
+    assert(result.stdout.includes('--host'), 'help should mention --host option')
+    console.log('✓ agent ps --help shows options\n')
+  }
+
+  // Test 3: agent ps returns error when no daemon running
+  {
+    console.log('Test 3: agent ps handles daemon not running')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps`.nothrow()
+    // Should fail because daemon not running
+    assert.notStrictEqual(result.exitCode, 0, 'should fail when daemon not running')
+    const output = result.stdout + result.stderr
+    const hasError =
+      output.toLowerCase().includes('daemon') ||
+      output.toLowerCase().includes('connect') ||
+      output.toLowerCase().includes('cannot')
+    assert(hasError, 'error message should mention connection issue')
+    console.log('✓ agent ps handles daemon not running\n')
+  }
+
+  // Test 4: agent ps --format json returns valid JSON error
+  {
+    console.log('Test 4: agent ps --format json handles errors')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --format json`.nothrow()
+    // Should still fail (daemon not running)
+    assert.notStrictEqual(result.exitCode, 0, 'should fail when daemon not running')
+    // But output should be valid JSON if present
+    const output = result.stdout.trim()
+    if (output.length > 0) {
+      try {
+        JSON.parse(output)
+        console.log('✓ agent ps --format json outputs valid JSON error\n')
+      } catch {
+        // Empty or stderr-only output is acceptable
+        console.log('✓ agent ps --format json handled error (output may be in stderr)\n')
+      }
+    } else {
+      console.log('✓ agent ps --format json handled error gracefully\n')
+    }
+  }
+
+  // Test 5: agent ps -a flag is accepted
+  {
+    console.log('Test 5: agent ps -a flag is accepted')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps -a`.nothrow()
+    // Will fail due to no daemon, but flag should be parsed without error
+    // (no "unknown option" error)
+    const output = result.stdout + result.stderr
+    assert(!output.includes('unknown option'), 'should accept -a flag')
+    assert(!output.includes('error: option'), 'should not have option parsing error')
+    console.log('✓ agent ps -a flag is accepted\n')
+  }
+
+  // Test 6: agent ps --status flag is accepted
+  {
+    console.log('Test 6: agent ps --status flag is accepted')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --status running`.nothrow()
+    const output = result.stdout + result.stderr
+    assert(!output.includes('unknown option'), 'should accept --status flag')
+    assert(!output.includes('error: option'), 'should not have option parsing error')
+    console.log('✓ agent ps --status flag is accepted\n')
+  }
+
+  // Test 7: agent ps --cwd flag is accepted
+  {
+    console.log('Test 7: agent ps --cwd flag is accepted')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo agent ps --cwd /tmp`.nothrow()
+    const output = result.stdout + result.stderr
+    assert(!output.includes('unknown option'), 'should accept --cwd flag')
+    assert(!output.includes('error: option'), 'should not have option parsing error')
+    console.log('✓ agent ps --cwd flag is accepted\n')
+  }
+
+  // Test 8: -q (quiet) flag is accepted globally
+  {
+    console.log('Test 8: -q (quiet) flag is accepted')
+    const result =
+      await $`PASEO_HOST=localhost:${port} PASEO_HOME=${paseoHome} npx paseo -q agent ps`.nothrow()
+    const output = result.stdout + result.stderr
+    assert(!output.includes('unknown option'), 'should accept -q flag')
+    assert(!output.includes('error: option'), 'should not have option parsing error')
+    console.log('✓ -q (quiet) flag is accepted\n')
+  }
+} finally {
+  // Clean up temp directory
+  await rm(paseoHome, { recursive: true, force: true })
+}
+
+console.log('=== All agent ps tests passed ===')