From e412edd0ea7112272a51ca98d76cae40ca7e8664 Mon Sep 17 00:00:00 2001
From: sstefdev <sstefandev@gmail.com>
Date: Mon, 25 May 2026 13:30:38 +0200
Subject: [PATCH] feat: parallel multi-agent runs with stop + grid layout
 (closes #6)

---
 src/app/api/agents/[id]/run/route.ts | 21 ++++++++-
 src/app/api/runs/[id]/stop/route.ts  | 24 ++++++++++
 src/app/workspace/[id]/page.tsx      |  9 +++-
 src/components/AgentPanel.tsx        | 60 +++++++++++++++++++++----
 src/components/RunHistory.tsx        |  2 +-
 src/lib/claude.ts                    | 13 ++++++
 src/lib/run-registry.ts              | 67 ++++++++++++++++++++++++++++
 7 files changed, 182 insertions(+), 14 deletions(-)
 create mode 100644 src/app/api/runs/[id]/stop/route.ts
 create mode 100644 src/lib/run-registry.ts

diff --git a/src/app/api/agents/[id]/run/route.ts b/src/app/api/agents/[id]/run/route.ts
index 1ae0c90..6bab04a 100644
--- a/src/app/api/agents/[id]/run/route.ts
+++ b/src/app/api/agents/[id]/run/route.ts
@@ -3,6 +3,7 @@ import { db, schema } from '@/lib/db'
 import { eq } from 'drizzle-orm'
 import { runAgent, writeAgentSkillConfig } from '@/lib/claude'
 import { resolveAgentCwd } from '@/lib/directories'
+import { registerRun, unregisterRun } from '@/lib/run-registry'
 
 export const runtime = 'nodejs'
 // Allow long-running streams; default Vercel limit is short, but we're
@@ -72,6 +73,9 @@ export async function POST(
   const encoder = new TextEncoder()
   const collected: string[] = []
   let exitCode: number | null = null
+  // Track whether the run was killed via the Stop endpoint so we can
+  // record status='cancelled' instead of 'failed' on a non-zero exit.
+  let cancelled = false
 
   const stream = new ReadableStream({
     async start(controller) {
@@ -94,6 +98,14 @@ export async function POST(
           systemPrompt: agent.systemPrompt ?? '',
           model: agent.model,
           skills: agent.skills ?? [],
+          onChild: (child) => {
+            registerRun(run.id, child)
+            // Detect external SIGTERM (i.e. our Stop endpoint) so we
+            // can persist 'cancelled' instead of 'failed' on exit.
+            child.once('exit', (_code, signal) => {
+              if (signal === 'SIGTERM') cancelled = true
+            })
+          },
         })) {
           send(event as object)
           collected.push(JSON.stringify(event))
@@ -112,10 +124,15 @@ export async function POST(
           type: 'error',
           message: err instanceof Error ? err.message : String(err),
         })
+      } finally {
+        unregisterRun(run.id)
       }
 
-      const status: 'completed' | 'failed' =
-        exitCode === 0 ? 'completed' : 'failed'
+      const status: 'completed' | 'failed' | 'cancelled' = cancelled
+        ? 'cancelled'
+        : exitCode === 0
+          ? 'completed'
+          : 'failed'
       try {
         await db
           .update(schema.runs)
diff --git a/src/app/api/runs/[id]/stop/route.ts b/src/app/api/runs/[id]/stop/route.ts
new file mode 100644
index 0000000..974c9cd
--- /dev/null
+++ b/src/app/api/runs/[id]/stop/route.ts
@@ -0,0 +1,24 @@
+import { NextResponse } from 'next/server'
+import { killRun, isRunning } from '@/lib/run-registry'
+
+export const runtime = 'nodejs'
+
+/**
+ * POST /api/runs/[id]/stop
+ *
+ * SIGTERM the run's child process group if it's still alive. The
+ * run-route's SSE loop sees the child exit, persists `status='cancelled'`
+ * (detected via the SIGTERM signal), and closes the stream. Idempotent:
+ * stopping an already-finished run returns 200 with stopped:false.
+ */
+export async function POST(
+  _req: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params
+  if (!isRunning(id)) {
+    return NextResponse.json({ ok: true, stopped: false })
+  }
+  const killed = killRun(id)
+  return NextResponse.json({ ok: true, stopped: killed })
+}
diff --git a/src/app/workspace/[id]/page.tsx b/src/app/workspace/[id]/page.tsx
index 2058935..a102aac 100644
--- a/src/app/workspace/[id]/page.tsx
+++ b/src/app/workspace/[id]/page.tsx
@@ -105,9 +105,14 @@ export default async function WorkspacePage({
         <h2 className="text-sm font-semibold uppercase tracking-[0.18em] text-neutral-500">
           Agents
         </h2>
-        <div className="mt-3 flex flex-col gap-4">
+        <p className="mt-1 max-w-2xl text-xs text-neutral-500">
+          Each agent runs independently. Hit Run on more than one to
+          watch them work in parallel; Stop sends SIGTERM to that
+          agent&apos;s child without touching the others.
+        </p>
+        <div className="mt-3 grid grid-cols-1 gap-4 xl:grid-cols-2">
           {agents.length === 0 && (
-            <div className="rounded-lg border border-dashed border-neutral-800 p-6 text-sm text-neutral-500">
+            <div className="rounded-lg border border-dashed border-neutral-800 p-6 text-sm text-neutral-500 xl:col-span-2">
               No agents in this workspace yet. Create one below.
             </div>
           )}
diff --git a/src/components/AgentPanel.tsx b/src/components/AgentPanel.tsx
index 6eed0ca..9d5dd5a 100644
--- a/src/components/AgentPanel.tsx
+++ b/src/components/AgentPanel.tsx
@@ -30,15 +30,30 @@ export function AgentPanel({
   const [prompt, setPrompt] = useState('')
   const [events, setEvents] = useState<StreamEvent[]>([])
   const [running, setRunning] = useState(false)
+  // RunId becomes known after the server emits its run:start frame.
+  // The Stop button needs this to address the right child process.
+  const [runId, setRunId] = useState<string | null>(null)
   // Bumped each time a live run ends, so RunHistory re-fetches the
   // newly persisted row without a full page reload.
   const [historyVersion, setHistoryVersion] = useState(0)
   const outputRef = useRef<HTMLDivElement>(null)
 
+  async function stop() {
+    if (!runId) return
+    try {
+      await fetch(`/api/runs/${runId}/stop`, { method: 'POST' })
+    } catch {
+      // Server might be gone or restarted. The run-end frame will
+      // never arrive in that case; the UI just stays in "running"
+      // until the user reloads. Not worth more handling for v1.
+    }
+  }
+
   async function run() {
     if (!prompt.trim() || running) return
     setRunning(true)
     setEvents([])
+    setRunId(null)
     try {
       const res = await fetch(`/api/agents/${agent.id}/run`, {
         method: 'POST',
@@ -70,6 +85,14 @@ export function AgentPanel({
           if (!dataLine) continue
           try {
             const event = JSON.parse(dataLine.slice('data: '.length))
+            if (
+              event &&
+              typeof event === 'object' &&
+              event.type === 'run:start' &&
+              typeof event.runId === 'string'
+            ) {
+              setRunId(event.runId)
+            }
             setEvents((prev) => [...prev, event])
             // Auto-scroll to bottom of output
             requestAnimationFrame(() => {
@@ -92,6 +115,7 @@ export function AgentPanel({
       ])
     } finally {
       setRunning(false)
+      setRunId(null)
       setHistoryVersion((v) => v + 1)
     }
   }
@@ -159,14 +183,26 @@ export function AgentPanel({
           disabled={running}
           className="rounded border border-neutral-800 bg-neutral-950 px-3 py-2 text-sm focus:border-neutral-600 focus:outline-none disabled:opacity-50"
         />
-        <div className="flex justify-between">
-          <button
-            onClick={run}
-            disabled={running || !prompt.trim()}
-            className="rounded bg-amber-500 px-4 py-2 text-sm font-medium text-neutral-950 transition hover:bg-amber-400 disabled:cursor-not-allowed disabled:opacity-50"
-          >
-            {running ? 'running...' : 'Run'}
-          </button>
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex items-center gap-2">
+            <button
+              onClick={run}
+              disabled={running || !prompt.trim()}
+              className="rounded bg-amber-500 px-4 py-2 text-sm font-medium text-neutral-950 transition hover:bg-amber-400 disabled:cursor-not-allowed disabled:opacity-50"
+            >
+              {running ? 'running...' : 'Run'}
+            </button>
+            {running && (
+              <button
+                onClick={stop}
+                disabled={!runId}
+                className="rounded border border-red-900 px-3 py-2 text-sm font-medium text-red-400 transition hover:bg-red-950 disabled:cursor-not-allowed disabled:opacity-50"
+                title={runId ? 'send SIGTERM to the running child' : 'waiting for runId'}
+              >
+                Stop
+              </button>
+            )}
+          </div>
           {events.length > 0 && (
             <button
               onClick={() => setEvents([])}
@@ -206,8 +242,14 @@ function EventLine({ event }: { event: StreamEvent }) {
       status: string
       exitCode: number | null
     }
+    const color =
+      e.status === 'completed'
+        ? 'text-green-500'
+        : e.status === 'cancelled'
+          ? 'text-amber-400'
+          : 'text-red-400'
     return (
-      <div className={e.status === 'completed' ? 'text-green-500' : 'text-red-400'}>
+      <div className={color}>
         ▸ run {e.status} (exit {e.exitCode ?? '?'})
       </div>
     )
diff --git a/src/components/RunHistory.tsx b/src/components/RunHistory.tsx
index 32163cb..288f89f 100644
--- a/src/components/RunHistory.tsx
+++ b/src/components/RunHistory.tsx
@@ -111,7 +111,7 @@ function RunRow({
   const status = run.status
   const exit = run.exitCode
   const statusColor =
-    status === 'running'
+    status === 'running' || status === 'cancelled'
       ? 'text-amber-400'
       : exit === 0
         ? 'text-green-500'
diff --git a/src/lib/claude.ts b/src/lib/claude.ts
index 1ca1ea8..d452f6c 100644
--- a/src/lib/claude.ts
+++ b/src/lib/claude.ts
@@ -31,6 +31,13 @@ export type AgentRunOptions = {
   systemPrompt?: string
   model?: string | null
   skills?: string[]
+  /**
+   * Called once with the freshly spawned child process. The caller can
+   * use this to register the process in a kill-from-elsewhere registry
+   * (so a Stop button on a parallel pane can SIGTERM this run). The
+   * child is unspecified if spawn itself fails before this callback.
+   */
+  onChild?: (child: ChildProcessWithoutNullStreams) => void
 }
 
 /**
@@ -93,6 +100,11 @@ export async function* runAgent(opts: AgentRunOptions) {
     child = spawn('claude', args, {
       cwd: opts.cwd,
       env: { ...process.env },
+      // detached:true puts the child in its own process group. SIGTERM
+      // sent to -pid then kills the whole group, including any tool
+      // subprocesses claude spawned. We still wait for the child in the
+      // current process, so the OS treats this as a regular child.
+      detached: true,
     })
   } catch (err) {
     yield {
@@ -102,6 +114,7 @@ export async function* runAgent(opts: AgentRunOptions) {
     yield { type: 'exit', code: 1 }
     return
   }
+  if (opts.onChild) opts.onChild(child)
 
   // Forward stdout as JSONL events. Buffer partial lines across
   // chunks so we never yield half a JSON object.
diff --git a/src/lib/run-registry.ts b/src/lib/run-registry.ts
new file mode 100644
index 0000000..342e335
--- /dev/null
+++ b/src/lib/run-registry.ts
@@ -0,0 +1,67 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process'
+
+/**
+ * Process-local registry mapping runId -> the child process spawned
+ * for that run. Used by the Stop endpoint to find and SIGTERM a run
+ * that was started in a different request.
+ *
+ * In-memory only, single process. A `next start` worker restart drops
+ * the map and any leftover process becomes an orphan (cleaned up by
+ * the OS or by exiting on its own). Good enough for a local single-
+ * user app; revisit if Argus ever runs multi-process.
+ *
+ * Cached on globalThis so Next.js dev's module hot reload doesn't
+ * silently fork the map.
+ */
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __argus_run_registry: Map<string, ChildProcessWithoutNullStreams> | undefined
+}
+
+const registry: Map<string, ChildProcessWithoutNullStreams> =
+  globalThis.__argus_run_registry ??
+  (globalThis.__argus_run_registry = new Map())
+
+export function registerRun(
+  runId: string,
+  child: ChildProcessWithoutNullStreams,
+): void {
+  registry.set(runId, child)
+  // Auto-clean when the process exits, so the map doesn't grow forever
+  // and so a Stop request after a natural exit just no-ops cleanly.
+  child.once('exit', () => {
+    if (registry.get(runId) === child) registry.delete(runId)
+  })
+}
+
+export function unregisterRun(runId: string): void {
+  registry.delete(runId)
+}
+
+export function isRunning(runId: string): boolean {
+  return registry.has(runId)
+}
+
+/**
+ * SIGTERM the run's process group. Returns true if a process was
+ * found and signaled, false if there's nothing to kill (already
+ * exited, never registered, etc).
+ *
+ * Targets `-pid` (negative) so the signal hits the whole process group
+ * the child was placed into (see detached:true on spawn). That kills
+ * any tool subprocesses claude itself started.
+ */
+export function killRun(runId: string): boolean {
+  const child = registry.get(runId)
+  if (!child || child.pid == null) return false
+  try {
+    process.kill(-child.pid, 'SIGTERM')
+    return true
+  } catch {
+    // Process already gone or signal not permitted; either way, drop
+    // it from the map so we don't try again.
+    registry.delete(runId)
+    return false
+  }
+}