fix(swarm): write runtime.json on stop + sync roster model on start (#238)

Closes #235 — workers stuck after stop because runtime.json was never
updated. `POST /api/swarm-tmux-stop` killed the tmux session but left
`lifecycle.state` / `phase` / `currentTask` at whatever the last
in-process update wrote. The Swarm UI rendered the worker as 'stuck':
no tmux session, but lifecycle still says running/blocked.

Adds `patchSwarmRuntimeFile` in swarm-foundation, atomic-write into
`runtime.json` so unrelated fields survive. Stop handler now patches:

  state: idle, phase: stopped, currentTask: null, blockedReason: null,
  checkpointStatus: none, lastDispatchResult: 'Stopped via UI',
  lastOutputAt: now

Best-effort: a runtime-write failure does NOT fail the kill request
(the tmux session is already gone — caller deserves to know that).

Closes #236 — roster `model:` field was display-only. The wrapper at
`~/.local/bin/swarm<N>` invokes `hermes chat --continue` with no
`--model` flag, so the per-profile config.yaml wins. Profiles all
defaulted to `gpt-5.5`, so the roster value never made it to the model.

Adds:

- `swarm-model-resolver.ts` — maps roster display labels (e.g. 'Opus 4.7',
  'PC1 Coder (97 TPS)', 'GPT-5.5', 'minimax M2.7') to canonical
  provider+model id pairs. Tolerant: unknown labels return null so the
  worker is left alone instead of getting wedged.

- `swarm-profile-config.ts` — atomic YAML patch for
  `profiles/<id>/config.yaml` that updates only `model.provider` and
  `model.default`, preserving sibling fields (toolsets, providers,
  agent settings).

- swarm-tmux-start now resolves the roster model and syncs the profile
  config before (re)attaching the tmux session. Returns a `modelSync`
  block in the response so the UI can surface 'now using …' or quietly
  ignore unknown labels.

Tests:
- 10 new tests for `patchSwarmRuntimeFile` (4) + resolver (7) + config sync (7)
- All 24 pass; pre-existing failing tests on main are unrelated and untouched.

Co-authored-by: Aurora release bot <release@outsourc-e.com>

Author: outsourc-e

src/routes/api/swarm-tmux-start.ts

@@ -5,6 +5,9 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { isAuthenticated } from '../../server/auth-middleware'
+import { rosterByWorkerId } from '../../server/swarm-roster'
+import { resolveSwarmModelLabel } from '../../server/swarm-model-resolver'
+import { syncSwarmProfileModel } from '../../server/swarm-profile-config'
 
 // Inlined to avoid SSR module-resolution races against freshly-written
 // helpers; mirrors `src/server/claude-paths.ts` getProfilesDir().
@@ -161,6 +164,39 @@ export const Route = createFileRoute('/api/swarm-tmux-start')({
           )
         }
 
+        // Sync the worker's profile config.yaml model section to the
+        // roster's `model:` label before we (re)attach tmux. Hermes Agent
+        // reads config.yaml on every invocation, and the wrapper does not
+        // pass `--model`, so this is the only way the roster value is
+        // honored. Best-effort: unrecognised labels (typos, custom
+        // models) are left as-is so a worker never gets wedged. See #236.
+        let modelSync: {
+          attempted: boolean
+          changed: boolean
+          target?: string
+          previous?: string
+          error?: string
+        } = { attempted: false, changed: false }
+        try {
+          const roster = rosterByWorkerId([workerId]).get(workerId)
+          const resolved = resolveSwarmModelLabel(roster?.model ?? null)
+          if (resolved) {
+            modelSync.attempted = true
+            const result = syncSwarmProfileModel(profilePath, resolved)
+            if (result.ok) {
+              modelSync.changed = result.changed
+              modelSync.target = `${resolved.provider}/${resolved.default}`
+              if (result.previous) {
+                modelSync.previous = `${result.previous.provider}/${result.previous.default}`
+              }
+            } else {
+              modelSync.error = result.error
+            }
+          }
+        } catch (err) {
+          modelSync.error = err instanceof Error ? err.message : String(err)
+        }
+
         const sessionName = `swarm-${workerId}`
         const alreadyRunning = await tmuxHasSession(tmuxBin, sessionName)
         if (alreadyRunning) {
@@ -170,6 +206,7 @@ export const Route = createFileRoute('/api/swarm-tmux-start')({
             alreadyRunning: true,
             started: false,
             tmuxBin,
+            modelSync,
           })
         }
 
@@ -194,6 +231,7 @@ export const Route = createFileRoute('/api/swarm-tmux-start')({
           started: true,
           tmuxBin,
           cwd,
+          modelSync,
         })
       },
     },

src/routes/api/swarm-tmux-stop.ts

