From 474bb54bc59303aa0baa63e0b1af1eec3d8046fe Mon Sep 17 00:00:00 2001
From: nfebe <fenn25.fn@gmail.com>
Date: Mon, 7 Sep 2026 23:07:07 +0100
Subject: [PATCH 1/4] feat: Improve local setup, graph loading, and shutdown

---
 cmd/agent/main.go                    |  38 +++++++-
 cmd/agent/main_test.go               | 131 +++++++++++++++++++++++++++
 internal/api/server.go               |  31 ++++++-
 internal/api/stop_test.go            |  36 ++++++++
 internal/runtime/runtime.go          |  24 +++++
 ui/src/components/FolderPicker.vue   |   7 +-
 ui/src/components/GraphWorkbench.vue |  31 +++++--
 ui/src/components/Onboarding.vue     |  12 +--
 ui/src/composables/useCodeGraph.js   |   1 +
 9 files changed, 288 insertions(+), 23 deletions(-)
 create mode 100644 cmd/agent/main_test.go
 create mode 100644 internal/api/stop_test.go

diff --git a/cmd/agent/main.go b/cmd/agent/main.go
index 083d962..37028ce 100644
--- a/cmd/agent/main.go
+++ b/cmd/agent/main.go
@@ -71,11 +71,29 @@ func run() error {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
-	supervised := make(chan error, 1)
-	go func() { supervised <- supervisor.Run(ctx) }()
+	supervised := make(chan struct{})
+	var coreErr error
+	go func() {
+		defer close(supervised)
+		coreErr = supervisor.Run(ctx)
+		cleanup, cancel := context.WithTimeout(context.Background(), 8*time.Second)
+		defer cancel()
+		if err := installed.Stop(cleanup, port); err != nil && coreErr == nil {
+			coreErr = err
+		}
+	}()
 
 	served := make(chan error, 1)
 	server := api.New(client, supervisor, Version, coreURL)
+	server.SetStop(func(request context.Context) error {
+		stop()
+		select {
+		case <-supervised:
+			return coreErr
+		case <-request.Done():
+			return request.Err()
+		}
+	})
 	go func() { served <- server.Serve(ctx, cfg.Listen) }()
 
 	// A repository read once answers about last month, so it is read again on
@@ -89,10 +107,20 @@ func run() error {
 	// Whichever half stops first ends the agent: an agent serving without a
 	// core answers nothing, and a core nobody serves is not reachable.
 	select {
-	case err := <-supervised:
-		return err
+	case <-supervised:
+		stop()
+		serverErr := <-served
+		if coreErr != nil {
+			return coreErr
+		}
+		return serverErr
 	case err := <-served:
-		return err
+		stop()
+		<-supervised
+		if err != nil {
+			return err
+		}
+		return coreErr
 	}
 }
 
diff --git a/cmd/agent/main_test.go b/cmd/agent/main_test.go
new file mode 100644
index 0000000..8bb5724
--- /dev/null
+++ b/cmd/agent/main_test.go
@@ -0,0 +1,131 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestAgentProcess(t *testing.T) {
+	switch os.Getenv("SOURCEANT_TEST_PROCESS") {
+	case "agent":
+		if err := run(); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+		os.Exit(0)
+	case "core":
+		port := os.Args[len(os.Args)-1]
+		stopped := make(chan os.Signal, 1)
+		signal.Notify(stopped, syscall.SIGTERM)
+		go func() {
+			<-stopped
+			time.Sleep(200 * time.Millisecond)
+			if err := os.WriteFile(os.Getenv("SOURCEANT_TEST_STOPPED"), []byte("stopped"), 0600); err != nil {
+				os.Exit(1)
+			}
+			os.Exit(0)
+		}()
+		_ = http.ListenAndServe("127.0.0.1:"+port, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) }))
+		os.Exit(1)
+	}
+}
+
+func TestShutdownWaitsForCore(t *testing.T) {
+	for _, mode := range []string{"http", "signal"} {
+		t.Run(mode, func(t *testing.T) {
+			dir := t.TempDir()
+			binary, err := os.Executable()
+			if err != nil {
+				t.Fatal(err)
+			}
+			wrapper := filepath.Join(dir, "core")
+			if err := os.WriteFile(wrapper, []byte("#!/bin/sh\nexport SOURCEANT_TEST_PROCESS=core\nexec \"$SOURCEANT_TEST_BINARY\" -test.run=TestAgentProcess -- \"$@\"\n"), 0700); err != nil {
+				t.Fatal(err)
+			}
+			listener, err := net.Listen("tcp", "127.0.0.1:0")
+			if err != nil {
+				t.Fatal(err)
+			}
+			address := listener.Addr().String()
+			_ = listener.Close()
+			stopped := filepath.Join(dir, "stopped")
+			cmd := exec.Command(binary, "-test.run=TestAgentProcess")
+			cmd.Env = append(os.Environ(), "SOURCEANT_TEST_PROCESS=agent", "SOURCEANT_TEST_BINARY="+binary, "SOURCEANT_TEST_STOPPED="+stopped, "SOURCEANT_CORE="+wrapper, "SOURCEANT_CORE_PORT=", "SOURCEANT_AGENT_LISTEN="+address)
+			var output bytes.Buffer
+			cmd.Stdout = &output
+			cmd.Stderr = &output
+			if err := cmd.Start(); err != nil {
+				t.Fatal(err)
+			}
+			done := make(chan struct{})
+			var waitErr error
+			go func() { waitErr = cmd.Wait(); close(done) }()
+			t.Cleanup(func() {
+				_ = cmd.Process.Signal(syscall.SIGTERM)
+				select {
+				case <-done:
+				case <-time.After(10 * time.Second):
+					_ = cmd.Process.Kill()
+				}
+			})
+			client := &http.Client{Timeout: 10 * time.Second}
+			ready := false
+			deadline := time.Now().Add(10 * time.Second)
+			for time.Now().Before(deadline) {
+				response, err := client.Get("http://" + address + "/health")
+				if err == nil {
+					var status struct {
+						CoreUp bool `json:"core_up"`
+					}
+					decodeErr := json.NewDecoder(response.Body).Decode(&status)
+					_ = response.Body.Close()
+					if decodeErr == nil && status.CoreUp {
+						ready = true
+						break
+					}
+				}
+				time.Sleep(20 * time.Millisecond)
+			}
+			if !ready {
+				t.Fatal("agent did not become ready")
+			}
+			if mode == "http" {
+				request, _ := http.NewRequest(http.MethodPost, "http://"+address+"/api/stop", nil)
+				request.Header.Set("X-Sourceant-Client", "cli")
+				response, err := client.Do(request)
+				if err != nil {
+					t.Fatal(err)
+				}
+				_ = response.Body.Close()
+				if response.StatusCode != 204 {
+					t.Fatalf("stop returned %d", response.StatusCode)
+				}
+			} else {
+				if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
+					t.Fatal(err)
+				}
+			}
+			select {
+			case <-done:
+				if waitErr != nil {
+					t.Fatalf("%v: %s", waitErr, output.String())
+				}
+			case <-time.After(10 * time.Second):
+				t.Fatal("agent did not stop")
+			}
+			if _, err := os.Stat(stopped); err != nil {
+				t.Fatal("agent exited before core cleanup completed")
+			}
+		})
+	}
+}
diff --git a/internal/api/server.go b/internal/api/server.go
index 9a21c5b..622f139 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -10,6 +10,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"net"
 	"net/http"
 	"strconv"
 	"time"
