@sergeychuvayev/claude-fleet 0.1.0 → 0.3.0

package/README.md

@@ -192,6 +192,34 @@ conversation on every question.
 
 </details>
 
+### An initiative is a team behind one conversation
+
+Some work is too big for one agent and too small to project-manage by hand. Launch it with a
+**team** instead of alone and you get an *initiative*: a manager that plans and delegates, a
+developer that implements, and a QA that independently verifies, all behind a single
+conversation.
+
+You talk to the manager and only to the manager. That is not a rule in a prompt: the manager
+holds the main thread, and the rest of the team is reachable only through the Agent tool, so
+they have no channel to you at all. Their work arrives as delegation blocks in the
+conversation, each showing the role, the mandate it was given, and the report it sent back.
+
+The manager has no edit tools. Its only way to ship is to delegate, which is the entire point
+of having a team rather than an agent with a long prompt. QA has no edit tools either: it
+reproduces the problem, runs the project's own gates, and returns PASS or FAIL with evidence,
+so a developer's account of its own work is never the last word.
+
+An initiative works in a git worktree of its own, branched from wherever the project is
+checked out, so a team editing files cannot collide with your own editing or with another
+initiative. It finishes by opening a pull request. Pushing stops for your approval like any
+other publishing command, so nothing leaves the machine without you.
+
+Closing an initiative forgets Fleet's record of the conversation and leaves the worktree and
+its branch alone. Deleting code is never the same click as tidying a list.
+
+Teams cost roughly an order of magnitude more tokens than a single agent, and only earn it
+when the work genuinely splits. For a one-line fix, launch an agent.
+
 ### Approvals that stay out of the way
 
 Every agent runs in one of three modes, chosen at launch and changeable from the
@@ -309,6 +337,8 @@ for the app itself.
 | [`fleet.js`](fleet.js) | Cached, read-only collection of external Claude sessions |
 | [`archive.js`](archive.js) | Which sessions are put away, the age rule, and its store |
 | [`managed.js`](managed.js) | SDK runs, approvals, tool blocks, persistence, cancellation |
+| [`teams.js`](teams.js) | The roles an initiative runs, and how they compile into SDK options |
+| [`worktree.js`](worktree.js) | The git worktree an initiative works in, and its branch |
 | [`search.js`](search.js) | Transcript index, BM25 ranking, and the answering turn |
 | [`permissions.js`](permissions.js) | The three approval modes and the command list that still stops |
 | [`theme.js`](theme.js) | Reads the local Warp palette and renders it as CSS variables |

package/bin/claude-fleet.js

@@ -13,18 +13,25 @@ const pkg = require(path.join(ROOT, 'package.json'))
 const HELP = `
   Claude Fleet v${pkg.version} — a local control room for Claude Code sessions
 
-  claude-fleet                 start Fleet and open the dashboard
-  claude-fleet start           start it without opening a browser
+  claude-fleet                 start Fleet and open it as an app window
+  claude-fleet start           start it without opening anything
+  claude-fleet --browser       open a normal browser tab instead of an app window
   claude-fleet install-app     put a "Claude Fleet" app in ~/Applications (macOS)
   claude-fleet update          install the latest published version
   claude-fleet --version       print the version
   claude-fleet --help          this
 
+  The app window is a Chromium window with no tab strip and no address bar. If Fleet
+  is already running, claude-fleet puts that server on screen rather than starting a
+  second one.
+
   Environment
     PORT                       port to listen on (default 7777, next free one if taken)
     CLAUDE_FLEET_HOME          where Fleet keeps its own state (default ~/.claude-fleet)
     CLAUDE_FLEET_DIR           the Claude directory to read (default ~/.claude)
     CLAUDE_FLEET_EXECUTABLE    the claude binary to run; "bundled" uses the SDK's own
+    CLAUDE_FLEET_BROWSER       the Chromium to open the app window with
+    CLAUDE_FLEET_APP_PROFILE   where that window keeps its profile
 `
 
 // A PATH walk rather than `command -v`, because this has to work without a shell

package/fleet.js

@@ -59,7 +59,7 @@ function toolTarget(name, input) {
   if (!input || typeof input !== 'object') return null
   const first = value => (typeof value === 'string' ? value.split('\n')[0].trim().slice(0, 120) : null)
   if (name === 'Bash' || name === 'BashOutput') return first(input.description) || first(input.command)
-  if (name === 'Task') return first(input.description)
+  if (name === 'Task' || name === 'Agent') return first(input.description)
   if (name === 'WebSearch') return first(input.query)
   if (name === 'WebFetch') return first(input.url)
   if (name === 'Grep' || name === 'Glob') return first(input.pattern)

package/managed.js

@@ -7,6 +7,8 @@ const { EventEmitter } = require('node:events')
 const { gitBranch, turnSummary, toolTarget } = require('./fleet')
 const { askReason, normaliseMode, MODES, DEFAULT_MODE } = require('./permissions')
 const { stateDir } = require('./paths')
+const { getTeam, compile } = require('./teams')
+const worktrees = require('./worktree')
 
 const ACTIVE = new Set(['starting', 'running', 'approval', 'stopping'])
 // Used until a live run reports the runtime's own list, which replaces it.
@@ -78,22 +80,45 @@ class ManagedSessions extends EventEmitter {
       }
     } catch (error) { this.releaseLock(); throw new Error(`Cannot read Fleet session store: ${error.message}`) }
   }
+  // The lock used to hold a bare PID. It now holds {pid, port} so that a second
+  // `claude-fleet` can put the running dashboard on screen instead of only naming the
+  // process that beat it to the lock. A bare PID is still read: the file outlives an
+  // upgrade, and a stale one must not read as corrupt.
+  readLock() {
+    const raw = fs.readFileSync(this.lock, 'utf8').trim()
+    try {
+      const parsed = JSON.parse(raw)
+      if (Number.isInteger(parsed?.pid) && parsed.pid > 0) return { pid: parsed.pid, port: Number(parsed.port) || null }
+    } catch {}
+    const pid = Number(raw)
+    return Number.isInteger(pid) && pid > 0 ? { pid, port: null } : null
+  }
   acquireLock() {
     for (let attempt = 0; attempt < 2; attempt++) {
-      try { fs.writeFileSync(this.lock, String(process.pid), { flag: 'wx', mode: 0o600 }); return }
+      try { fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 }); return }
       catch (error) {
         if (error.code !== 'EEXIST') throw error
-        const pid = Number(fs.readFileSync(this.lock, 'utf8'))
-        if (!Number.isInteger(pid) || pid <= 0) throw new Error(`Invalid Fleet lock file; inspect ${this.lock}.`)
-        try { process.kill(pid, 0) }
+        const held = this.readLock()
+        if (!held) throw new Error(`Invalid Fleet lock file; inspect ${this.lock}.`)
+        try { process.kill(held.pid, 0) }
         catch (e) { if (e.code === 'ESRCH') { fs.unlinkSync(this.lock); continue } }
-        throw new Error(`Fleet controls are already running (PID ${pid}). Open that server instead.`)
+        // Carries the holder so main() can open it rather than print and exit 1. Being
+        // already running is the normal case, not a failure.
+        const conflict = new Error(`Fleet controls are already running (PID ${held.pid})`)
+        conflict.code = 'FLEET_ALREADY_RUNNING'
+        conflict.holder = held
+        throw conflict
       }
     }
     throw new Error('Cannot acquire Fleet session lock')
   }