@@ -5,7 +5,10 @@ import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { isAuthenticated } from '../../server/auth-middleware'
-// (no profile path needed for stop; only the session name)
+import {
+  getSwarmProfilePath,
+  patchSwarmRuntimeFile,
+} from '../../server/swarm-foundation'
 
 /**
  * POST /api/swarm-tmux-stop
@@ -119,7 +122,32 @@ export const Route = createFileRoute('/api/swarm-tmux-stop')({
           )
         }
 
-        return json({ workerId, sessionName, wasRunning: true, killed: true })
+        // Reconcile runtime.json so the Swarm UI doesn't show a 'stuck'
+        // worker (tmux gone, lifecycle still says running/blocked). Best
+        // effort — the kill already succeeded, so a write failure here
+        // should NOT fail the stop request. Reported in #235.
+        const profilePath = getSwarmProfilePath(workerId)
+        const stoppedAt = Date.now()
+        const patchResult = patchSwarmRuntimeFile(profilePath, workerId, {
+          state: 'idle',
+          phase: 'stopped',
+          currentTask: null,
+          activeTool: null,
+          needsHuman: false,
+          blockedReason: null,
+          checkpointStatus: 'none',
+          lastDispatchResult: 'Stopped via UI',
+          lastOutputAt: stoppedAt,
+        })
+
+        return json({
+          workerId,
+          sessionName,
+          wasRunning: true,
+          killed: true,
+          runtimePatched: patchResult.ok,
+          runtimePatchError: patchResult.ok ? undefined : patchResult.error,
+        })
       },
     },
   },

src/server/swarm-foundation.test.ts

@@ -155,3 +155,97 @@ describe('parseSwarmPluginManifest', () => {
     }
   })
 })
+
+import { patchSwarmRuntimeFile, readSwarmRuntimeFile } from './swarm-foundation'
+
+describe('patchSwarmRuntimeFile', () => {
+  it('returns ok=false when the profile path does not exist', () => {
+    const tempDir = path.join(os.tmpdir(), `patch-runtime-missing-${Date.now()}`)
+    const result = patchSwarmRuntimeFile(tempDir, 'swarm9', { state: 'idle' })
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('profile path missing')
+  })
+
+  it('writes a fresh runtime.json when none exists', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'patch-runtime-fresh-'))
+    try {
+      const result = patchSwarmRuntimeFile(tempDir, 'swarm9', {
+        state: 'idle',
+        phase: 'stopped',
+        currentTask: null,
+      })
+      expect(result.ok).toBe(true)
+      const { source, runtime } = readSwarmRuntimeFile(tempDir, 'swarm9', {
+        workspaceRoot: tempDir,
+      })
+      expect(source).toBe('runtime.json')
+      expect(runtime.state).toBe('idle')
+      expect(runtime.phase).toBe('stopped')
+      expect(runtime.currentTask).toBeNull()
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
+  it('preserves unrelated fields and only overwrites the patched ones', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'patch-runtime-merge-'))
+    try {
+      const runtimePath = path.join(tempDir, 'runtime.json')
+      fs.writeFileSync(
+        runtimePath,
+        JSON.stringify({
+          workerId: 'swarm9',
+          state: 'blocked',
+          phase: 'blocked',
+          currentTask: 'old task',
+          blockedReason: 'legacy reason',
+          assignedTaskCount: 7,
+          customField: 'kept',
+        }) + '\n',
+        'utf8',
+      )
+
+      const result = patchSwarmRuntimeFile(tempDir, 'swarm9', {
+        state: 'idle',
+        phase: 'stopped',
+        currentTask: null,
+        blockedReason: null,
+      })
+      expect(result.ok).toBe(true)
+
+      const raw = JSON.parse(fs.readFileSync(runtimePath, 'utf8')) as Record<
+        string,
+        unknown
+      >
+      expect(raw.state).toBe('idle')
+      expect(raw.phase).toBe('stopped')
+      expect(raw.currentTask).toBeNull()
+      expect(raw.blockedReason).toBeNull()
+      expect(raw.assignedTaskCount).toBe(7)
+      expect(raw.customField).toBe('kept')
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
+  it('rewrites cleanly even when existing runtime.json is corrupt', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'patch-runtime-corrupt-'))
+    try {
+      const runtimePath = path.join(tempDir, 'runtime.json')
+      fs.writeFileSync(runtimePath, '{ this is not json', 'utf8')
+
+      const result = patchSwarmRuntimeFile(tempDir, 'swarm9', {
+        state: 'idle',
+        phase: 'stopped',
+      })
+      expect(result.ok).toBe(true)
+      const { runtime } = readSwarmRuntimeFile(tempDir, 'swarm9', {
+        workspaceRoot: tempDir,
+      })
+      expect(runtime.state).toBe('idle')
+      expect(runtime.phase).toBe('stopped')
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+})

src/server/swarm-foundation.ts

@@ -394,6 +394,61 @@ export function readSwarmRuntimeFile(
   }
 }
 
+/**
+ * Patch a worker's `runtime.json` in place.
+ *
+ * Reads the existing file (if any) so unspecified fields are preserved,
+ * applies the supplied partial update, and writes atomically. The runtime
+ * file is the source of truth for `lifecycle.state` / `phase` / `currentTask`
+ * etc that the Swarm UI renders, so it MUST be kept in sync with operations
+ * that change worker state out-of-band (for example: tmux kill from
+ * `swarm-tmux-stop`).
+ *
+ * Best-effort: if the profile directory is missing, do nothing. If the
+ * write fails, log the error but do not throw — callers are usually
+ * lifecycle hooks that should not fail because state.json bookkeeping
+ * could not persist.
+ */
+export function patchSwarmRuntimeFile(
+  profilePath: string,
+  workerId: string,
+  patch: Partial<SwarmRuntime>,
+): { ok: boolean; error?: string } {
+  if (!fs.existsSync(profilePath)) {
+    return { ok: false, error: `profile path missing: ${profilePath}` }
+  }
+  const runtimePath = path.join(profilePath, 'runtime.json')
+  let existing: Record<string, unknown> = {}
+  if (fs.existsSync(runtimePath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(runtimePath, 'utf8')) as Record<
+        string,
+        unknown
+      >
+    } catch {
+      // Corrupt JSON: fall through and rewrite from scratch using the patch.
+      existing = {}
+    }
+  }
+  const merged = { ...existing, ...patch, workerId }
+  const tmpPath = `${runtimePath}.tmp-${process.pid}-${Date.now()}`
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + '\n', 'utf8')
+    fs.renameSync(tmpPath, runtimePath)
+    return { ok: true }
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath)
+    } catch {
+      // tmp may not exist if the write failed before creation
+    }
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}
+
 export function listSwarmWorkerIds(options?: { swarmOnly?: boolean }): Array<string> {
   const profilesDir = getProfilesDir()
   if (!fs.existsSync(profilesDir)) return []

src/server/swarm-model-resolver.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+import { resolveSwarmModelLabel } from './swarm-model-resolver'
+
+describe('resolveSwarmModelLabel', () => {
+  it('returns null for empty / blank / sentinel labels', () => {
+    expect(resolveSwarmModelLabel(null)).toBeNull()
+    expect(resolveSwarmModelLabel('')).toBeNull()
+    expect(resolveSwarmModelLabel('   ')).toBeNull()
+    expect(resolveSwarmModelLabel('Worker')).toBeNull()
+  })
+
+  it('resolves Anthropic Opus labels', () => {
+    expect(resolveSwarmModelLabel('Opus 4.7')).toEqual({
+      provider: 'anthropic-oauth',
+      default: 'claude-opus-4-7',
+    })
+    expect(resolveSwarmModelLabel('Claude Opus 4.6')).toEqual({
+      provider: 'anthropic-oauth',
+      default: 'claude-opus-4-6',
+    })
+    expect(resolveSwarmModelLabel('opus 4.5')).toEqual({
+      provider: 'anthropic-oauth',
+      default: 'claude-opus-4-5',
+    })
+  })
+
+  it('resolves Claude Sonnet labels', () => {
+    expect(resolveSwarmModelLabel('Sonnet 4.6')).toEqual({
+      provider: 'anthropic-oauth',
+      default: 'claude-sonnet-4-6',
+    })
+    expect(resolveSwarmModelLabel('Sonnet 4.5')).toEqual({
+      provider: 'anthropic',
+      default: 'claude-sonnet-4-5',
+    })
+  })
+
+  it('resolves OpenAI Codex labels', () => {
+    expect(resolveSwarmModelLabel('GPT-5.5')).toEqual({
+      provider: 'openai-codex',
+      default: 'gpt-5.5',
+    })
+    expect(resolveSwarmModelLabel('GPT 5.4')).toEqual({
+      provider: 'openai-codex',
+      default: 'gpt-5.4',
+    })
+    expect(resolveSwarmModelLabel('Codex (GPT-5.5)')).toEqual({
+      provider: 'openai-codex',
+      default: 'gpt-5.5',
+    })
+  })
+
+  it('resolves PC1 local labels regardless of TPS qualifier', () => {
+    expect(resolveSwarmModelLabel('PC1 Coder (97 TPS)')).toEqual({
+      provider: 'ollama-pc1',
+      default: 'qwen3-coder-30b-fixed:latest',
+    })
+    expect(resolveSwarmModelLabel('PC1 Planner (175 TPS)')).toEqual({
+      provider: 'ollama-pc1',
+      default: 'pc1-planner:latest',
+    })
+    expect(resolveSwarmModelLabel('PC1 Critic')).toEqual({
+      provider: 'ollama-pc1',
+      default: 'pc1-critic:latest',
+    })
+  })
+
+  it('passes through fully-qualified provider/model ids', () => {
+    expect(resolveSwarmModelLabel('openai-codex/gpt-5.5')).toEqual({
+      provider: 'openai-codex',
+      default: 'gpt-5.5',
+    })
+    expect(resolveSwarmModelLabel('anthropic-oauth/claude-opus-4-7')).toEqual({
+      provider: 'anthropic-oauth',
+      default: 'claude-opus-4-7',
+    })
+  })
+
+  it('returns null for unknown labels (so the worker is left alone)', () => {
+    expect(resolveSwarmModelLabel('Unknown 9000')).toBeNull()
+    expect(resolveSwarmModelLabel('typo opus')).toBeNull()
+  })
+})