@doriandev/devcc 0.1.2 → 0.3.0

package/src/devcc/app/App.ts

@@ -1,6 +1,10 @@
 import { BoxRenderable, createCliRenderer, type CliRenderer, type KeyEvent } from "@opentui/core"
-import { existsSync } from "node:fs"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { basename, join, resolve } from "node:path"
+import { AgentManager, createAgentAdapters } from "../agents/agents.js"
+import { configProblems } from "../automation.js"
+import { detectProject, renderStarterConfig } from "../init/detect.js"
+import { buildSetupPrompt, extractConfigFromOutput } from "../init/prompt.js"
 import { ConfirmDialog, PromptDialog } from "../components/ConfirmDialog.js"
 import { Footer, type KeyHint } from "../components/Footer.js"
 import { Header } from "../components/Header.js"
@@ -10,7 +14,8 @@ import { Sidebar } from "../components/Sidebar.js"
 import { CommandPalette } from "../components/CommandPalette.js"
 import { ProjectPicker } from "../components/ProjectPicker.js"
 import { CommandRegistry, type CommandContext } from "../core/commands.js"
-import { loadConfig, type CommandConfigEntry, type ResolvedConfig } from "../core/config.js"
+import { loadConfig, loadConfigFile, type CommandConfigEntry, type ResolvedConfig } from "../core/config.js"
+import { EnvironmentService, type EnvironmentSnapshot } from "../environment/EnvironmentService.js"
 import { Subscriptions } from "../core/events.js"
 import {
   createInitialSelection,
@@ -26,10 +31,12 @@ import {
   type NotificationLevel,
   type ProjectState,
   type ScriptRun,
+  type VerifyState,
   type ViewId,
 } from "../core/state.js"
 import { DependencyService, updateArgs } from "../deps/DependencyService.js"
 import { GitService } from "../git/GitService.js"
+import { defaultWorktreePath, removalBlocker, worktreeLabel, type GitWorktree } from "../git/worktrees.js"
 import {
   buildProjectList,
   defaultSearchDirs,
@@ -40,20 +47,36 @@ import {
 } from "../projects/ProjectRegistry.js"
 import { LogStore, MAX_LOG_LINES } from "../logs/LogBuffer.js"
 import { ALL_SOURCES } from "../logs/merge.js"
-import { isActive } from "../processes/ManagedProcess.js"
+import { isActive, type ManagedProcess } from "../processes/ManagedProcess.js"
+import {
+  editorCommand,
+  launchDetached,
+  sshCommand,
+  terminalCommand,
+  type LaunchCommand,
+} from "../platform/launch.js"
 import { ProcessManager } from "../processes/ProcessManager.js"
 import { DockerService } from "../services/docker.js"
 import { detectNodeServices, PortService } from "../services/node.js"
 import { OllamaService } from "../services/ollama.js"
 import { PostgresService } from "../services/postgres.js"
 import { RedisService } from "../services/redis.js"
+import { RemoteMachineService, TailscaleService } from "../services/remote.js"
 import { ServiceManager } from "../services/ServiceManager.js"
-import { SystemMonitor } from "../system/SystemMonitor.js"
+import { SystemMonitor, type ToolVersions } from "../system/SystemMonitor.js"
 import { errorMessage, toDevccError } from "../utils/errors.js"
 import { createLogger, type Logger } from "../utils/logger.js"
 import { detectPackageManager, readPackageJson, readScripts, runScriptArgs } from "../utils/packageManager.js"
 import { fuzzyFilter } from "../utils/fuzzy.js"
-import { findProjectRoot } from "../utils/paths.js"
+import { findProjectRoot, tildify } from "../utils/paths.js"
+import {
+  isVerifyIssue,
+  resolveVerifySteps,
+  runVerification,
+  summariseVerify,
+  type StepExecutor,
+  type VerifyStep,
+} from "../verify/verify.js"
 import { DependenciesView } from "../views/DependenciesView.js"
 import { GitView } from "../views/GitView.js"
 import { LogsView } from "../views/LogsView.js"
@@ -63,8 +86,10 @@ import { ScriptsView, scriptProcessId } from "../views/ScriptsView.js"
 import { ServicesView } from "../views/ServicesView.js"
 import { SettingsView } from "../views/SettingsView.js"
 import { SystemView } from "../views/SystemView.js"
+import { WorktreesView, selectedWorktreeEntry } from "../views/WorktreesView.js"
 import type { View, ViewDeps } from "../views/View.js"
 import { createBuiltinCommands, createConfigCommands, createScriptCommands } from "./builtinCommands.js"
+import { createControlPlaneCommands } from "./controlPlaneCommands.js"
 import { HELP_SECTIONS, VIEW_SHORTCUTS } from "./keymap.js"
 import { theme } from "./theme.js"
 
@@ -101,7 +126,17 @@ interface ProjectSession {
   git: GitService
   system: SystemMonitor
   deps: DependencyService
+  agents: AgentManager
+  environment: EnvironmentService
   project: ProjectState
+  /** Verification steps resolved from config, and the latest run. */
+  verifySteps: VerifyStep[]
+  verify: VerifyState
+  /** Config problems that make verification untrustworthy; running is refused while any exist. */
+  verifyIssues: string[]
+  verifyAbort: AbortController | null
+  /** The agent session proposing a .devcc.ts, if one is running. */
+  setupAgentSessionId: string | null
   scripts: { name: string; command: string }[]
   /** Script runs belong to the project they ran in, not to the store. */
   scriptRuns: Record<string, ScriptRun>
@@ -151,6 +186,12 @@ export class App {
   private get deps(): DependencyService {
     return this.session.deps
   }
+  private get agents(): AgentManager {
+    return this.session.agents
+  }
+  private get environment(): EnvironmentService {
+    return this.session.environment
+  }
   private get config(): ResolvedConfig {
     return this.session.config
   }
@@ -242,21 +283,36 @@ export class App {
       logger: logger.child("services"),
       intervalMs: config.refresh.services,
     })
+    const tailscale = new TailscaleService({
+      machines: config.remoteMachines,
+      logger: logger.child("tailscale"),
+    })
     services.registerAll([
       new DockerService({ rootDir }),
       new PostgresService(),
       new RedisService(),
       new OllamaService(),
       ...detectNodeServices(packageJson),
-      ...config.services.map(
-        (entry) =>
-          new PortService({
-            id: entry.id,
-            name: entry.name,
-            port: entry.port,
-            host: entry.host,
-            healthPath: entry.healthPath,
-            category: entry.category,
+      ...config.services.map((entry) =>
+        entry.type === "ollama"
+          ? new OllamaService({ id: entry.id, name: entry.name, baseUrl: entry.baseUrl })
+          : new PortService({
+              id: entry.id,
+              name: entry.name,
+              port: entry.port,
+              host: entry.host,
+              healthPath: entry.healthPath,
+              category: entry.category,
+            }),
+      ),
+      tailscale,
+      ...config.remoteMachines.map(
+        (machine) =>
+          new RemoteMachineService({
+            machine,
+            tailscale: () => tailscale.getLastStatus(),
+            service: (id) => services.get(id),
+            logger: logger.child("remote"),
           }),
       ),
     ])
@@ -267,13 +323,25 @@ export class App {
       manager: packageManager.manager,
       logger: logger.child("deps"),
     })
+    const agents = new AgentManager({
+      processes,
+      adapters: createAgentAdapters(config.agents),
+      logger: logger.child("agents"),
+    })
+    const environment = new EnvironmentService({ rootDir, logger: logger.child("environment") })
+    const scripts = readScripts(packageJson)
+    const resolvedVerify = resolveVerifySteps(config.verify, {
+      commands: config.commands,
+      scripts,
+      packageManager: packageManager.manager,
+    })
 
     const project: ProjectState = {
       name: config.name ?? (typeof packageJson?.name === "string" ? packageJson.name : basename(rootDir)),
       rootDir,
       packageManager,
       configPath: loaded.filePath,
-      configIssues: loaded.issues,
+      configIssues: [...loaded.issues, ...resolvedVerify.issues],
       host: system.getHostInfo(),
       tools: { git: null, docker: null, packageManager: null },
     }
@@ -291,8 +359,15 @@ export class App {
       git,
       system,
       deps,
+      agents,
+      environment,
       project,
-      scripts: readScripts(packageJson),
+      verifySteps: resolvedVerify.steps,
+      verify: { configured: resolvedVerify.steps.length, running: false, steps: [] },
+      verifyIssues: [...loaded.issues.filter(isVerifyIssue), ...resolvedVerify.issues],
+      verifyAbort: null,
+      setupAgentSessionId: null,
+      scripts,
       scriptRuns: {},
       wiring: new Subscriptions(),
       timers: [],
@@ -307,12 +382,21 @@ export class App {
     this.commands.registerAll(
       createConfigCommands(this.config.commands, (entry) => this.runConfigCommand(entry)),
     )
+    this.commands.registerAll(
+      createControlPlaneCommands({
+        agents: this.session.agents.list(),
+        machines: this.config.remoteMachines,
+      }),
+    )
   }
 
   private reportConfigIssues(): void {
     for (const issue of this.session.project.configIssues) {
       this.pushNotification("warn", `Config: ${issue}`)
     }
+    if (!this.session.project.configPath) {
+      this.pushNotification("info", "No .devcc.ts yet: press / and run “Project: set up .devcc.ts”")
+    }
   }
 
   // ---------------------------------------------------------------------
@@ -366,6 +450,7 @@ export class App {
       new ServicesView(deps),
       new ScriptsView(deps),
       new GitView(deps),
+      new WorktreesView(deps),
       new LogsView(deps),
       new DependenciesView(deps),
       new SystemView(deps),
@@ -429,13 +514,13 @@ export class App {
    */
   private wireSession(session: ProjectSession): void {
     const { store } = this
-    const { wiring, processes, services, git, system, logs, deps } = session
+    const { wiring, processes, services, git, system, logs, deps, environment } = session
     const active = () => this.session === session
     const notify = (level: NotificationLevel, message: string, detail?: string) =>
       this.pushNotification(level, active() ? message : `[${session.project.name}] ${message}`, detail)
 
     const syncProcesses = () => {
-      if (active()) store.patch({ processes: processes.list() })
+      if (active()) store.patch({ processes: processes.list(), agents: session.agents.sessions() })
       this.refreshSidebarProjects()
     }
     processes.on("process:changed", syncProcesses)
@@ -443,6 +528,7 @@ export class App {
     processes.on("process:exit", (process) => {
       this.finishScriptRun(session, process.id, process.exitCode ?? 0)
       syncProcesses()
+      if (process.id === session.setupAgentSessionId) void this.finishConfigSetup(session, process)
     })
     processes.on("process:error", (error) => notify("error", error.message, error.detail))
     processes.on("process:retry", (managed, delayMs) => {
@@ -473,11 +559,16 @@ export class App {
     system.on("system:metrics", (metrics) => {
       if (active()) store.patch({ system: metrics })
     })
-    system.on("system:tools", (tools) => {
+    wiring.add(() => system.removeAllListeners())
+
+    environment.on("environment:changed", (snapshot) => {
+      const tools = toolVersionsFrom(snapshot, session.project.packageManager.manager)
       session.project = { ...session.project, tools }
-      if (active()) store.setState((state) => ({ ...state, project: { ...state.project, tools } }))
+      if (active()) {
+        store.setState((state) => ({ ...state, environment: snapshot, project: { ...state.project, tools } }))
+      }
     })
-    wiring.add(() => system.removeAllListeners())
+    wiring.add(() => environment.removeAllListeners())
 
     logs.on("log:sources", (sources) => {
       if (!active()) return
@@ -540,6 +631,9 @@ export class App {
     this.subscriptions.add(store.watch((state) => state.services, markDirty, shallowArrayEqual))
     this.subscriptions.add(store.watch((state) => state.git, markDirty))
     this.subscriptions.add(store.watch((state) => state.dependencies, markDirty))
+    this.subscriptions.add(store.watch((state) => state.agents, markDirty, shallowArrayEqual))
+    this.subscriptions.add(store.watch((state) => state.environment, markDirty))
+    this.subscriptions.add(store.watch((state) => state.verify, markDirty))
     this.subscriptions.add(store.watch((state) => state.projects, markDirty, shallowArrayEqual))
     this.subscriptions.add(store.watch((state) => state.system, markDirty))
     this.subscriptions.add(store.watch((state) => state.scripts, markDirty))
@@ -557,6 +651,7 @@ export class App {
       processes: this.processes.list(),
       services: this.services.list(),
       logSources: this.logs.sources(),
+      verify: this.session.verify,
     })
     store.setState((state) => ({
       ...state,
@@ -596,7 +691,8 @@ export class App {
 
     void session.git.refresh()
     void session.services.detectAll().then(() => session.services.start())
-    void session.system.refreshTools(session.project.packageManager.manager)
+    // Tool versions change rarely: detect once per project, refresh on request.
+    if (!session.environment.getSnapshot().checkedAt) void session.environment.refresh()
     if (!session.processes.list().some((entry) => entry.startedAt)) {
       // Autostart only the first time a project is opened, never on reactivation.
       void session.processes.startAutoStart()
@@ -759,6 +855,11 @@ export class App {
       void this.commands.run("app.refresh", this.context)
       return
     }
+    if (key.shift && key.name === "v") {
+      key.preventDefault()
+      void this.runCommand("verify.run")
+      return
+    }
 
     const state = this.store.getState()
 
@@ -1035,6 +1136,8 @@ export class App {
       logs: this.logs,
       system: this.system,
       deps: this.deps,
+      agents: this.agents,
+      environment: this.environment,
       navigate: (view) => updateUi(this.store, { view }),
       notify: (level, message, detail) => this.pushNotification(level, message, detail),
       confirm: (title, message) => this.askConfirm(title, message),
@@ -1046,6 +1149,17 @@ export class App {
       openProjects: () => this.openProjects(),
       switchProject: (path) => this.openProject(path),
       closeProject: (path) => this.closeProject(path),
+      selectedWorktree: () => this.selectedWorktree(),
+      createWorktree: () => this.createWorktree(),
+      removeWorktree: (worktree) => this.removeWorktree(worktree),
+      launchAgent: (agentId, worktree) => this.launchAgent(agentId, worktree),
+      openInEditor: (path) => this.launch(() => editorCommand(path, this.config.editor), path),
+      openInTerminal: (path) => this.launch(() => terminalCommand(path, this.config.terminal), path),
+      runVerify: () => this.runVerify(),
+      remoteMachines: () => this.config.remoteMachines,
+      sshTo: (machineId) => this.sshTo(machineId),
+      setUpConfig: (how) => this.setUpConfig(how),
+      reloadConfig: () => this.reloadConfig(),
       quit: () => void this.quit(),
     }
 
@@ -1058,6 +1172,8 @@ export class App {
       logs: { get: () => this.logs, enumerable: true },
       system: { get: () => this.system, enumerable: true },
       deps: { get: () => this.deps, enumerable: true },
+      agents: { get: () => this.agents, enumerable: true },
+      environment: { get: () => this.environment, enumerable: true },
     })
 
     return context
@@ -1262,6 +1378,9 @@ export class App {
       scripts: { available: session.scripts, runs: session.scriptRuns },
       git: session.git.getSnapshot(),
       dependencies: session.deps.getSnapshot(),
+      agents: session.agents.sessions(),
+      environment: session.environment.getSnapshot(),
+      verify: session.verify,
       system: session.system.getMetrics(),
       logSources: session.logs.sources(),
       projects: [],
@@ -1349,6 +1468,379 @@ export class App {
     )
   }
 
+  // ---------------------------------------------------------------------
+  // Worktrees, agents, verification, remote
+  // ---------------------------------------------------------------------
+
+  private selectedWorktree(): GitWorktree | undefined {
+    const state = this.store.getState()
+    if (state.ui.view === "worktrees") {
+      const entry = selectedWorktreeEntry(state)
+      if (entry?.worktree) return entry.worktree
+    }
+    return state.git.worktrees.find((worktree) => worktree.isCurrent)
+  }
+
+  private async createWorktree(): Promise<void> {
+    const snapshot = this.git.getSnapshot()
+    if (!snapshot.isRepository) {
+      this.pushNotification("warn", "Not a git repository")
+      return
+    }
+    const main = snapshot.worktrees.find((worktree) => worktree.isMain)
+    if (!main) {
+      this.pushNotification("warn", "Could not read this repository's worktrees yet")
+      return
+    }
+
+    const branch = (
+      await this.askPrompt("New worktree: branch (created if it does not exist)", "feature/name")
+    )?.trim()
+    if (!branch) return
+    const current = snapshot.status.branch ?? "HEAD"
+    const base = await this.askPrompt(`Base for ${branch} (empty: ${current})`, current)
+    if (base === null) return
+    const suggested = defaultWorktreePath(main.path, branch, this.config.worktrees?.directory)
+    const path = await this.askPrompt(`Directory (empty: ${tildify(suggested)})`, tildify(suggested))
+    if (path === null) return
+
+    const target = path.trim() === "" ? suggested : resolve(main.path, expandHome(path.trim()))
+    try {
+      this.footer.setStatus(`Creating worktree ${branch}…`)
+      await this.git.createWorktree({ branch, base: base.trim() || undefined, path: target })
+      this.pushNotification("success", `Created worktree ${branch} at ${tildify(target)}`)
+    } catch (error) {
+      const devccError = toDevccError(error, "git")
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  private async removeWorktree(worktree: GitWorktree): Promise<void> {
+    const busy = [
+      ...this.agents.busyPaths(),
+      ...this.processes
+        .list()
+        .filter((entry) => isActive(entry.status))
+        .map((entry) => resolve(this.session.rootDir, entry.cwd ?? ".")),
+      // A worktree open as a project in devcc is in use too.
+      ...[...this.sessions.keys()].filter((path) => path !== this.session.rootDir),
+    ]
+    const blocker = removalBlocker(worktree, busy)
+    if (blocker) {
+      this.pushNotification("warn", blocker)
+      return
+    }
+
+    const confirmed = await this.askConfirm(
+      `Remove worktree ${worktreeLabel(worktree)}?`,
+      `Deletes ${tildify(worktree.path)}. The branch is kept. git refuses if there are uncommitted or untracked changes; devcc never forces it.`,
+    )
+    if (!confirmed) return
+
+    try {
+      await this.git.removeWorktree(worktree.path, busy)
+      this.pushNotification("success", `Removed worktree ${worktreeLabel(worktree)}`)
+    } catch (error) {
+      const devccError = toDevccError(error, "git")
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  private async launchAgent(agentId: string, worktree?: GitWorktree): Promise<void> {
+    const adapter = this.agents.get(agentId)
+    if (!adapter) {
+      this.pushNotification("warn", `Unknown agent "${agentId}"`)
+      return
+    }
+    const target = worktree ?? this.selectedWorktree()
+    const cwd = target?.path ?? this.session.rootDir
+    const where = target ? worktreeLabel(target) : basename(cwd)
+
+    const task = await this.askPrompt(
+      `Task for ${adapter.name} in ${where}`,
+      "Describe what the agent should do",
+    )
+    if (task === null || task.trim() === "") return
+
+    try {
+      const session = await this.agents.launch(agentId, { cwd, prompt: task, branch: target?.branch })
+      updateUi(this.store, { logSource: session.id })
+      this.pushNotification("success", `${adapter.name} started in ${where}`)
+    } catch (error) {
+      const devccError = toDevccError(error, "process")
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  /** Build and start an external launch; a missing configuration becomes a notification. */
+  private async launch(build: () => LaunchCommand, cwd: string): Promise<void> {
+    try {
+      const command = build()
+      await launchDetached(command, cwd)
+      this.logger.log("debug", "launch", "opened", { command: command.command, cwd })
+    } catch (error) {
+      const devccError = toDevccError(error, "command")
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  private async sshTo(machineId: string): Promise<void> {
+    const machine = this.config.remoteMachines.find((entry) => entry.id === machineId)
+    if (!machine) {
+      this.pushNotification("warn", `Unknown remote machine "${machineId}"`)
+      return
+    }
+    await this.launch(() => sshCommand(machine, this.config.terminal), this.session.rootDir)
+  }
+
+  /**
+   * Run verification through the ProcessManager: each step is a managed task,
+   * so its output streams into Logs and quitting stops it like anything else.
+   */
+  private async runVerify(): Promise<void> {
+    const session = this.session
+    if (session.verify.running) {
+      this.pushNotification("warn", "Verification is already running")
+      return
+    }
+    if (session.verifyIssues.length > 0) {
+      this.pushNotification(
+        "error",
+        `Verify refused: ${session.verifyIssues[0] ?? "invalid verify config"}`,
+        session.verifyIssues.join("\n"),
+      )
+      return
+    }
+    if (session.verifySteps.length === 0) {
+      this.pushNotification(
+        "warn",
+        "No verification steps configured",
+        'Add verify: ["lint", "test"] to .devcc.ts',
+      )
+      return
+    }
+
+    const controller = new AbortController()
+    session.verifyAbort = controller
+    const publish = (verify: VerifyState) => {
+      session.verify = verify
+      if (session === this.session) this.store.patch({ verify })
+    }
+    const startedAt = new Date()
+    publish({ configured: session.verifySteps.length, running: true, steps: [], startedAt })
+    this.pushNotification("info", `Verifying: ${session.verifySteps.map((step) => step.name).join(", ")}`)
+
+    const report = await runVerification(session.verifySteps, this.processStepExecutor(session), {
+      signal: controller.signal,
+      onProgress: (steps) => publish({ ...session.verify, steps: [...steps] }),
+    })
+
+    session.verifyAbort = null
+    publish({
+      configured: session.verifySteps.length,
+      running: false,
+      steps: report.steps,
+      startedAt,
+      finishedAt: new Date(),
+      ok: report.ok,
+    })
+    this.pushNotification(report.ok ? "success" : "error", `Verify: ${summariseVerify(report)}`)
+  }
+
+  private processStepExecutor(session: ProjectSession): StepExecutor {
+    return async (step, signal) => {
+      const { processes } = session
+      const id = `verify:${step.id}`
+      if (processes.isRunning(id)) return { exitCode: null, error: "already running" }
+
+      processes.register({
+        id,
+        name: `verify · ${step.name}`,
+        command: step.command,
+        args: step.args,
+        cwd: step.cwd,
+        env: { NO_COLOR: "1" },
+        kind: "task",
+      })
+
+      let onChange: ((snapshot: ManagedProcess) => void) | undefined
+      const finished = new Promise<ManagedProcess>((resolveFinished) => {
+        let started = false
+        onChange = (snapshot: ManagedProcess) => {
+          if (snapshot.id !== id) return
+          if (snapshot.status === "starting" || snapshot.status === "running") started = true
+          else if (started && (snapshot.status === "stopped" || snapshot.status === "failed")) {
+            resolveFinished(snapshot)
+          }
+        }
+        processes.on("process:changed", onChange)
+      })
+      const onAbort = () => void processes.stop(id).catch(() => undefined)
+      signal.addEventListener("abort", onAbort, { once: true })
+
+      try {
+        if (session === this.session) updateUi(this.store, { logSource: id })
+        await processes.start(id)
+        const result = await finished
+        return {
+          exitCode: result.exitCode ?? null,
+          error: signal.aborted
+            ? "cancelled"
+            : result.exitSignal
+              ? `terminated by ${result.exitSignal}`
+              : result.exitCode === undefined
+                ? result.lastError
+                : undefined,
+        }
+      } catch (error) {
+        return { exitCode: null, error: errorMessage(error) }
+      } finally {
+        signal.removeEventListener("abort", onAbort)
+        // Also runs when start() throws, so the listener never outlives the step.
+        if (onChange) processes.off("process:changed", onChange)
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // Project setup (.devcc.ts)
+  // ---------------------------------------------------------------------
+
+  private async setUpConfig(how: string): Promise<void> {
+    const session = this.session
+    const facts = detectProject(session.rootDir)
+
+    if (how === "starter") {
+      if (facts.configPath) {
+        const replace = await this.askConfirm(
+          "Replace the existing config with a starter?",
+          `${tildify(facts.configPath)} will be overwritten with what devcc detects. Consider setting it up with an agent instead, which keeps what is still right.`,
+        )
+        if (!replace) return
+      }
+      const target = join(session.rootDir, ".devcc.ts")
+      writeFileSync(target, renderStarterConfig(facts), "utf8")
+      this.pushNotification("success", `Created ${tildify(target)}`)
+      await this.reloadConfig()
+      return
+    }
+
+    const adapter = this.agents.get(how)
+    if (!adapter) {
+      this.pushNotification("warn", `Unknown agent "${how}"`)
+      return
+    }
+    if (session.setupAgentSessionId && session.processes.isRunning(session.setupAgentSessionId)) {
+      this.pushNotification("warn", "An agent is already setting up .devcc.ts")
+      return
+    }
+
+    try {
+      const agentSession = await this.agents.launch(how, {
+        cwd: session.rootDir,
+        prompt: buildSetupPrompt(facts, "print"),
+      })
+      session.setupAgentSessionId = agentSession.id
+      updateUi(this.store, { logSource: agentSession.id })
+      this.pushNotification(
+        "info",
+        `${adapter.name} is reading the project; devcc will offer its .devcc.ts when it finishes`,
+      )
+    } catch (error) {
+      const devccError = toDevccError(error, "process")
+      this.pushNotification("error", devccError.message, devccError.detail)
+    }
+  }
+
+  /**
+   * The setup agent exited: take the config it printed, validate it from a
+   * scratch file under .devcc/, and write it only if the user agrees.
+   */
+  private async finishConfigSetup(session: ProjectSession, agent: ManagedProcess): Promise<void> {
+    session.setupAgentSessionId = null
+    const name = session.project.name
+    if (agent.exitCode !== 0) {
+      this.pushNotification(
+        "error",
+        `[${name}] Config setup agent exited with code ${agent.exitCode ?? "?"}; see its logs`,
+      )
+      return
+    }
+
+    const output = (session.logs.get(agent.id)?.toArray() ?? [])
+      .filter((entry) => entry.stream !== "system")
+      .map((entry) => entry.text)
+      .join("\n")
+    const proposal = extractConfigFromOutput(output)
+    if (!proposal) {
+      this.pushNotification("warn", `[${name}] The agent did not print a .devcc.ts; see its logs`)
+      return
+    }
+
+    const scratchDir = join(session.rootDir, ".devcc")
+    const proposedPath = join(scratchDir, "proposed.devcc.ts")
+    mkdirSync(scratchDir, { recursive: true })
+    writeFileSync(proposedPath, proposal, "utf8")
+    const loaded = await loadConfigFile(proposedPath)
+    const problems = configProblems(session.rootDir, loaded)
+    const { config } = loaded
+
+    const current = session.project.configPath
+    const target = current && !current.endsWith(".json") ? current : join(session.rootDir, ".devcc.ts")
+    const summary = [
+      `${config.processes.length} process(es), ${config.commands.length} command(s), verify: ${
+        config.verify.map((entry) => (typeof entry === "string" ? entry : entry.id)).join(", ") || "none"
+      }.`,
+      problems.length > 0 ? `${problems.length} issue(s): ${problems[0] ?? ""}` : "It validates cleanly.",
+      `Review it first in ${tildify(proposedPath)}.`,
+    ].join(" ")
+
+    const write = await this.askConfirm(
+      `Write ${current ? "the updated" : "the proposed"} ${tildify(target)}?`,
+      summary,
+    )
+    if (!write) {
+      this.pushNotification("info", `Kept the proposal at ${tildify(proposedPath)}`)
+      return
+    }
+    writeFileSync(target, proposal, "utf8")
+    this.pushNotification("success", `Wrote ${tildify(target)}`)
+    if (session === this.session) await this.reloadConfig()
+    else this.pushNotification("info", `Switch to ${name} and reload its config to use it`)
+  }
+
+  /** Rebuild the active project's session so a changed config takes effect. */
+  private async reloadConfig(): Promise<void> {
+    const previous = this.session
+    const running = previous.processes.list().filter((entry) => isActive(entry.status))
+    if (running.length > 0) {
+      const confirmed = await this.askConfirm(
+        `Reload the config and stop ${running.length} running process(es)?`,
+        `${running.map((entry) => entry.name).join(", ")} will be stopped; start them again afterwards.`,
+      )
+      if (!confirmed) return
+    }
+
+    this.stopSessionBackground(previous)
+    previous.verifyAbort?.abort()
+    await previous.processes.stopAll()
+    previous.wiring.dispose()
+
+    try {
+      const next = await this.createSession(previous.rootDir)
+      this.sessions.set(next.rootDir, next)
+      this.wireSession(next)
+      this.activateSession(next)
+      this.reportConfigIssues()
+      this.pushNotification(
+        "success",
+        `Reloaded ${next.project.configPath ? basename(next.project.configPath) : "config"}`,
+      )
+    } catch (error) {
+      this.pushNotification("error", `Could not reload the config: ${errorMessage(error)}`)
+    }
+  }
+
   // ---------------------------------------------------------------------
   // Dependencies
   // ---------------------------------------------------------------------
@@ -1404,6 +1896,7 @@ export class App {
     this.footer.setStatus("Shutting down…")
 
     this.stopBackground()
+    for (const session of this.sessions.values()) session.verifyAbort?.abort()
 
     // Every open project, not just the visible one.
     await Promise.all(
@@ -1461,3 +1954,17 @@ export class App {
     return this.logs
   }
 }
+
+/** The header and System view still read `project.tools`; derive it from environment detection. */
+function toolVersionsFrom(snapshot: EnvironmentSnapshot, packageManager: string): ToolVersions {
+  const version = (id: string) => {
+    const tool = snapshot.tools.find((entry) => entry.id === id)
+    return tool?.installed ? (tool.version ?? "installed") : null
+  }
+  return { git: version("git"), docker: version("docker"), packageManager: version(packageManager) }
+}
+
+function expandHome(path: string): string {
+  const home = process.env.HOME
+  return home && (path === "~" || path.startsWith("~/")) ? `${home}${path.slice(1)}` : path
+}