v3.0.0-rc.1: force-kill flag, SSE cap bump, Tower sort fix, handle validation

- af tower stop --force-kill-all-child-processes: kills detached shellper
  processes and their children (claude, bash), not just the Tower daemon
- SSE hard cap bumped from 12 to 50 for multi-workspace usage
- Tower overview: running workspaces alphabetical, recent reverse-chronological
- GitHub handle validation relaxed to accept trailing hyphens (e.g. timeleft--)

Author: waleedkadous

packages/codev/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.0.0-rc.0",
+  "version": "3.0.0-rc.1",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {

packages/codev/src/__tests__/team.test.ts

@@ -91,12 +91,13 @@ describe('isValidGitHubHandle', () => {
     expect(isValidGitHubHandle('alice-bob')).toBe(true);
     expect(isValidGitHubHandle('Alice123')).toBe(true);
     expect(isValidGitHubHandle('a')).toBe(true);
+    expect(isValidGitHubHandle('alice-')).toBe(true);
+    expect(isValidGitHubHandle('timeleft--')).toBe(true);
   });
 
   it('rejects invalid handles', () => {
     expect(isValidGitHubHandle('')).toBe(false);
     expect(isValidGitHubHandle('-alice')).toBe(false);
-    expect(isValidGitHubHandle('alice-')).toBe(false);
     expect(isValidGitHubHandle('al ice')).toBe(false);
     expect(isValidGitHubHandle('al@ice')).toBe(false);
     expect(isValidGitHubHandle('a'.repeat(40))).toBe(false);

packages/codev/src/agent-farm/cli.ts

@@ -617,10 +617,12 @@ export async function runAgentFarm(args: string[]): Promise<void> {
     .command('stop')
     .description('Stop the tower dashboard')
     .option('-p, --port <port>', 'Port to stop (default: 4100)')
+    .option('--force-kill-all-child-processes', 'SIGKILL tower and every child process (builders, shells, everything)')
     .action(async (options) => {
       try {
         await towerStop({
           port: options.port ? parseInt(options.port, 10) : undefined,
+          forceKillAllChildProcesses: options.forceKillAllChildProcesses,
         });
       } catch (error) {
         logger.error(error instanceof Error ? error.message : String(error));

packages/codev/src/agent-farm/commands/tower.ts

@@ -26,6 +26,7 @@ export interface TowerStartOptions {
 
 export interface TowerStopOptions {
   port?: number;
+  forceKillAllChildProcesses?: boolean;
 }
 
 /**
@@ -214,8 +215,9 @@ export async function towerStart(options: TowerStartOptions = {}): Promise<void>
  */
 export async function towerStop(options: TowerStopOptions = {}): Promise<void> {
   const port = options.port || DEFAULT_TOWER_PORT;
+  const forceKill = options.forceKillAllChildProcesses || false;
 
-  logger.header('Stopping Tower');
+  logger.header(forceKill ? 'Force-Killing Tower and All Child Processes' : 'Stopping Tower');
 
   const pids = getProcessesOnPort(port);
 
@@ -224,6 +226,56 @@ export async function towerStop(options: TowerStopOptions = {}): Promise<void> {
     return;
   }
 
+  if (forceKill) {
+    // Shellper processes are spawned DETACHED from Tower — they intentionally
+    // survive Tower restarts. So pgrep -P won't find them. We need to:
+    // 1. Find all shellper-main processes via pgrep -f
+    // 2. Find all their children (claude, bash, etc.)
+    // 3. Kill the Tower daemon itself
+    const { execSync } = await import('node:child_process');
+    const allPids = new Set<number>();
+
+    // Recursive function to collect entire subtree via pgrep -P
+    function collectDescendants(pid: number): void {
+      if (allPids.has(pid)) return;
+      allPids.add(pid);
+      try {
+        const output = execSync(`pgrep -P ${pid}`, { encoding: 'utf-8' }).trim();
+        for (const line of output.split('\n')) {
+          const childPid = parseInt(line, 10);
+          if (!isNaN(childPid)) collectDescendants(childPid);
+        }
+      } catch { /* no children */ }
+    }
+
+    // Collect Tower daemon PIDs
+    for (const pid of pids) {
+      collectDescendants(pid);
+    }
+
+    // Collect ALL shellper processes and their descendants (claude, bash, etc.)
+    try {
+      const shellperOutput = execSync('pgrep -f shellper-main', { encoding: 'utf-8' }).trim();
+      for (const line of shellperOutput.split('\n')) {
+        const pid = parseInt(line, 10);
+        if (!isNaN(pid)) collectDescendants(pid);
+      }
+    } catch { /* no shellper processes */ }
+
+    // Kill leaves first (reverse order: deepest descendants → root)
+    const orderedPids = [...allPids].reverse();
+    let killed = 0;
+    for (const pid of orderedPids) {
+      try {
+        process.kill(pid, 'SIGKILL');
+        killed++;
+      } catch { /* already dead */ }
+    }
+
+    logger.success(`Force-killed ${killed} process(es) (tower + ${orderedPids.length - pids.length} shellper/children)`);
+    return;
+  }
+
   let stopped = 0;
   for (const pid of pids) {
     try {

packages/codev/src/agent-farm/servers/tower-instances.ts

@@ -200,12 +200,19 @@ export async function getInstances(): Promise<InstanceStatus[]> {
     });
   }
 
-  // Sort: running first, then by workspace name
+  // Sort: running first (alphabetical), then non-running by most recently used
   instances.sort((a, b) => {
     if (a.running !== b.running) {
       return a.running ? -1 : 1;
     }
-    return a.workspaceName.localeCompare(b.workspaceName);
+    if (a.running) {
+      // Running: alphabetical
+      return a.workspaceName.localeCompare(b.workspaceName);
+    }
+    // Non-running (recent): reverse chronological (most recently used first)
+    const aTime = a.lastUsed ? new Date(a.lastUsed).getTime() : 0;
+    const bTime = b.lastUsed ? new Date(b.lastUsed).getTime() : 0;
+    return bTime - aTime;
   });
 
   return instances;

packages/codev/src/agent-farm/servers/tower-server.ts

@@ -291,7 +291,7 @@ const routeCtx: RouteContext = {
     // Hard cap: evict oldest connections when over limit to prevent
     // unbounded accumulation (tunnel-proxied EventSource reconnects
     // can leak because TCP close doesn't propagate reliably).
-    const SSE_MAX_CLIENTS = 12;
+    const SSE_MAX_CLIENTS = 50;
     while (sseClients.length >= SSE_MAX_CLIENTS) {
       const oldest = sseClients.shift();
       if (oldest) {

packages/codev/src/lib/team.ts

@@ -70,7 +70,10 @@ export function parseFrontmatter(content: string): Record<string, unknown> | nul
 // Team Members
 // =============================================================================
 
-const GITHUB_HANDLE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+// GitHub's documented rules say no trailing hyphens or consecutive hyphens,
+// but real accounts like "timeleft--" exist. Match what GitHub actually allows:
+// starts with alphanumeric, then any mix of alphanumeric and hyphens.
+const GITHUB_HANDLE_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]*$/;
 
 export function isValidGitHubHandle(handle: string): boolean {
   return GITHUB_HANDLE_RE.test(handle) && handle.length <= 39;