@@ -69,6 +70,7 @@ type Server struct {
 	supervisor Supervision
 	version    string
 	coreURL    string
+	stop       func(context.Context) error
 }
 
 // New builds the agent's HTTP surface.
@@ -81,9 +83,29 @@ func New(reader Reader, supervisor Supervision, version, coreURL string) *Server
 	}
 }
 
+func (s *Server) SetStop(stop func(context.Context) error) { s.stop = stop }
+
+func (s *Server) stopStack(w http.ResponseWriter, r *http.Request) {
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil || !net.ParseIP(host).IsLoopback() || r.Header.Get("Origin") != "" || r.Header.Get("X-Sourceant-Client") != "cli" {
+		write(w, http.StatusForbidden, problem{Error: "stop is only available to the local CLI"})
+		return
+	}
+	if s.stop == nil {
+		write(w, http.StatusNotImplemented, problem{Error: "this agent does not support stopping"})
+		return
+	}
+	if err := s.stop(r.Context()); err != nil {
+		write(w, http.StatusInternalServerError, problem{Error: err.Error()})
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // Handler is the agent's routes.
 func (s *Server) Handler() http.Handler {
 	mux := http.NewServeMux()
+	mux.HandleFunc("POST /api/stop", s.stopStack)
 	mux.HandleFunc("GET /health", s.health)
 	mux.HandleFunc("GET /api/repositories", s.repositories)
 	mux.HandleFunc("POST /api/repositories", s.addRepository)
@@ -466,14 +488,19 @@ func (s *Server) Serve(ctx context.Context, address string) error {
 		Handler:           s.Handler(),
 		ReadHeaderTimeout: 10 * time.Second,
 	}
+	shutdownDone := make(chan struct{})
 	go func() {
+		defer close(shutdownDone)
 		<-ctx.Done()
-		shutdown, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+		shutdown, cancel := context.WithTimeout(context.WithoutCancel(ctx), 15*time.Second)
 		defer cancel()
-		_ = server.Shutdown(shutdown)
+		if err := server.Shutdown(shutdown); err != nil {
+			_ = server.Close()
+		}
 	}()
 	if err := server.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
 		return err
 	}
+	<-shutdownDone
 	return nil
 }
diff --git a/internal/api/stop_test.go b/internal/api/stop_test.go
new file mode 100644
index 0000000..0220d00
--- /dev/null
+++ b/internal/api/stop_test.go
@@ -0,0 +1,36 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestStopRequiresLocalCLI(t *testing.T) {
+	for _, tc := range []struct {
+		name, remote, origin, client string
+		want                         int
+	}{
+		{"local", "127.0.0.1:1234", "", "cli", 204},
+		{"ipv6", "[::1]:1234", "", "cli", 204},
+		{"remote", "192.0.2.1:1234", "", "cli", 403},
+		{"browser", "127.0.0.1:1234", "http://example.org", "cli", 403},
+		{"missing client", "127.0.0.1:1234", "", "", 403},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			server := New(nil, nil, "test", "")
+			stopped := false
+			server.SetStop(func(context.Context) error { stopped = true; return nil })
+			req := httptest.NewRequest(http.MethodPost, "/api/stop", nil)
+			req.RemoteAddr = tc.remote
+			req.Header.Set("Origin", tc.origin)
+			req.Header.Set("X-Sourceant-Client", tc.client)
+			response := httptest.NewRecorder()
+			server.Handler().ServeHTTP(response, req)
+			if response.Code != tc.want || stopped != (tc.want == 204) {
+				t.Fatalf("status=%d stopped=%v", response.Code, stopped)
+			}
+		})
+	}
+}
diff --git a/internal/runtime/runtime.go b/internal/runtime/runtime.go
index 9dd0b86..24df27a 100644
--- a/internal/runtime/runtime.go
+++ b/internal/runtime/runtime.go
@@ -7,13 +7,16 @@
 package runtime
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"net/url"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strconv"
+	"strings"
 )
 
 // Kind is how the core is installed.