+  // Called once the server knows which port it actually got, which is not always the
+  // one it asked for: the listen path walks upwards past anything already bound.
+  recordPort(port) {
+    try { fs.writeFileSync(this.lock, JSON.stringify({ pid: process.pid, port }), { mode: 0o600 }) } catch {}
+  }
   releaseLock() {
-    try { if (fs.readFileSync(this.lock, 'utf8') === String(process.pid)) fs.unlinkSync(this.lock) } catch {}
+    try { if (this.readLock()?.pid === process.pid) fs.unlinkSync(this.lock) } catch {}
   }
   save() {
     clearTimeout(this.saveTimer); this.saveTimer = null
@@ -123,6 +148,8 @@ class ManagedSessions extends EventEmitter {
       permissionMode:'default', approvalMode:s.approvalMode || DEFAULT_MODE, selectedModel:s.selectedModel || '', messages:s.messages.filter(m=>m.role!=='tool').length, links:linksFromMessages(s.messages), approvals:s.approvals.length,
       turn:turnSummary(managedEvents(s.messages), { working: ACTIVE.has(s.status) && s.status !== 'approval' }),
       error:s.error, currentTool:s.currentTool, resumeCmd:s.sessionId ? `claude --resume ${s.sessionId}` : null,
+      kind:s.kind || 'agent', teamId:s.teamId || null, teamName:s.teamName || null,
+      worktreeBranch:s.worktree?.branch || null,
     }))
   }
   create(body) {
@@ -147,10 +174,17 @@ class ManagedSessions extends EventEmitter {
       resume = source.sessionId
     }
     this.checkCapacity()
-    const s = {id:randomUUID(),sessionId:resume,name,cwd,createRequestId:rid,createdAt:Date.now(),updatedAt:Date.now(),status:'idle',approvalMode:normaliseMode(body.approvalMode),selectedModel:modelChoice(body.model),messages:[],approvals:[],model:null,contextTokens:null,error:null,currentTool:null,requestIds:[]}
+    // A team turns this conversation into an initiative: the manager takes the main thread
+    // and the work happens on a branch of its own rather than in the operator's checkout.
+    const team = body.teamId ? getTeam(text(body.teamId,'Team',60)) : null
+    if (body.teamId && !team) fail('That team does not exist.')
+    if (team && resume) fail('A resumed conversation cannot be given a team.',409)
+    const id = randomUUID()
+    const worktree = team ? worktrees.create({cwd,id,name}) : null
+    const s = {id,sessionId:resume,name,cwd:worktree ? worktree.path : cwd,createRequestId:rid,createdAt:Date.now(),updatedAt:Date.now(),status:'idle',approvalMode:normaliseMode(body.approvalMode),selectedModel:modelChoice(body.model),messages:[],approvals:[],model:null,contextTokens:null,error:null,currentTool:null,requestIds:[],kind:team ? 'initiative' : 'agent',teamId:team?.id || null,teamName:team?.name || null,worktree}
     this.sessions.set(s.id,s)
     try { this.send(s.id,{message:prompt,images:body.images,requestId:rid}) }
-    catch (error) { this.sessions.delete(s.id); throw error }
+    catch (error) { this.sessions.delete(s.id); if (worktree) worktrees.remove(worktree); throw error }
     return s
   }
   checkCapacity() {
@@ -241,6 +275,11 @@ class ManagedSessions extends EventEmitter {
         ...(s.sessionId ? {resume:s.sessionId} : {}),
       }
       if (s.selectedModel) options.model = s.selectedModel
+      // `agent` puts the manager on the main thread, so the operator's messages reach it and
+      // nobody else; `agents` is where the Agent tool resolves the rest of the team from.
+      // Both compose with the claude_code preset above, which keeps the built-in tools.
+      const team = getTeam(s.teamId)
+      if (team) Object.assign(options, compile(team))
       if (process.env.CLAUDE_FLEET_EXECUTABLE) options.pathToClaudeCodeExecutable = process.env.CLAUDE_FLEET_EXECUTABLE
       run.query = await this.queryFactory({prompt,options})
       if (run.stopping) { run.query.close(); return }
@@ -348,7 +387,7 @@ class ManagedSessions extends EventEmitter {
     if (!reason) return Promise.resolve({behavior:'allow',updatedInput:input})
     return new Promise(resolve => {
       const id=randomUUID()
-      const approval={id,tool,input,at:Date.now(),reason,description:context.title || context.decisionReason || null}
+      const approval={id,tool,input,at:Date.now(),reason,description:context.title || context.decisionReason || null,role:roleAsking(s,context)}
       let settled=false
       const finish=result=>{
         if(settled)return
@@ -401,7 +440,11 @@ class ManagedSessions extends EventEmitter {
     this.sessions.delete(id)
     try { this.save() } catch (error) { this.emit('storage-error',error) }
     this.emit('change',id)
-    return {id, sessionId:s.sessionId}
+    // An initiative's worktree is left on disk on purpose. Forgetting a conversation is a
+    // change to Fleet's records; deleting a branch with uncommitted work on it is a change
+    // to the operator's code, and the two should never happen with the same click. The path
+    // comes back so the caller can say where the work went.
+    return {id, sessionId:s.sessionId, worktree:s.worktree?.path || null, branch:s.worktree?.branch || null}
   }
   async close() {
     this.closed=true
@@ -412,6 +455,21 @@ class ManagedSessions extends EventEmitter {
   }
 }
 // An empty choice means "leave it to the project", which is the SDK's own default.
+// Who is asking for this approval. Inside an initiative, "the session wants to run rm" is
+// not good enough: the operator needs to know which role wants it. The SDK marks a
+// subagent's request with an agentID but not with the role name, so the name is recovered
+// from the delegation that is in flight. With two delegations running at once that is
+// ambiguous, and an honest null beats a confident guess at the wrong role.
+function roleAsking(s,context) {
+  const team = getTeam(s.teamId)
+  if (!team) return null
+  // No agentID means the request came from the main thread, which is the manager by
+  // definition. The role name comes from the team rather than a literal, because a future
+  // team is free to call that role something else.
+  if (!context.agentID) return team.manager
+  const running = s.messages.filter(m => m.role==='tool' && (m.tool==='Agent' || m.tool==='Task') && m.status==='running')
+  return running.length === 1 ? (running[0].input?.subagent_type || null) : null
+}
 function modelChoice(value) {
   if (value === undefined || value === null || value === '') return ''
   if (typeof value !== 'string' || !/^[\w.:-]{1,80}$/.test(value)) fail('That model name is not valid.')

package/open.js

@@ -0,0 +1,94 @@
+'use strict'
+// How the dashboard gets on screen. Fleet is a desktop tool in everything but
+// packaging, so the default is a Chromium app window — no tab strip, no address
+// bar, its own Dock entry — rather than a tab that goes missing among forty others.
+//
+// The profile directory is shared with the bundle `install-app` builds, on purpose.
+// Chrome keys localStorage and window state to the profile, so a terminal launch and
+// a Spotlight launch have to point at the same one or they become two windows that
+// disagree about which sessions you had open.
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+// Tried in order. Chrome first because it is the likeliest to be installed and its
+// `--app` behaviour has been stable for years.
+const MAC_BROWSERS = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+]
+const UNIX_BROWSERS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge', 'brave-browser']
+const WIN_BROWSERS = [
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+]
+
+const executable = file => { try { fs.accessSync(file, fs.constants.X_OK); return true } catch { return false } }
+
+// Absolute paths are checked as given; bare names are walked down PATH, because an
+// app launched from Finder or a .desktop file has no shell to resolve them for it.
+function locate(candidate, { env, exists }) {
+  if (candidate.includes(path.sep) || candidate.includes('/')) return exists(candidate) ? candidate : null
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue
+    const full = path.join(dir, candidate)
+    if (exists(full)) return full
+  }
+  return null
+}
+
+// Kept in step with build/make-app.sh. If one of them moves, both move.
+function profileDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.CLAUDE_FLEET_APP_PROFILE) return path.resolve(env.CLAUDE_FLEET_APP_PROFILE)
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'ClaudeFleetApp')
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ClaudeFleetApp')
+  return path.join(env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'ClaudeFleetApp')
+}
+
+// CLAUDE_FLEET_BROWSER wins outright, so an operator on a Chromium this does not know
+// about is never stuck with a plain tab.
+function findBrowser({ env = process.env, platform = process.platform, exists = executable } = {}) {
+  const known = platform === 'darwin' ? MAC_BROWSERS : platform === 'win32' ? WIN_BROWSERS : UNIX_BROWSERS
+  const candidates = env.CLAUDE_FLEET_BROWSER ? [env.CLAUDE_FLEET_BROWSER, ...known] : known
+  for (const candidate of candidates) {
+    const found = locate(candidate, { env, exists })
+    if (found) return found
+  }
+  return null
+}
+
+// The plain-tab route, for when no Chromium is installed or the operator asked for it.
+function browserCommand(url, platform) {
+  if (platform === 'darwin') return ['open', [url]]
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]]
+  return ['xdg-open', [url]]
+}
+
+// Returns what it did, so the caller can say so and the tests can assert on it without
+// launching anything: {mode:'app'|'browser', command, args}.
+function openDashboard(url, {
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  exists = executable,
+  spawn = require('node:child_process').spawn,
+  app = true,
+} = {}) {
+  const browser = app ? findBrowser({ env, platform, exists }) : null
+  const [command, args] = browser
+    // --app is what drops the tab strip and the address bar. The separate profile also
+    // keeps Fleet out of the way of whatever the operator has open for actual browsing.
+    ? [browser, [`--app=${url}`, `--user-data-dir=${profileDir({ env, platform, home })}`]]
+    : browserCommand(url, platform)
+  // Detached: the window has to outlive `claude-fleet` when the server is already up
+  // and this process is about to exit.
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.on('error', () => {})
+  child.unref()
+  return { mode: browser ? 'app' : 'browser', command, args }
+}
+
+module.exports = { openDashboard, findBrowser, profileDir, MAC_BROWSERS, UNIX_BROWSERS, WIN_BROWSERS }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sergeychuvayev/claude-fleet",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A local control room for Claude Code sessions",
   "keywords": [
     "claude",
@@ -29,12 +29,15 @@
     "catalog.js",
     "fleet.js",
     "managed.js",
+    "open.js",
     "paths.js",
     "permissions.js",
     "search.js",
     "server.js",
+    "teams.js",
     "theme.js",
-    "update.js"
+    "update.js",
+    "worktree.js"
   ],
   "scripts": {
     "start": "node bin/claude-fleet.js start",

package/public/app.js

@@ -99,7 +99,7 @@ function render() {
   renderArchiveBar(live.filter(s => s.state === 'dead'), archived.length)
   update('session-list', shown.length ? shown.map(s => {
     const p = percent(s)
-    return `<button class="session" data-session="${esc(key(s))}" aria-pressed="${selected === key(s)}" aria-controls="detail" title="${hasUnseen(s) ? 'New output since you last opened this' : ''}"><span><span class="session-top">${hasUnseen(s) ? '<span class="unseen" aria-label="New output"></span>' : ''}${status(s)}<span class="session-name">${esc((s.managed ? 'FLEET · ' : '') + (s.name || s.shortId || 'Unnamed session'))}</span>${spawnCounts.get(s.pid) ? `<span class="spawn-badge" title="Running ${spawnCounts.get(s.pid)} background session(s)">⑂ ${spawnCounts.get(s.pid)}</span>` : ''}${s.background ? `<span class="spawn-owner" title="Started by ${esc(s.spawnedByName || 'a program')}, not from a terminal">via ${esc(s.spawnedByName || 'a program')}</span>` : ''}${s.archived ? '<span class="archived-tag" title="Archived. Hidden from your fleet, still on disk and still resumable.">archived</span>' : ''}</span><span class="session-title">${esc(s.title || s.lastPrompt || 'Untitled session')}</span><span class="session-meta"><span>${esc(s.cwd?.split('/').filter(Boolean).pop() || 'No project')}</span><span class="branch">⑂ ${esc(s.branch || 'No branch')}</span>${s.links?.length ? `<span>↗ ${s.links.length}</span>` : ''}</span>${turnRow(s)}</span><span class="session-context ${heat(p)}">${p === null ? '—' : Math.round(p)+'%'}<span class="mini-bar"><i class="${heat(p)}" style="width:${p || 0}%"></i></span><small>${age(s.lastActivity)} ago</small></span></button>`
+    return `<button class="session" data-session="${esc(key(s))}" aria-pressed="${selected === key(s)}" aria-controls="detail" title="${hasUnseen(s) ? 'New output since you last opened this' : ''}"><span><span class="session-top">${hasUnseen(s) ? '<span class="unseen" aria-label="New output"></span>' : ''}${status(s)}<span class="session-name">${esc((s.managed ? 'FLEET · ' : '') + (s.name || s.shortId || 'Unnamed session'))}</span>${spawnCounts.get(s.pid) ? `<span class="spawn-badge" title="Running ${spawnCounts.get(s.pid)} background session(s)">⑂ ${spawnCounts.get(s.pid)}</span>` : ''}${s.background ? `<span class="spawn-owner" title="Started by ${esc(s.spawnedByName || 'a program')}, not from a terminal">via ${esc(s.spawnedByName || 'a program')}</span>` : ''}${s.archived ? '<span class="archived-tag" title="Archived. Hidden from your fleet, still on disk and still resumable.">archived</span>' : ''}</span>${s.kind === 'initiative' ? `<span class="initiative-tag">Initiative · ${esc(s.teamName || s.teamId || 'Team')}</span>` : ''}<span class="session-title">${esc(s.title || s.lastPrompt || 'Untitled session')}</span><span class="session-meta"><span>${esc(s.cwd?.split('/').filter(Boolean).pop() || 'No project')}</span><span class="branch">⑂ ${esc(s.branch || 'No branch')}</span>${s.links?.length ? `<span>↗ ${s.links.length}</span>` : ''}</span>${turnRow(s)}</span><span class="session-context ${heat(p)}">${p === null ? '—' : Math.round(p)+'%'}<span class="mini-bar"><i class="${heat(p)}" style="width:${p || 0}%"></i></span><small>${age(s.lastActivity)} ago</small></span></button>`
   }).join('') : `<div class="empty">${filter === 'background' ? 'No background sessions right now.' : total ? 'No sessions match your filters.<br>Try another search or select All sessions.' : 'Your fleet is quiet.<br>Start a Claude Code session and it will appear here automatically.'}</div>`)
   const current = shown.find(s => key(s) === selected)
   if (current) markSeen(key(current), current.lastActivity)

package/public/blocks.js

@@ -7,7 +7,7 @@
 const LIBS = () => window.FleetLibs || null
 const ICONS = {
   Bash: '⚡', BashOutput: '⚡', Read: '▤', Write: '✎', Edit: '✎', NotebookEdit: '✎',
-  Grep: '⌕', Glob: '⌕', WebSearch: '⌕', WebFetch: '↓', Task: '✳', Skill: '◆',
+  Grep: '⌕', Glob: '⌕', WebSearch: '⌕', WebFetch: '↓', Task: '✳', Agent: '✳', Skill: '◆',
   TodoWrite: '☑', AskUserQuestion: '?', ExitPlanMode: '▸',
 }
 const EXTENSIONS = {
@@ -18,9 +18,13 @@ const EXTENSIONS = {
 }
 // Mirrors toolTarget() in managed.js: the input key already shown in the block header.
 const TARGET_KEYS = {
-  Bash: 'command', BashOutput: 'bash_id', Task: 'description', WebSearch: 'query',
+  Bash: 'command', BashOutput: 'bash_id', Task: 'description', Agent: 'description', WebSearch: 'query',
   WebFetch: 'url', Grep: 'pattern', Glob: 'pattern', Skill: 'skill',
 }
+// The runtime names this tool `Agent`; `Task` is the older name for the same call and still
+// appears in transcripts recorded before the rename. Both carry {subagent_type, description,
+// prompt}, so both render as a delegation.
+const isDelegation = name => name === 'Agent' || name === 'Task'
 const escapeHtml = value => String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]))
 const languageFor = file => EXTENSIONS[String(file || '').split('.').pop().toLowerCase()] || null
 const duration = ms => ms == null ? null : ms < 1000 ? `${ms}ms` : ms < 60000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms / 60000)}m ${Math.round(ms % 60000 / 1000)}s`
@@ -87,7 +91,8 @@ function toolBody(message) {
     const mark = t => t.status === 'completed' ? '☑' : t.status === 'in_progress' ? '▸' : '☐'
     return `<ul class="block-todos">${todos.map(t => `<li class="todo-${escapeHtml(t.status)}"><span aria-hidden="true">${mark(t)}</span>${escapeHtml(t.content || t.activeForm || '')}</li>`).join('')}</ul>`
   }
-  if (name === 'Task' || name === 'Skill') return codeHtml(input.prompt || input.args || input.description || '', 'plaintext')
+  if (isDelegation(name)) return `<details class="delegation-mandate" data-delegation="mandate"><summary>Mandate</summary>${proseHtml(input.prompt || input.description || 'No mandate recorded.')}</details>`
+  if (name === 'Skill') return codeHtml(input.prompt || input.args || input.description || '', 'plaintext')
   if (name === 'AskUserQuestion') return ''
   // The header already shows the main argument, so repeating it as JSON is noise.
   const shown = TARGET_KEYS[name] || 'file_path'
@@ -95,6 +100,12 @@ function toolBody(message) {
   return Object.keys(rest).length ? codeHtml(JSON.stringify(rest, null, 2), 'json') : ''
 }
 function resultHtml(message) {
+  if (isDelegation(message.tool)) {
+    const report = String(message.result || '')
+    if (!report) return `<p class="block-note">${message.status === 'running' ? 'Awaiting report…' : message.status === 'error' ? 'Delegation failed without a report.' : 'No report returned.'}</p>`
+    const long = report.length > 1200 || report.split('\n').length > 16
+    return `<details class="delegation-report" data-delegation="report"${long ? '' : ' open'}><summary>Returned report${long ? ' · long' : ''}</summary>${proseHtml(report)}${message.truncated ? '<p class="block-note">Report truncated by Fleet.</p>' : ''}</details>`
+  }
   if (!message.result) return ''
   const language = message.tool === 'Read' ? languageFor(message.input?.file_path) : message.status === 'error' ? 'plaintext' : null
   const note = message.truncated ? '<p class="block-note">Output truncated by Fleet.</p>' : ''
@@ -107,10 +118,10 @@ function blockHtml(message, { streaming = false } = {}) {
     const icon = ICONS[message.tool] || '▸'
     const meta = [duration(message.ms), clock(message.at)].filter(Boolean).join(' · ')
     const state = message.status === 'error' ? 'is-failed' : message.status === 'running' ? 'is-running' : message.status === 'interrupted' ? 'is-interrupted' : 'is-done'
-    const stateLabel = state === 'is-done' ? '' : state.slice(3)
+    const stateLabel = state === 'is-done' ? isDelegation(message.tool) ? 'done' : '' : state.slice(3)
     const target = message.target ? `<span class="block-target" title="${escapeHtml(message.target)}">${escapeHtml(message.target)}</span>` : ''
     const auto = message.approval === 'auto' ? '<span class="block-auto" title="Fleet approved this automatically">auto</span>' : ''
-    return `<div class="block-head"><span class="block-icon" aria-hidden="true">${icon}</span><span class="block-tool">${escapeHtml(message.tool)}</span>${target}<span class="block-meta">${escapeHtml(meta)}</span>${auto}<span class="block-state ${state}">${stateLabel}</span>${actionsHtml}</div><div class="block-body">${toolBody(message)}${resultHtml(message)}</div>`
+    return `<div class="block-head"><span class="block-icon" aria-hidden="true">${icon}</span><span class="block-tool">${isDelegation(message.tool) ? `Delegation · ${escapeHtml(message.input?.subagent_type || 'subagent')}` : escapeHtml(message.tool)}</span>${target}<span class="block-meta">${escapeHtml(meta)}</span>${auto}<span class="block-state ${state}">${stateLabel}</span>${actionsHtml}</div><div class="block-body">${toolBody(message)}${resultHtml(message)}</div>`
   }
   const who = message.role === 'user' ? 'YOU' : 'CLAUDE'
   const icon = message.role === 'user' ? '›' : '✳'
@@ -152,14 +163,16 @@ function renderBlocks(container, messages, { streamingId = null, onCopy = () =>
       element.className = 'block'
       element.dataset.block = message.id
       // Long tool output starts collapsed, the way a long command block does in a terminal.
-      if (message.role === 'tool' && (message.result || '').length > 1200) element.classList.add('collapsed')
+      if (message.role === 'tool' && !isDelegation(message.tool) && (message.result || '').length > 1200) element.classList.add('collapsed')
     }
     if (element.dataset.sig !== sig) {
       element.dataset.sig = sig
       element.dataset.role = message.role
       element.dataset.tool = message.tool || ''
       element.dataset.status = message.status || ''
+      const disclosures = new Map([...element.querySelectorAll('[data-delegation]')].map(el => [el.dataset.delegation, el.open]))
       element.innerHTML = blockHtml(message, { streaming })
+      for (const el of element.querySelectorAll('[data-delegation]')) if (disclosures.has(el.dataset.delegation)) el.open = disclosures.get(el.dataset.delegation)
       element.querySelector('[data-collapse]')?.addEventListener('click', event => {
         const collapsed = element.classList.toggle('collapsed')
         event.currentTarget.setAttribute('aria-expanded', String(!collapsed))

package/public/control.js

@@ -20,10 +20,37 @@ async function initializeControls() {
   controlToken=data.token
   if(!$('launch-cwd').value) $('launch-cwd').value=data.defaultCwd
 }
+let launchTeams=null, launchTeamsLoading=false
+function updateLaunchTeam() {
+  const team=resumeSource ? null : launchTeams?.find(t=>t.id===$('launch-team')?.value)
+  $('launch-title').textContent=resumeSource ? 'Continue this conversation in Fleet.' : team ? 'Give your team a brief.' : 'Give your next task a home.'
+  document.querySelector('label[for="launch-prompt"]').textContent=team ? 'Brief for the manager' : 'What are we working on?'
+  document.querySelector('.launch-task-note').textContent=team ? `You talk to the ${team.manager || 'manager'}. They delegate to the team and bring the reports back here.` : 'Big ideas, small fixes. Every task starts here.'
+  $('launch-prompt').placeholder=team ? 'Describe the goal, boundaries, verification steps, and what a good result looks like.' : 'There’s something I’d love your help with…\n\nDescribe the task, what a good result looks like, and anything your agent should know.'
+  if(!$('launch-submit').disabled) $('launch-submit').textContent=team ? 'Launch initiative ↗' : 'Launch agent ↗'
+  $('launch-team').disabled=!!resumeSource || launchTeamsLoading || $('launch-submit').disabled
+  $('launch-team-note').textContent=resumeSource ? 'Continuing with the existing agent.' : team ? [team.description, `Roles: ${team.roles.map(r=>r.name).join(', ')}.`].filter(Boolean).join(' ') : launchTeamsLoading ? 'Loading teams…' : launchTeams ? 'No team keeps this a single-agent conversation.' : 'Teams unavailable. Reopen this dialog to retry; single agents are still available.'
+}
+async function loadLaunchTeams() {
+  if(!$('launch-team')) {
+    document.querySelector('.launch-fields').insertAdjacentHTML('afterbegin','<label for="launch-team">Team<select id="launch-team" name="teamId" aria-describedby="launch-team-note"><option value="">No team · single agent</option></select><span class="note" id="launch-team-note" role="status"></span></label>')
+    $('launch-team').addEventListener('change',()=>{launchRequestId=null;updateLaunchTeam()})
+  }
+  if(launchTeams || launchTeamsLoading){updateLaunchTeam();return}
+  launchTeamsLoading=true;updateLaunchTeam()
+  try {
+    const data=await api('/api/teams')
+    if(!Array.isArray(data.teams)) throw new Error('Invalid teams')
+    launchTeams=data.teams
+    for(const team of launchTeams) $('launch-team').add(new Option(team.name,team.id))
+  } catch { launchTeams=null }
+  finally {launchTeamsLoading=false;updateLaunchTeam()}
+}
 function openLaunch(source=null) {
   resumeSource=source
   $('launch-title').textContent=source ? 'Continue this conversation in Fleet.' : 'Give your next task a home.'
   if(source){$('launch-cwd').value=source.cwd || '';$('launch-form').elements.name.value=source.title || source.name || ''}
+  loadLaunchTeams()
   $('launch-cwd').readOnly=!!source
   openModal('launch-backdrop', '[name=prompt]')
 }
@@ -41,17 +68,17 @@ $('launch-form').addEventListener('submit',async event=>{
   const button=$('launch-submit'); if(button.disabled)return
   button.disabled=true;button.textContent='Launching…';$('launch-error').hidden=true
   const form=event.currentTarget
-  form.querySelectorAll('input,textarea').forEach(el=>el.disabled=true)
+  form.querySelectorAll('input,textarea,select').forEach(el=>el.disabled=true)
   launchRequestId ||= crypto.randomUUID()
   try{
-    const data=await api('/api/managed',{cwd:form.elements.cwd.value,name:form.elements.name.value,prompt:form.elements.prompt.value,approvalMode:form.elements.approvalMode.value,model:form.elements.model.value,requestId:launchRequestId,...(resumeSource ? {resumeSessionId:resumeSource.sessionId}: {})})
+    const data=await api('/api/managed',{...(form.elements.teamId?.value && !resumeSource ? {teamId:form.elements.teamId.value}: {}),cwd:form.elements.cwd.value,name:form.elements.name.value,prompt:form.elements.prompt.value,approvalMode:form.elements.approvalMode.value,model:form.elements.model.value,requestId:launchRequestId,...(resumeSource ? {resumeSessionId:resumeSource.sessionId}: {})})
     selected=data.session.id;filter='all'
     form.elements.prompt.value='';launchRequestId=null
     closeModal()
-    await tick();toast('Agent launched')
+    await tick();toast(form.elements.teamId?.value && !resumeSource ? 'Initiative launched' : 'Agent launched')
     if(matchMedia('(max-width:720px)').matches)$('detail').scrollIntoView({block:'start',behavior:'instant'})
   }catch(error){$('launch-error').textContent=error.message;$('launch-error').hidden=false}
-  finally{button.disabled=false;button.textContent='Launch agent ↗';form.querySelectorAll('input,textarea').forEach(el=>el.disabled=false)}
+  finally{button.disabled=false;button.textContent='Launch agent ↗';form.querySelectorAll('input,textarea,select').forEach(el=>el.disabled=false);if($('launch-team'))updateLaunchTeam()}
 })
 function selectControl(session) {
   const next=session?.managedId || null
@@ -155,7 +182,11 @@ function renderControl() {
 function renderApprovals(approvals) {
   $('approvals').innerHTML=approvals.map(p=>{
     const question=p.tool==='AskUserQuestion'
-    return `<form class="approval" data-approval="${esc(p.id)}"><div class="eyebrow">${question?'CLAUDE HAS A QUESTION':'APPROVAL REQUIRED'}</div><h4>${esc(p.description || p.tool)}</h4>${p.reason && !question ? `<p class="approval-reason">${esc(p.reason)}</p>` : ''}${question ? (p.input.questions || []).map((q,i)=>`<fieldset><legend>${esc(q.question)}</legend>${(q.options || []).map(o=>`<label class="answer-option"><input type="${q.multiSelect?'checkbox':'radio'}" name="q${i}" value="${esc(o.label)}"><span>${esc(o.label)}${o.description?`<small>${esc(o.description)}</small>`:''}</span></label>`).join('')}<label class="other-answer">Your answer<input type="text" name="other${i}" placeholder="Or type your own answer" maxlength="4000"></label></fieldset>`).join('') : `<pre class="tool-input">${esc(JSON.stringify(p.input,null,2))}</pre>`}<div class="approval-actions"><button class="button" type="button" data-deny="${esc(p.id)}">${question?'Skip question':'Deny'}</button><button class="button resume" type="submit">${question?'Send answer':'Allow once'}</button></div><p class="form-error" role="alert" hidden></p></form>`
+    // Inside an initiative, which role wants this is the whole question. "Approve rm?" with
+    // no name attached is how an operator ends up approving something the developer asked
+    // for while believing the manager did.
+    const who=p.role ? ` · ${esc(p.role.toUpperCase())}` : ''
+    return `<form class="approval" data-approval="${esc(p.id)}"><div class="eyebrow">${question?'CLAUDE HAS A QUESTION':'APPROVAL REQUIRED'}${who}</div><h4>${esc(p.description || p.tool)}</h4>${p.reason && !question ? `<p class="approval-reason">${esc(p.reason)}</p>` : ''}${question ? (p.input.questions || []).map((q,i)=>`<fieldset><legend>${esc(q.question)}</legend>${(q.options || []).map(o=>`<label class="answer-option"><input type="${q.multiSelect?'checkbox':'radio'}" name="q${i}" value="${esc(o.label)}"><span>${esc(o.label)}${o.description?`<small>${esc(o.description)}</small>`:''}</span></label>`).join('')}<label class="other-answer">Your answer<input type="text" name="other${i}" placeholder="Or type your own answer" maxlength="4000"></label></fieldset>`).join('') : `<pre class="tool-input">${esc(JSON.stringify(p.input,null,2))}</pre>`}<div class="approval-actions"><button class="button" type="button" data-deny="${esc(p.id)}">${question?'Skip question':'Deny'}</button><button class="button resume" type="submit">${question?'Send answer':'Allow once'}</button></div><p class="form-error" role="alert" hidden></p></form>`
   }).join('')
   $('approvals').querySelectorAll('form').forEach(form=>{
     const approval=approvals.find(p=>p.id===form.dataset.approval)

package/public/styles.css

@@ -452,3 +452,13 @@ body[data-modal]{overflow:hidden}
 .topbar .update-pill:disabled{opacity:.72;cursor:default}
 @media(prefers-reduced-motion:no-preference){.update-pill:not([hidden]){animation:update-pill-in .3s ease-out}}
 @keyframes update-pill-in{from{opacity:0;transform:translateY(-3px)}to{opacity:1;transform:none}}
+
+.initiative-tag{display:inline-block;max-width:100%;margin-top:6px;padding:2px 6px;border:1px solid var(--line);border-radius:3px;color:var(--muted);font-size:10px;overflow-wrap:anywhere}
+.block[data-tool="Task"],.block[data-tool="Agent"]{border-left:2px solid var(--accent)}
+.block[data-tool="Task"] .block-tool,.block[data-tool="Agent"] .block-tool{white-space:normal;overflow-wrap:anywhere}
+.delegation-mandate,.delegation-report{margin:0 13px;padding:12px 0}
+.delegation-report{border-top:1px solid var(--line)}
+.delegation-mandate>summary,.delegation-report>summary{cursor:pointer;color:var(--muted);font-size:11px;font-weight:600}
+.delegation-mandate>summary:focus-visible,.delegation-report>summary:focus-visible{outline:2px solid var(--accent);outline-offset:4px}
+.delegation-mandate .block-prose,.delegation-report .block-prose{padding:12px 0 0}
+.delegation-mandate .block-plain,.delegation-report .block-plain{white-space:pre-wrap;overflow-wrap:anywhere}

package/server.js

@@ -12,6 +12,8 @@ const { SearchJobs, warm: warmSearch, WINDOW_DAYS: SEARCH_DAYS } = require('./se
 const { Archive } = require('./archive.js')
 const { Updater } = require('./update.js')
 const { defaultCwd } = require('./paths.js')
+const { listTeams } = require('./teams.js')
+const { openDashboard } = require('./open.js')
 const { version: VERSION } = require('./package.json')
 const HOST = '127.0.0.1'
 const MODEL_FALLBACK = [
@@ -166,6 +168,7 @@ function createApp({manager = new ManagedSessions({externalSessions:()=>collect(
         return res.end(themeCss(currentTheme()))
       }
       if(url.pathname==='/api/models') return json(res,200,{models:manager.models || MODEL_FALLBACK})
+      if(url.pathname==='/api/teams') return json(res,200,{teams:listTeams()})
       if(url.pathname==='/api/sessions') return json(res,200,getSnapshot())
       if(url.pathname==='/api/events') {
         if(clients.size>=20) return json(res,429,{error:'Too many dashboard connections.'})
@@ -226,7 +229,21 @@ function main(){
     child.unref()
     setTimeout(()=>process.exit(0),100).unref()
   }
-  try{app=createApp({restart})}catch(error){console.error(error.message);process.exit(1)}
+  try{app=createApp({restart})}catch(error){
+    // Already running is the everyday case, not a crash: put the window the operator
+    // asked for on screen and leave quietly. Exiting 1 with no window was the whole
+    // reason a second `claude-fleet` looked like a broken one.
+    if(error.code==='FLEET_ALREADY_RUNNING'){
+      // A lock written by an older Fleet carries no port, so fall back to the one this
+      // run would have asked for. Every lock written from here on records the real one.
+      const running=error.holder?.port||Number(process.env.PORT||7777)
+      const target=`http://${HOST}:${running}`
+      console.log(`\n  ${error.message} → ${target}\n`)
+      if(process.argv.includes('--open')) openDashboard(target,{app:!process.argv.includes('--browser')})
+      process.exit(0)
+    }
+    console.error(error.message);process.exit(1)
+  }
   let attempt=0,port=Number(process.env.PORT||7777)
   app.server.on('error',async error=>{
     if(error.code==='EADDRINUSE' && attempt++<10){app.server.listen(++port,HOST);return}
@@ -234,16 +251,14 @@ function main(){
   })
   app.server.on('listening',()=>{
     const url=`http://${HOST}:${app.server.address().port}`
+    // Write the port where the next `claude-fleet` will look for it.
+    app.manager.recordPort(app.server.address().port)
     console.log(`\n  Claude Fleet v${VERSION} → ${url}\n  Local dashboard + managed agents · ctrl-c to stop\n`)
     // Index transcripts in the background so the first question does not wait for it.
     setTimeout(()=>warmSearch().catch(()=>{}),1500).unref()
     // And ask npm whether there is a newer Fleet, well after the page has loaded.
     setTimeout(()=>app.updater.check().catch(()=>{}),5000).unref()
-    if(process.argv.includes('--open')) {
-      const opener=process.platform==='darwin'?'open':'xdg-open'
-      const child=require('node:child_process').spawn(opener,[url],{stdio:'ignore'})
-      child.on('error',()=>{});child.unref()
-    }
+    if(process.argv.includes('--open')) openDashboard(url,{app:!process.argv.includes('--browser')})
   })
   app.server.listen(port,HOST)
   let closing=false

package/teams.js

@@ -0,0 +1,199 @@
+'use strict'
+// A team is a named set of roles. One role is the manager: it owns the main thread, so it
+// owns the conversation with the operator. The others are reachable only through the Agent
+// tool, which is what makes "you talk to the manager" structural rather than a house rule.
+//
+// Role prompts are deliberately project-agnostic. Fleet runs against whatever directory it
+// is pointed at, so a role discovers the repo's own gates instead of carrying someone's.
+
+// Every non-manager role gets this appended. Subagents do not know they are subagents, and
+// left unlabelled they write to the operator and try to delegate further.
+const SUBAGENT_RULE = `
+
+## You are a subagent
+
+You were invoked by the manager of an initiative. You are not talking to a person.
+Your reply goes back to the manager and to nobody else, so never address the operator,
+never ask them a question, and never promise to follow up.
+
+You cannot delegate. If the work is larger than your mandate, do the part that is clearly
+yours and say in your report exactly what you left and why. Returning a smaller honest
+result beats returning a larger invented one.`
+
+const MANAGER = `You are the manager of an initiative: one goal, a small team, and a single
+conversation with the operator. You are the only member of the team they can hear.
+
+## You do not write code
+
+You have no edit tools. That is deliberate, not an oversight to work around. Your only way
+to ship is to delegate, and the moment you start patching things yourself with shell
+redirection or heredocs the team stops meaning anything. If a change is one character, it
+is still the developer's change.
+
+## Order of work
+
+1. **Read before you plan.** Find the project's own instructions (CLAUDE.md, AGENTS.md,
+   CONTRIBUTING, README) and any rules scoped to the paths in question. Locate the actual
+   files the goal touches. A brief that says "fix the login redirect" maps onto specific
+   modules; find them before you split anything.
+
+2. **Find the gates.** Every repo has commands that decide whether work is acceptable:
+   a test runner, a type check, a linter. Read package.json scripts, the CI workflow, or
+   the contributing guide and write down the exact commands. You will hand these to every
+   delegate. Guessing at them wastes a whole round.
+
+3. **Ask if the goal is genuinely ambiguous.** Now, while it costs one message, rather than
+   after three delegations have built the wrong thing. Ambiguity that changes the work is
+   worth a question; ambiguity you can resolve by reading is not.
+
+4. **Split into tasks that cannot collide.** Each task is one deliverable with a file set
+   disjoint from every other task in flight. Two delegates editing the same file is the
+   most reliable way to make this whole arrangement fail. If two tasks need the same file,
+   they are one task, or they run in sequence.
+
+5. **Delegate with a complete mandate.** A delegate inherits none of your conversation and
+   none of your reading. Every delegation must carry four things or it will drift:
+   - **Objective**: what to change, in which files
+   - **Boundaries**: what it must not touch
+   - **Gates**: the exact commands that must pass, copied, not described
+   - **Done**: how you will know it worked, in terms someone else could check
+
+   Delegate to the roles on your team and never to yourself. You appear in your own roster
+   for mechanical reasons; invoking yourself buys nothing and costs a full context.
+
+6. **Have QA verify, and believe QA.** Send finished work to qa before you report it as
+   done. A developer's account of its own work is a claim, not evidence. If qa fails the
+   work, send it back to the developer with what qa found; do not overrule it because the
+   diff looks fine to you.
+
+7. **Report once, at the end of the turn.** One message to the operator: what changed, what
+   passed, what you deliberately did not do, and what you need from them if anything.
+   Not a running commentary.
+
+## Finishing
+
+When qa passes and the goal is met, commit on the initiative's branch and open a pull
+request with \`gh\`. Use the project's commit convention if it has one. Pushing will stop
+for the operator's approval, which is intended: they get the last look before anything
+leaves the machine.
+
+If you cannot finish, say so plainly and say what is blocking. A stalled initiative
+reported honestly is worth more than a green one that is lying.`
+
+const DEVELOPER = `You implement one scoped task inside an initiative, end to end.
+
+Work only inside the boundaries your mandate gives you. If the fix genuinely requires
+touching a file outside them, stop and report that, rather than reaching for it: the
+boundary probably exists because somebody else is in that file right now.
+
+Before you report anything as done, run the gates in your mandate and read the output. Not
+"they should pass", not "the change is small". Run them. If they fail and you cannot fix
+it, that is a legitimate report; a false green is not.
+
+Follow the conventions already in the files you are editing: their naming, their error
+handling, their comment density. New code should be hard to pick out of a diff by style
+alone.
+
+## Your report
+
+- what you changed, file by file
+- the gate commands you ran and what they printed
+- anything you deliberately did not do, and why
+- anything you found that the manager did not know about
+
+Keep it short enough to read and specific enough to act on.${SUBAGENT_RULE}`
+
+const QA = `You verify work inside an initiative. You are the only reason the manager can
+trust anything, so behave like it.
+
+You have no edit tools. You cannot fix what you find, and you should not want to: your
+output is a verdict with evidence, not a patch.
+
+## How to verify
+
+Start from the original problem, not from the diff. A reviewer who only reads the change
+agrees with the change. Reproduce the behaviour the initiative set out to fix, then check
+whether it is actually fixed.
+
+Run the gates yourself. The developer's report is a claim about what happened on their
+turn; re-running costs little and catches the difference between "I ran it" and "it
+passed". Read the output rather than the exit code alone where the two can disagree.
+
+Then look for what the mandate did not mention: cases the change breaks, boundaries it
+crossed, tests that assert the implementation instead of the behaviour, error paths that
+are now unreachable.
+
+## Your verdict
+
+Open with exactly one of **PASS** or **FAIL**, then the evidence.
+
+For a FAIL, state what you did, what you expected, what happened instead, and where. Be
+specific enough that the developer can act without asking you anything.
+
+Failing work is an ordinary outcome and the most useful thing you produce. Do not soften a
+FAIL into a pass with reservations, and do not pad a PASS with speculative concerns to look
+thorough. If it works, say it works.${SUBAGENT_RULE}`
+
+// Subagents must not spawn their own subagents: nothing supervises the result, and a
+// runaway nest is expensive before it is visible.
+const NO_DELEGATION = ['Agent', 'Task']
+const NO_EDITS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']
+
+const TEAMS = {
+  bugfix: {
+    id: 'bugfix',
+    name: 'Bug fix',
+    description: 'A manager who plans and delegates, a developer who implements, and a QA who independently verifies.',
+    manager: 'manager',
+    roles: {
+      manager: {
+        description: 'Plans the work, delegates it, and reports back. Never writes code.',
+        prompt: MANAGER,
+        model: 'opus',
+        effort: 'high',
+        disallowedTools: NO_EDITS,
+      },
+      developer: {
+        description: 'Implements one scoped task and runs the gates. Use for any change to the code.',
+        prompt: DEVELOPER,
+        model: 'opus',
+        effort: 'high',
+        disallowedTools: NO_DELEGATION,
+      },
+      qa: {
+        description: 'Independently verifies finished work and returns PASS or FAIL with evidence. Use before reporting anything as done.',
+        prompt: QA,
+        model: 'sonnet',
+        effort: 'medium',
+        disallowedTools: [...NO_EDITS, ...NO_DELEGATION],
+      },
+    },
+  },
+}
+
+function getTeam(id) {
+  if (!id) return null
+  return Object.prototype.hasOwnProperty.call(TEAMS, id) ? TEAMS[id] : null
+}
+
+// What the UI needs to offer a choice. Prompts are large and of no use to the browser.
+function listTeams() {
+  return Object.values(TEAMS).map(team => ({
+    id: team.id, name: team.name, description: team.description, manager: team.manager,
+    roles: Object.entries(team.roles).map(([name, role]) => ({
+      name, description: role.description, model: role.model || null,
+    })),
+  }))
+}
+
+// A team becomes two SDK options: `agent` names who holds the main thread, `agents` carries
+// every definition. The manager has to appear in `agents` too, because that is where `agent`
+// resolves the name from; it is not reachable as a subagent of itself by convention rather
+// than by construction, which is why its prompt says so outright.
+function compile(team) {
+  if (!team) return null
+  if (!team.roles[team.manager]) throw new Error(`Team ${team.id} names a manager role that does not exist.`)
+  return { agent: team.manager, agents: { ...team.roles } }
+}
+
+module.exports = { TEAMS, getTeam, listTeams, compile, roleNames: team => Object.keys(team.roles) }

package/worktree.js

@@ -0,0 +1,90 @@
+'use strict'
+// An initiative gets its own git worktree, so a team editing files cannot collide with the
+// operator's own checkout or with another initiative in the same repo. Worktrees live under
+// Fleet's state directory rather than inside the project, for the same reason the archive
+// does: Fleet's bookkeeping is Fleet's business and should be removable in one directory.
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+const { stateDir } = require('./paths')
+
+// Arguments always travel as an array. A branch name is operator-derived text and must
+// never reach a shell.
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+}
+
+function repoRoot(cwd) {
+  try { return git(cwd, ['rev-parse', '--show-toplevel']) } catch { return null }
+}
+
+// The branch an initiative forks from: the checked-out branch, or the commit itself when
+// HEAD is detached, which still gives the worktree something to stand on.
+//
+// A repository with no commits answers `symbolic-ref` perfectly happily with its unborn
+// branch, so the name alone proves nothing. Confirm HEAD resolves to a commit first, or the
+// operator gets `fatal: invalid reference: main` instead of being told the repo is empty.
+function baseRef(root) {
+  try { git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']) } catch { return null }
+  try {
+    const branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+    if (branch) return branch
+  } catch {}
+  try { return git(root, ['rev-parse', 'HEAD']) } catch { return null }
+}
+
+function slugify(value, fallback) {
+  const slug = String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+  return slug || fallback
+}
+
+function branchExists(root, branch) {
+  try { git(root, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]); return true } catch { return false }
+}
+
+// Create the worktree for one initiative. Throws with a message meant for the operator:
+// every failure here happens at launch, where there is still a human watching.
+function create({ cwd, id, name }) {
+  const root = repoRoot(cwd)
+  if (!root) {
+    const error = new Error('An initiative needs a git repository: its team works on a branch and finishes with a pull request. Point it at a checkout, or launch a single agent instead.')
+    error.status = 400
+    throw error
+  }
+  const base = baseRef(root)
+  if (!base) {
+    const error = new Error('This repository has no commits yet, so there is nothing to branch from.')
+    error.status = 400
+    throw error
+  }
+
+  const short = String(id).slice(0, 8)
+  let branch = `initiative/${slugify(name, short)}`
+  if (branchExists(root, branch)) branch = `${branch}-${short}`
+
+  const dir = path.join(stateDir(), 'worktrees', short)
+  fs.mkdirSync(path.dirname(dir), { recursive: true, mode: 0o700 })
+  if (fs.existsSync(dir)) {
+    const error = new Error(`A worktree already exists at ${dir}.`)
+    error.status = 409
+    throw error
+  }
+
+  try { git(root, ['worktree', 'add', '-b', branch, dir, base]) }
+  catch (cause) {
+    const error = new Error(`Could not create a worktree for this initiative: ${String(cause.stderr || cause.message).trim().slice(0, 500)}`)
+    error.status = 400
+    throw error
+  }
+  return { path: dir, branch, base, repo: root }
+}
+
+// Best effort: an initiative whose worktree is gone is still readable, and a half-removed
+// worktree is worse than one left behind for `git worktree prune` to notice.
+function remove(worktree) {
+  if (!worktree?.path || !worktree?.repo) return false
+  try { git(worktree.repo, ['worktree', 'remove', '--force', worktree.path]); return true }
+  catch { return false }
+}
+
+module.exports = { create, remove, repoRoot, baseRef, slugify }