@@ -209,3 +212,24 @@ func throughTheHost(address string) string {
 	}
 	return parsed.String()
 }
+
+func (c Core) Stop(ctx context.Context, port int) error {
+	if c.Runtime != Docker {
+		return nil
+	}
+	name := "sourceant-core-" + strconv.Itoa(port)
+	output, err := exec.CommandContext(ctx, "docker", "container", "ls", "--all", "--format", "{{.Names}}").CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("checking the core container: %w: %s", err, output)
+	}
+	for _, container := range strings.Fields(string(output)) {
+		if container == name {
+			output, err = exec.CommandContext(ctx, "docker", "container", "stop", "--timeout", "5", name).CombinedOutput()
+			if err != nil {
+				return fmt.Errorf("stopping the core container: %w: %s", err, output)
+			}
+			break
+		}
+	}
+	return nil
+}
diff --git a/ui/src/components/FolderPicker.vue b/ui/src/components/FolderPicker.vue
index 75ce448..a44368b 100644
--- a/ui/src/components/FolderPicker.vue
+++ b/ui/src/components/FolderPicker.vue
@@ -45,8 +45,8 @@ async function add() {
   busy.value = true
   problem.value = ''
   try {
-    await api.addRepository(listing.value.path, name.value.trim())
-    await api.index('', { everything: true })
+    const repository = await api.addRepository(listing.value.path, name.value.trim())
+    await api.index(repository.name)
     emit('added')
     emit('close')
   } catch (error) {
@@ -96,6 +96,9 @@ async function add() {
     <Notice v-if="problem" tone="danger" class="mt-3">
       {{ problem }}
     </Notice>
+    <p v-if="busy" role="status" class="mt-3 text-sm text-muted-foreground">
+      Reading this repository. Large repositories can take several minutes.
+    </p>
 
     <div class="flex items-center gap-2 pt-5">
       <UiButton :disabled="busy || !listing" @click="add">
diff --git a/ui/src/components/GraphWorkbench.vue b/ui/src/components/GraphWorkbench.vue
index bddc088..82f78d5 100644
--- a/ui/src/components/GraphWorkbench.vue
+++ b/ui/src/components/GraphWorkbench.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { CodeGraph as KnowledgeGraph, Tabs, useContextKinds } from '@sourceant/design'
+import { Button, CodeGraph as KnowledgeGraph, Loading, LoadFailure, Tabs, useContextKinds } from '@sourceant/design'
 import { computed, ref, watch } from 'vue'
 import { Crosshair, Network, Search, X } from 'lucide-vue-next'
 import type { KnowledgeGraphData } from '~/types'
@@ -76,6 +76,9 @@ const focusLabel = computed(() => {
 })
 
 const parts = computed(() => drawn.value?.communities ?? [])
+const partsShown = ref(50)
+const visibleParts = computed(() => parts.value.slice(0, partsShown.value))
+watch(parts, () => { partsShown.value = 50 })
 
 const modes: { id: Mode, label: string }[] = [
   { id: '2d', label: '2D' },
@@ -234,7 +237,7 @@ defineExpose({ reload: loadGraph })
       <div v-if="offers('parts') && source === 'code' && parts.length">
         <p class="mb-1.5 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">Parts</p>
         <ul class="space-y-0.5">
-          <li v-for="p in parts" :key="p.id">
+          <li v-for="p in visibleParts" :key="p.id">
             <button
               type="button"
               class="flex w-full items-center gap-2 rounded-md px-1 py-1 text-left text-[11px] transition-colors hover:bg-muted"
@@ -247,6 +250,13 @@ defineExpose({ reload: loadGraph })
             </button>
           </li>
         </ul>
+        <Button
+          v-if="partsShown < parts.length"
+          variant="ghost"
+          size="sm"
+          class="mt-2 w-full"
+          @click="partsShown += 50"
+        >Show more parts ({{ partsShown }} of {{ parts.length }})</Button>
         <p class="mt-1.5 text-[11px] text-muted-foreground">
           Grouped by what calls what. Click one to hide it.
         </p>
@@ -320,12 +330,16 @@ defineExpose({ reload: loadGraph })
       <div class="grid gap-4" :class="$slots.inspector ? 'lg:grid-cols-[1fr_20rem]' : ''">
         <div class="min-w-0">
           <div class="overflow-hidden rounded-lg border bg-card">
-            <UiLoadFailure v-if="problem" what="this graph" :message="problem" @retry="loadGraph" />
-
-            <div v-else-if="busy" :style="{ height }">
-              <UiLoadingState :label="source === 'code' ? 'Reading the code' : 'Reading the knowledge graph'" compact />
+            <div v-if="busy" :style="{ height }">
+              <Loading
+                :label="source === 'code' ? 'Reading the code' : 'Reading the knowledge graph'"
+                note="Large repositories can take longer to load."
+                size="sm"
+              />
             </div>
 
+            <LoadFailure v-else-if="problem" what="this graph" :message="problem.message" @retry="loadGraph" />
+
             <div v-else-if="!hasRealGraph" class="flex flex-col items-center justify-center gap-3 px-6 text-center" :style="{ height }">
               <Network class="h-7 w-7 text-muted-foreground" />
               <div class="space-y-1">
@@ -354,9 +368,12 @@ defineExpose({ reload: loadGraph })
             More than fits in one drawing, so this is the most connected part of it.
             Narrow it{{ railed ? ' on the left' : '' }}, or click something to walk out from it.
           </p>
-          <p v-else-if="hasRealGraph" class="mt-2 text-xs text-muted-foreground">
+          <p v-if="hasRealGraph" class="mt-2 text-xs text-muted-foreground">
             {{ drawn?.nodes.length }} symbols, {{ drawn?.links.length }} connections.
           </p>
+          <p v-if="hasRealGraph && !drawn?.links.length" class="mt-2 text-xs text-muted-foreground">
+            No connections were found between these files.
+          </p>
         </div>
 
         <div v-if="$slots.inspector" class="overflow-y-auto rounded-lg border bg-card" :style="{ height }">
diff --git a/ui/src/components/Onboarding.vue b/ui/src/components/Onboarding.vue
index b28fa18..63a82fd 100644
--- a/ui/src/components/Onboarding.vue
+++ b/ui/src/components/Onboarding.vue
@@ -40,7 +40,8 @@ onMounted(async () => {
   }
   if (asked) return
   await fetchRepositories()
-  open.value = repositories.value.length === 0
+  step.value = repositories.value.length ? 'model' : 'folder'
+  open.value = true
 })
 </script>
 
@@ -67,17 +68,14 @@ onMounted(async () => {
     </template>
 
     <template v-else>
-      <h2 class="text-lg font-semibold mb-1">Bring a model, or don't</h2>
+      <h2 class="text-lg font-semibold mb-1">Add a model and API key</h2>
       <p class="text-sm text-muted-foreground mb-5">
         Reading your code and reading what it already states about itself need no model at
         all. Proposing what nobody wrote down does. Your key stays on this machine and goes
         to that provider and nowhere else.
       </p>
-      <SettingsPanel group="Model" @saved="remember">
-        <template #after>
-          <UiButton variant="ghost" @click="remember">Not now</UiButton>
-        </template>
-      </SettingsPanel>
+      <SettingsPanel group="Model" @saved="remember" />
+      <UiButton variant="ghost" class="mt-4" @click="remember">Skip for now</UiButton>
     </template>
   </UiModal>
 </template>
diff --git a/ui/src/composables/useCodeGraph.js b/ui/src/composables/useCodeGraph.js
index 0374985..aa4f719 100644
--- a/ui/src/composables/useCodeGraph.js
+++ b/ui/src/composables/useCodeGraph.js
@@ -9,6 +9,7 @@ export function useCodeGraph() {
 
   async function fetchCodeGraph(owner, repo, ask = {}) {
     loading.value = true
+    problem.value = null
     try {
       graph.value = await api.graph(`${owner}/${repo}`, ask)
       problem.value = null

From 6f83d7cfc55deb306237fae5b390adac79986441 Mon Sep 17 00:00:00 2001
From: nfebe <fenn25.fn@gmail.com>
Date: Mon, 7 Sep 2026 23:13:31 +0100
Subject: [PATCH 2/4] fix(ui): Use available controls for graph errors

---
 ui/src/components/GraphWorkbench.vue | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/ui/src/components/GraphWorkbench.vue b/ui/src/components/GraphWorkbench.vue
index 82f78d5..88010c8 100644
--- a/ui/src/components/GraphWorkbench.vue
+++ b/ui/src/components/GraphWorkbench.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { Button, CodeGraph as KnowledgeGraph, Loading, LoadFailure, Tabs, useContextKinds } from '@sourceant/design'
+import { Button, CodeGraph as KnowledgeGraph, Loading, Tabs, useContextKinds } from '@sourceant/design'
 import { computed, ref, watch } from 'vue'
 import { Crosshair, Network, Search, X } from 'lucide-vue-next'
 import type { KnowledgeGraphData } from '~/types'
@@ -330,7 +330,7 @@ defineExpose({ reload: loadGraph })
       <div class="grid gap-4" :class="$slots.inspector ? 'lg:grid-cols-[1fr_20rem]' : ''">
         <div class="min-w-0">
           <div class="overflow-hidden rounded-lg border bg-card">
-            <div v-if="busy" :style="{ height }">
+            <div v-if="busy" class="flex" :style="{ height }">
               <Loading
                 :label="source === 'code' ? 'Reading the code' : 'Reading the knowledge graph'"
                 note="Large repositories can take longer to load."
@@ -338,7 +338,11 @@ defineExpose({ reload: loadGraph })
               />
             </div>
 
-            <LoadFailure v-else-if="problem" what="this graph" :message="problem.message" @retry="loadGraph" />
+            <div v-else-if="problem" role="alert" class="flex flex-col items-center justify-center gap-3 px-6 text-center" :style="{ height }">
+              <p class="text-sm font-medium">Could not load this graph</p>
+              <p class="text-xs text-muted-foreground">{{ problem.message }}</p>
+              <Button variant="outline" size="sm" @click="loadGraph">Try again</Button>
+            </div>
 
             <div v-else-if="!hasRealGraph" class="flex flex-col items-center justify-center gap-3 px-6 text-center" :style="{ height }">
               <Network class="h-7 w-7 text-muted-foreground" />

From 6fddf11a1b553804c1afa128921045bc1f180e72 Mon Sep 17 00:00:00 2001
From: nfebe <fenn25.fn@gmail.com>
Date: Mon, 7 Sep 2026 23:52:07 +0100
Subject: [PATCH 3/4] fix(runtime): Stop only the container owned by this agent

---
 README.md                        |  4 ++++
 cmd/agent/main.go                |  2 +-
 internal/runtime/runtime.go      | 15 +++++++++------
 internal/runtime/runtime_test.go | 18 ++++++++++++++++++
 4 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 9f02ab4..d0fb4c6 100644
--- a/README.md
+++ b/README.md
@@ -47,3 +47,7 @@ make build
 ## Licence
 
 MIT.
+
+## Versioning
+
+The agent is versioned independently of the CLI, core, and design package. Its release number does not select the core version. Setup records the core image or Python executable that the agent starts.
diff --git a/cmd/agent/main.go b/cmd/agent/main.go
index 37028ce..ca9994d 100644
--- a/cmd/agent/main.go
+++ b/cmd/agent/main.go
@@ -78,7 +78,7 @@ func run() error {
 		coreErr = supervisor.Run(ctx)
 		cleanup, cancel := context.WithTimeout(context.Background(), 8*time.Second)
 		defer cancel()
-		if err := installed.Stop(cleanup, port); err != nil && coreErr == nil {
+		if err := installed.Stop(cleanup); err != nil && coreErr == nil {
 			coreErr = err
 		}
 	}()
diff --git a/internal/runtime/runtime.go b/internal/runtime/runtime.go
index 24df27a..bfc0644 100644
--- a/internal/runtime/runtime.go
+++ b/internal/runtime/runtime.go
@@ -8,6 +8,7 @@ package runtime
 
 import (
 	"context"
+	"crypto/rand"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -35,7 +36,8 @@ const DefaultImage = "ghcr.io/sourceant/sourceant:latest"
 
 // Core is everything needed to start the indexer.
 type Core struct {
-	Runtime Kind `json:"runtime"`
+	containerName string
+	Runtime       Kind `json:"runtime"`
 	// Command is the executable, for the python runtime.
 	Command string `json:"command,omitempty"`
 	// Image is the container, for the docker runtime.
@@ -122,7 +124,7 @@ func Save(path string, config Config) error {
 // this machine binds loopback and is reached there. A container binding
 // loopback would bind the container's own, reachable by nothing, so it binds
 // every interface inside and is published to loopback outside.
-func (c Core) Serve(port int) (string, []string, error) {
+func (c *Core) Serve(port int) (string, []string, error) {
 	number := strconv.Itoa(port)
 	switch c.Runtime {
 	case Python:
@@ -131,13 +133,14 @@ func (c Core) Serve(port int) (string, []string, error) {
 		}
 		return c.Command, []string{"serve", "--host", "127.0.0.1", "--port", number}, nil
 	case Docker:
+		c.containerName = "sourceant-core-" + rand.Text()
 		image := c.Image
 		if image == "" {
 			image = DefaultImage
 		}
 		args := []string{
 			"run", "--rm",
-			"--name", "sourceant-core-" + number,
+			"--name", c.containerName,
 			"-p", "127.0.0.1:" + number + ":" + number,
 		}
 		if c.DataDir != "" {
@@ -213,11 +216,11 @@ func throughTheHost(address string) string {
 	return parsed.String()
 }
 
-func (c Core) Stop(ctx context.Context, port int) error {
-	if c.Runtime != Docker {
+func (c Core) Stop(ctx context.Context) error {
+	if c.Runtime != Docker || c.containerName == "" {
 		return nil
 	}
-	name := "sourceant-core-" + strconv.Itoa(port)
+	name := c.containerName
 	output, err := exec.CommandContext(ctx, "docker", "container", "ls", "--all", "--format", "{{.Names}}").CombinedOutput()
 	if err != nil {
 		return fmt.Errorf("checking the core container: %w: %s", err, output)
diff --git a/internal/runtime/runtime_test.go b/internal/runtime/runtime_test.go
index ac1d009..f29c049 100644
--- a/internal/runtime/runtime_test.go
+++ b/internal/runtime/runtime_test.go
@@ -133,3 +133,21 @@ func TestADataDirNobodyChoseIsNotMounted(t *testing.T) {
 		t.Errorf("mounted something without being told where: %v", args)
 	}
 }
+
+func TestDockerLaunchesOnTheSamePortHaveDifferentOwners(t *testing.T) {
+	first := Core{Runtime: Docker}
+	second := Core{Runtime: Docker}
+	_, firstArgs, err := first.Serve(8931)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, secondArgs, err := second.Serve(8931)
+	if err != nil {
+		t.Fatal(err)
+	}
+	firstName := firstArgs[slices.Index(firstArgs, "--name")+1]
+	secondName := secondArgs[slices.Index(secondArgs, "--name")+1]
+	if firstName == secondName || firstName != first.containerName || secondName != second.containerName {
+		t.Fatalf("container ownership overlaps: %q and %q", firstName, secondName)
+	}
+}

From fe033aca743b1566adb3c5ca81be1dd6505e08a5 Mon Sep 17 00:00:00 2001
From: nfebe <fenn25.fn@gmail.com>
Date: Mon, 7 Sep 2026 23:59:22 +0100
Subject: [PATCH 4/4] docs(release): Prepare 1.0.0-beta.3

---
 CHANGELOG.md | 18 ++++++++++++++++++
 README.md    |  2 ++
 VERSION      |  2 +-
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5aded10..4699b64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0-beta.3]
+
+### Added
+
+- Local stack shutdown waits for core cleanup and only stops this agent's container.
+- Graph loading and failure states explain the wait and allow retrying.
+- Model setup offers an optional skip, including when settings cannot load.
+
+### Fixed
+
+- Large graphs display their group controls in batches.
+- Adding a folder indexes only that repository.
+
+### Compatibility
+
+- Core `1.0.0-beta.2` is the compatibility baseline for this release.
+- Newer core beta releases require compatibility checks before being added to the supported set.
+
 ## [1.0.0-beta.2] - 2026-08-30
 
 First release, versioned alongside the core it supervises.
diff --git a/README.md b/README.md
index d0fb4c6..b235992 100644
--- a/README.md
+++ b/README.md
@@ -51,3 +51,5 @@ MIT.
 ## Versioning
 
 The agent is versioned independently of the CLI, core, and design package. Its release number does not select the core version. Setup records the core image or Python executable that the agent starts.
+
+Agent `1.0.0-beta.3` uses core `1.0.0-beta.2` as its compatibility baseline. Older cores are outside this release's supported baseline. No maximum core version is declared; this does not promise compatibility with future beta releases. Startup checks core health but does not enforce a version range. Select a known core release with `sourceant setup --core-version 1.0.0-beta.2`.
diff --git a/VERSION b/VERSION
index 7e0b231..b0a2ffd 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.0.0-beta.2
+1.0.0-beta.3