@sergeychuvayev/claude-fleet 0.1.0

package/server.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+'use strict'
+const http = require('node:http')
+const fs = require('node:fs')
+const path = require('node:path')
+const { randomBytes, timingSafeEqual } = require('node:crypto')
+const { collect, transcriptFor } = require('./fleet.js')
+const { ManagedSessions } = require('./managed.js')
+const { readTheme, themeCss } = require('./theme.js')
+const { collect: collectCatalog } = require('./catalog.js')
+const { SearchJobs, warm: warmSearch, WINDOW_DAYS: SEARCH_DAYS } = require('./search.js')
+const { Archive } = require('./archive.js')
+const { Updater } = require('./update.js')
+const { defaultCwd } = require('./paths.js')
+const { version: VERSION } = require('./package.json')
+const HOST = '127.0.0.1'
+const MODEL_FALLBACK = [
+  { value:'', displayName:'Project default', description:'Whatever this project is configured to use' },
+  { value:'opus', displayName:'Opus', description:'Most capable' },
+  { value:'sonnet', displayName:'Sonnet', description:'Balanced' },
+  { value:'haiku', displayName:'Haiku', description:'Fastest' },
+]
+const PUBLIC = path.join(__dirname,'public')
+const TYPES = {'.html':'text/html; charset=utf-8','.css':'text/css; charset=utf-8','.js':'text/javascript; charset=utf-8','.svg':'image/svg+xml','.png':'image/png','.jpg':'image/jpeg','.gif':'image/gif','.webp':'image/webp','.webmanifest':'application/manifest+json'}
+
+function createApp({manager = new ManagedSessions({externalSessions:()=>collect().sessions}), collectSessions = collect, search = new SearchJobs(), archive = new Archive(), updater = new Updater(), restart = null} = {}) {
+  const token=randomBytes(32).toString('hex')
+  const clients=new Set(), changes=new Set()
+  let eventTimer=null, storageError=null
+  const broadcast=()=>{
+    eventTimer=null
+    const data=`event: sessions\ndata: ${JSON.stringify([...changes])}\n\n`
+    changes.clear()
+    for (const res of clients) if (!res.write(data)) { res.end(); clients.delete(res) }
+  }
+  manager.on('change',id=>{changes.add(id);if(!eventTimer) eventTimer=setTimeout(broadcast,120)})
+  manager.on('storage-error',error=>{storageError='Unable to save Fleet conversations. Check disk space and permissions.';console.error(error.message)})
+  let theme=readTheme(), themeReadAt=Date.now()
+  const currentTheme=()=>{
+    if(Date.now()-themeReadAt>30000){theme=readTheme();themeReadAt=Date.now()}
+    return theme
+  }
+  const heartbeat=setInterval(()=>{for(const res of clients) res.write(': heartbeat\n\n')},15000)
+  heartbeat.unref()
+  const json=(res,status,body)=>{res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store'});res.end(JSON.stringify(body))}
+  const elsewhere=(row)=>row && row.alive ? {pid:row.pid,name:row.name || row.shortId || null,entrypoint:row.entrypoint || null,background:!!row.background,state:row.state,startedAt:row.startedAt || null} : null
+  const getSnapshot=()=>{
+    const snap=collectSessions()
+    const managed=manager.summaries()
+    const managedIds=new Set(managed.map(s=>s.sessionId).filter(Boolean))
+    const external=snap.sessions.filter(s=>!managedIds.has(s.sessionId))
+    for(const s of managed) {
+      const transcript=snap.sessions.find(t=>t.sessionId===s.sessionId)
+      const holder=elsewhere(transcript)
+      if(holder){
+        s.openElsewhere=holder
+        s.state=holder.state==='busy' ? 'busy' : 'idle'; s.alive=true
+        if(transcript.turn) s.turn=transcript.turn
+        s.lastActivity=Math.max(s.lastActivity || 0, transcript.lastActivity || 0)
+      }
+      if(transcript){
+        s.branch=transcript.branch || s.branch
+        s.links=[...new Map([...(transcript.links||[]),...s.links].map(l=>[l.url,l])).values()].slice(-20)
+        s.transcriptTruncated=transcript.transcriptTruncated
+        // Claude names its own sessions once a conversation has taken shape. Prefer
+        // that over Fleet's first-prompt slice, and keep it for the detail view too.
+      }
+      // Claude names its own sessions once a conversation has taken shape. Prefer
+      // that over Fleet's first-prompt slice, and keep it for the detail view too.
+      const aiTitle=transcriptFor(s.sessionId)?.title
+      if(aiTitle){s.title=aiTitle;try{manager.get(s.managedId).aiTitle=aiTitle}catch{}}
+    }
+    const sessions=[...managed,...external].sort((a,b)=>{
+      const rank=s=>s.managedStatus==='approval'?0:s.state==='busy'?1:s.state==='idle'?2:s.state==='stale'?3:4
+      return rank(a)-rank(b) || (b.lastActivity||0)-(a.lastActivity||0)
+    })
+    // Archived rows are still sent, flagged: the dashboard needs them to offer an
+    // Archived filter, and the counts above them describe the fleet you are working.
+    const counts={busy:0,idle:0,stale:0,dead:0}
+    let archived=0
+    for(const s of sessions){
+      s.archived=archive.isArchived(s)
+      if(s.archived) archived++
+      else counts[s.state]++
+    }
+    return {...snap,sessions,counts,total:sessions.length-archived,archived,archiveRule:archive.rule,storageError}
+  }
+  const authorized=(req)=>{
+    const supplied=req.headers['x-fleet-token']
+    if(typeof supplied!=='string' || supplied.length!==token.length) return false
+    return timingSafeEqual(Buffer.from(supplied),Buffer.from(token))
+  }
+  async function body(req, limit = 65536) {
+    if (!(req.headers['content-type'] || '').startsWith('application/json')) throw Object.assign(new Error('JSON content type is required.'),{status:415})
+    let size=0, chunks=[]
+    for await(const chunk of req){size+=chunk.length;if(size>limit) throw Object.assign(new Error(limit > 65536 ? 'Attachments are too large for one message.' : 'Request is too large.'),{status:413});chunks.push(chunk)}
+    let data
+    try{data=JSON.parse(Buffer.concat(chunks).toString('utf8'))}catch{throw Object.assign(new Error('Invalid JSON.'),{status:400})}
+    if(!data || typeof data!=='object' || Array.isArray(data)) throw Object.assign(new Error('Expected a JSON object.'),{status:400})
+    return data
+  }
+  const server=http.createServer(async(req,res)=>{
+    res.setHeader('X-Content-Type-Options','nosniff')
+    res.setHeader('Referrer-Policy','no-referrer')
+    res.setHeader('X-Frame-Options','DENY')
+    res.setHeader('Content-Security-Policy',"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'self'")
+    try{
+      const port=server.address()?.port
+      const hosts=new Set([`127.0.0.1:${port}`,`localhost:${port}`])
+      if(!hosts.has(req.headers.host)) return json(res,403,{error:'Invalid host.'})
+      const origin=req.headers.origin
+      if(origin && origin!==`http://${req.headers.host}`) return json(res,403,{error:'Cross-origin requests are not allowed.'})
+      if(req.headers['sec-fetch-site']==='cross-site') return json(res,403,{error:'Cross-site requests are not allowed.'})
+      const url=new URL(req.url,`http://${req.headers.host}`)
+      if(req.method==='POST') {
+        if(!authorized(req)) return json(res,403,{error:'Reload Fleet before sending commands.'})
+        // Stopping an agent and installing an update both stay available when the
+        // session store is unwritable: one is an escape hatch, the other may be the fix.
+        if(storageError && url.pathname!=='/api/update' && !/^\/api\/managed\/[\w-]+\/stop$/.test(url.pathname)) return json(res,503,{error:storageError})
+        // Only the two endpoints that carry a message accept image-sized bodies.
+        const carriesMessage=url.pathname==='/api/managed' || /^\/api\/managed\/[\w-]+\/messages$/.test(url.pathname)
+        const data=await body(req, carriesMessage ? 40 * 1024 * 1024 : 65536)
+        if(url.pathname==='/api/managed') return json(res,201,{session:manager.detail(manager.create(data).id)})
+        // Keyword hits come back at once; the answer is fetched by id while Claude reads them.
+        if(url.pathname==='/api/search') return json(res,201,{job:search.start(data)})
+        if(url.pathname==='/api/archive') return json(res,200,{changed:archive.set(data.ids,data.archived!==false),archived:archive.archived.size})
+        if(url.pathname==='/api/archive/rule') return json(res,200,{rule:archive.setRule(data)})
+        if(url.pathname==='/api/update'){
+          const update=await updater.apply()
+          // The new code is on disk but this process is still the old one. Hand the
+          // port over once the answer has been written, so the page knows to wait.
+          if(restart) setTimeout(()=>{restart().catch(error=>console.error(error.message))},250).unref()
+          return json(res,200,{update:{...update,restarting:!!restart}})
+        }
+        const match=url.pathname.match(/^\/api\/managed\/([\w-]+)\/(messages|stop|mode|model|close|approvals\/([\w-]+))$/)
+        if(!match) return json(res,404,{error:'Unknown action.'})
+        const [,id,action,approvalId]=match
+        if(action==='close') return json(res,200,{closed:await manager.remove(id)})
+        if(action==='messages') manager.send(id,data)
+        else if(action==='stop') manager.stop(id)
+        else if(action==='mode') manager.setMode(id,data)
+        else if(action==='model') manager.setModelChoice(id,data)
+        else manager.decide(id,approvalId,data)
+        return json(res,200,{session:manager.detail(id)})
+      }
+      if(req.method!=='GET') return json(res,405,{error:'Method not allowed.'})
+      if(url.pathname==='/api/control') return json(res,200,{token,version:VERSION,defaultCwd:defaultCwd(),maxConcurrent:4,storageError,searchDays:SEARCH_DAYS,theme:{name:currentTheme().name,source:currentTheme().source}})
+      if(url.pathname==='/api/update'){
+        // Answer from the cache and refresh behind the request: a page load should
+        // never wait on npm's registry, and the dashboard asks again shortly after.
+        updater.check().catch(()=>{})
+        return json(res,200,{update:updater.status()})
+      }
+      if(url.pathname==='/manifest.webmanifest'){
+        const theme=currentTheme()
+        res.writeHead(200,{'content-type':TYPES['.webmanifest'],'cache-control':'no-cache'})
+        return res.end(JSON.stringify({
+          name:'Claude Fleet', short_name:'Fleet', description:'Local control room for Claude Code sessions',
+          start_url:'/', scope:'/', display:'standalone', orientation:'any',
+          background_color:theme.background, theme_color:theme.background,
+          icons:[192,512].map(size=>({src:`/icons/fleet-${size}.png`,sizes:`${size}x${size}`,type:'image/png',purpose:'any maskable'})),
+        }))
+      }
+      if(url.pathname==='/theme.css'){
+        res.writeHead(200,{'content-type':TYPES['.css'],'cache-control':'no-cache'})
+        return res.end(themeCss(currentTheme()))
+      }
+      if(url.pathname==='/api/models') return json(res,200,{models:manager.models || MODEL_FALLBACK})
+      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.'})
+        res.writeHead(200,{'content-type':'text/event-stream','cache-control':'no-store','connection':'keep-alive','x-accel-buffering':'no'})
+        res.write(': connected\n\n');clients.add(res)
+        req.on('close',()=>clients.delete(res));return
+      }
+      const searchJob=url.pathname.match(/^\/api\/search\/([\w-]+)$/)
+      if(searchJob) return json(res,200,{job:search.get(searchJob[1])})
+      const commands=url.pathname.match(/^\/api\/managed\/([\w-]+)\/commands$/)
+      if(commands) return json(res,200,{commands:collectCatalog(manager.detail(commands[1]).cwd)})
+      const attachment=url.pathname.match(/^\/api\/attachments\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(png|jpg|gif|webp))$/)
+      if(attachment){
+        let data
+        try{ data=await fs.promises.readFile(path.join(manager.attachmentsDir,attachment[1])) }
+        catch{ return json(res,404,{error:'Attachment not found.'}) }
+        res.writeHead(200,{'content-type':TYPES['.'+attachment[2]],'cache-control':'private, max-age=31536000, immutable','content-length':data.length})
+        return res.end(data)
+      }
+      const detail=url.pathname.match(/^\/api\/managed\/([\w-]+)$/)
+      if(detail){
+        const session=manager.detail(detail[1])
+        const holder=elsewhere(collectSessions().sessions.find(t=>t.sessionId===session.sessionId))
+        if(holder) session.openElsewhere=holder
+        return json(res,200,{session})
+      }
+      const files={'/':'index.html','/index.html':'index.html','/styles.css':'styles.css','/app.js':'app.js','/control.js':'control.js','/blocks.js':'blocks.js','/ask.js':'ask.js','/vendor/libs.js':path.join('vendor','libs.js'),'/icons/fleet-192.png':path.join('icons','fleet-192.png'),'/icons/fleet-512.png':path.join('icons','fleet-512.png')}
+      const file=files[url.pathname]
+      if(!file) return json(res,404,{error:'Not found.'})
+      const data=await fs.promises.readFile(path.join(PUBLIC,file))
+      res.writeHead(200,{'content-type':TYPES[path.extname(file)],'cache-control':'no-cache'});res.end(data)
+    }catch(error){if(!res.headersSent) json(res,error.status||500,{error:error.status ? error.message : 'Fleet could not complete the request. Check the server log.'});else res.end();if(!error.status) console.error(error)}
+  })
+  server.requestTimeout=15000
+  server.headersTimeout=10000
+  async function close(){clearTimeout(eventTimer);clearInterval(heartbeat);for(const res of clients)res.end();server.close();await Promise.all([manager.close(),search.close()])}
+  return {server,manager,search,archive,updater,close,getSnapshot}
+}
+
+// Starting the server is the CLI's job too, so it lives in a function rather than
+// in a `require.main` block: bin/claude-fleet.js calls this, which keeps argv[1]
+// pointing at the installed command that a restart needs to re-run.
+function main(){
+  let app
+  // Hand the port to the version that was just installed. argv[1] is the entry npm
+  // put on PATH; the update replaced what it points at, so re-running it runs the
+  // new code. The session lock and the port are both released by close() first.
+  const restart=async()=>{
+    const entry=process.argv[1]
+    const held=app.server.address()?.port || port
+    // The page that asked for this is already open and waiting to be reloaded, so
+    // the replacement must not raise a second window. Dropping --open is not enough:
+    // with no command, the CLI opens one by default. --no-open says it outright.
+    const args=[...process.argv.slice(2).filter(a=>a!=='--open'),'--no-open']
+    await app.close()
+    const child=require('node:child_process').spawn(process.execPath,[entry,...args],{detached:true,stdio:'ignore',env:{...process.env,PORT:String(held)}})
+    child.on('error',error=>{console.error(`Could not restart Fleet: ${error.message}`);process.exit(1)})
+    child.unref()
+    setTimeout(()=>process.exit(0),100).unref()
+  }
+  try{app=createApp({restart})}catch(error){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}
+    console.error(error.message);await app.close();process.exit(1)
+  })
+  app.server.on('listening',()=>{
+    const url=`http://${HOST}:${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()
+    }
+  })
+  app.server.listen(port,HOST)
+  let closing=false
+  const shutdown=async()=>{if(closing)return;closing=true;await app.close();process.exit(0)}
+  process.on('SIGINT',shutdown);process.on('SIGTERM',shutdown)
+  return app
+}
+if(require.main===module) main()
+module.exports={createApp,main}

package/theme.js

@@ -0,0 +1,89 @@
+'use strict'
+// Reads the colours out of the local Warp configuration so Fleet matches the terminal
+// the operator already uses. Nothing here is required: every failure falls back to the
+// built-in palette, and only colour and font-size values are ever read.
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const HEX = /^#[0-9a-fA-F]{3,8}$/
+const SLOTS = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']
+const FALLBACK = {
+  name: 'Fleet Default',
+  background: '#0c1014', foreground: '#99d1ce', accent: '#2aa889', cursor: '#2aa889',
+  normal: { black: '#0c1014', red: '#c23127', green: '#2aa889', yellow: '#edb443', blue: '#195466', magenta: '#4e5166', cyan: '#33859e', white: '#99d1ce' },
+  bright: { black: '#11151c', red: '#d26937', green: '#2aa889', yellow: '#edb443', blue: '#195466', magenta: '#888ca6', cyan: '#33859e', white: '#d3ebe9' },
+  fontSize: 13,
+  source: null,
+}
+
+const colour = value => (typeof value === 'string' && HEX.test(value.trim()) ? value.trim() : null)
+const unquote = value => value.trim().replace(/^["']|["']$/g, '').trim()
+
+// A deliberately small YAML reader: Warp theme files are two levels of `key: value`.
+function parseThemeYaml(text) {
+  const out = {}
+  let section = null, group = null
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\t/g, '  ')
+    if (!line.trim() || line.trim().startsWith('#')) continue
+    const indent = line.length - line.trimStart().length
+    const match = line.trim().match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/)
+    if (!match) continue
+    const [, key, rest] = match
+    const value = unquote(rest)
+    if (indent === 0) { section = key; group = null; if (value) out[key] = value; else out[key] = {} }
+    else if (indent <= 3) { group = key; if (section && typeof out[section] === 'object') { if (value) out[section][key] = value; else out[section][key] = {} } }
+    else if (section && group && out[section]?.[group] && typeof out[section][group] === 'object') out[section][group][key] = value
+  }
+  return out
+}
+
+// Warp's settings.toml, read only for the active theme path and the terminal font size.
+function parseSettings(text) {
+  const themeLine = text.match(/^\s*theme\s*=\s*(.+)$/m)?.[1] ?? ''
+  const fontSize = Number(text.match(/^\s*font_size\s*=\s*([\d.]+)/m)?.[1])
+  return {
+    themePath: unquote(themeLine.match(/path\s*=\s*("[^"]*"|'[^']*')/)?.[1] ?? '') || null,
+    fontSize: Number.isFinite(fontSize) && fontSize >= 8 && fontSize <= 32 ? fontSize : null,
+  }
+}
+
+function readTheme(warpDirectory = process.env.CLAUDE_FLEET_WARP_DIR || path.join(os.homedir(), '.warp')) {
+  const theme = structuredClone(FALLBACK)
+  try {
+    const settingsFile = path.join(warpDirectory, 'settings.toml')
+    if (!fs.existsSync(settingsFile)) return theme
+    const settings = parseSettings(fs.readFileSync(settingsFile, 'utf8'))
+    if (settings.fontSize) theme.fontSize = settings.fontSize
+    if (!settings.themePath) return theme
+    // Confine the lookup to the themes directory; a settings file never picks arbitrary paths.
+    const themesDirectory = path.join(warpDirectory, 'themes')
+    const file = path.resolve(themesDirectory, settings.themePath)
+    if (!file.startsWith(themesDirectory + path.sep) || !fs.existsSync(file)) return theme
+    if (fs.statSync(file).size > 64 * 1024) return theme
+    const parsed = parseThemeYaml(fs.readFileSync(file, 'utf8'))
+    theme.source = path.basename(file)
+    if (typeof parsed.name === 'string' && parsed.name.trim()) theme.name = parsed.name.trim().slice(0, 60)
+    for (const key of ['background', 'foreground', 'accent', 'cursor']) theme[key] = colour(parsed[key]) || theme[key]
+    for (const group of ['normal', 'bright']) for (const slot of SLOTS) {
+      theme[group][slot] = colour(parsed.terminal_colors?.[group]?.[slot]) || theme[group][slot]
+    }
+  } catch { return structuredClone(FALLBACK) }
+  return theme
+}
+
+function themeCss(theme) {
+  const lines = [
+    `--w-bg: ${theme.background};`,
+    `--w-fg: ${theme.foreground};`,
+    `--w-accent: ${theme.accent};`,
+    `--w-cursor: ${theme.cursor};`,
+    `--w-font-size: ${theme.fontSize}px;`,
+    ...SLOTS.map(slot => `--w-${slot}: ${theme.normal[slot]};`),
+    ...SLOTS.map(slot => `--w-bright-${slot}: ${theme.bright[slot]};`),
+  ]
+  return `/* Generated from ${theme.source ? `~/.warp/themes/${theme.source}` : 'the Fleet fallback palette'} — "${theme.name}". */\n:root {\n  ${lines.join('\n  ')}\n}\n`
+}
+
+module.exports = { readTheme, themeCss, parseThemeYaml, parseSettings, FALLBACK }

package/update.js

@@ -0,0 +1,183 @@
+'use strict'
+// Fleet checks npm for a newer published version and can install it on request.
+// The check is cached on disk and rate-limited, because a dashboard that phones a
+// registry on every page load is a dashboard nobody trusts. Nothing installs on
+// its own: the operator clicks.
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawn } = require('node:child_process')
+const { stateDir } = require('./paths')
+const pkg = require('./package.json')
+
+const REGISTRY = process.env.CLAUDE_FLEET_REGISTRY || 'https://registry.npmjs.org'
+const CHECK_EVERY = 6 * 60 * 60 * 1000
+const CHECK_TIMEOUT = 6000
+const INSTALL_TIMEOUT = 5 * 60 * 1000
+
+function parse(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(value || '').trim())
+  return match ? { nums: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] || null } : null
+}
+// Deliberately narrow: is `candidate` a release the operator should be offered?
+// A prerelease never qualifies, so a stray `1.2.0-beta.1` on the registry cannot
+// nag every install in the world.
+function isNewer(candidate, current) {
+  const a = parse(candidate), b = parse(current)
+  if (!a || !b || a.pre) return false
+  for (let i = 0; i < 3; i++) if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i]
+  return !!b.pre
+}
+// How this copy of Fleet got here decides whether it can replace itself.
+// A git checkout updates with `git pull`; only an npm install can be npm-installed over.
+function detectChannel(dir = __dirname) {
+  if (dir.split(path.sep).includes('node_modules')) return 'npm'
+  if (fs.existsSync(path.join(dir, '.git'))) return 'source'
+  return 'unknown'
+}
+
+async function fetchLatest(name) {
+  const url = `${REGISTRY}/${name.replace('/', '%2f')}/latest`
+  const response = await fetch(url, {
+    headers: { accept: 'application/vnd.npm.install-v1+json, application/json' },
+    signal: AbortSignal.timeout(CHECK_TIMEOUT),
+  })
+  if (!response.ok) throw new Error(`Registry answered ${response.status}`)
+  const data = await response.json()
+  if (!data || typeof data.version !== 'string') throw new Error('Registry returned no version')
+  return data.version
+}
+
+function npmInstall(spec) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('npm', ['install', '--global', '--no-fund', '--no-audit', spec], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // npm resolves its own prefix; inheriting a project's .npmrc here would be surprising.
+      env: { ...process.env, npm_config_yes: 'true' },
+    })
+    let stderr = ''
+    child.stdout.on('data', () => {})
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-4000) })
+    const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('The install took too long and was stopped.')) }, INSTALL_TIMEOUT)
+    timer.unref()
+    child.on('error', error => { clearTimeout(timer); reject(new Error(`Could not run npm: ${error.message}`)) })
+    child.on('close', code => {
+      clearTimeout(timer)
+      if (code === 0) return resolve()
+      // npm's own last words are far more useful than "exit 1".
+      const tail = stderr.trim().split('\n').filter(Boolean).slice(-4).join(' · ')
+      reject(new Error(tail ? `npm failed: ${tail}` : `npm exited with code ${code}.`))
+    })
+  })
+}
+
+class Updater {
+  constructor({
+    directory = stateDir(),
+    name = pkg.name,
+    version = pkg.version,
+    channel = detectChannel(),
+    latestVersion = fetchLatest,
+    install = npmInstall,
+    now = Date.now,
+  } = {}) {
+    this.name = name
+    this.version = version
+    this.channel = channel
+    this.latestVersion = latestVersion
+    this.install = install
+    this.now = now
+    this.file = path.join(directory, 'update.json')
+    this.state = 'idle' // idle | checking | installing | installed | failed
+    this.error = null
+    this.installed = null
+    this.checkedAt = 0
+    this.latest = null
+    this.inFlight = null
+    this.load()
+  }
+  load() {
+    try {
+      const data = JSON.parse(fs.readFileSync(this.file, 'utf8'))
+      if (!data || data.version !== 1) return
+      if (Number.isFinite(data.checkedAt)) this.checkedAt = data.checkedAt
+      // A cached answer about a version we are no longer running says nothing.
+      if (typeof data.latest === 'string' && data.for === this.version) this.latest = data.latest
+    } catch {}
+  }
+  persist() {
+    try {
+      fs.writeFileSync(this.file, JSON.stringify({ version: 1, checkedAt: this.checkedAt, latest: this.latest, for: this.version }), { mode: 0o600 })
+    } catch {}
+  }
+  status() {
+    const available = !!this.latest && isNewer(this.latest, this.version)
+    return {
+      name: this.name,
+      current: this.version,
+      latest: this.latest,
+      available,
+      // Only an npm install can npm-install over itself; a checkout is the user's to pull.
+      canInstall: available && this.channel === 'npm',
+      channel: this.channel,
+      checkedAt: this.checkedAt || null,
+      state: this.state,
+      error: this.error,
+      installed: this.installed,
+    }
+  }
+  // Cheap and idempotent: concurrent callers share one request, and a fresh answer
+  // is reused until it goes stale.
+  check({ force = false } = {}) {
+    if (this.inFlight) return this.inFlight
+    if (!force && this.now() - this.checkedAt < CHECK_EVERY) return Promise.resolve(this.status())
+    this.state = 'checking'
+    this.inFlight = (async () => {
+      try {
+        this.latest = await this.latestVersion(this.name)
+        this.checkedAt = this.now()
+        this.error = null
+        this.persist()
+      } catch (error) {
+        // A registry that is down or blocked is not worth an alarm; it just means
+        // we do not know yet. Keep whatever the last known answer was.
+        this.error = null
+        this.checkedAt = this.now()
+        this.persist()
+        if (process.env.CLAUDE_FLEET_DEBUG) console.error(`Update check failed: ${error.message}`)
+      } finally {
+        if (this.state === 'checking') this.state = 'idle'
+        this.inFlight = null
+      }
+      return this.status()
+    })()
+    return this.inFlight
+  }
+  async apply() {
+    const status = this.status()
+    if (this.state === 'installing') { const error = new Error('An update is already installing.'); error.status = 409; throw error }
+    if (!status.available) { const error = new Error('Fleet is already up to date.'); error.status = 409; throw error }
+    if (!status.canInstall) {
+      const error = new Error(this.channel === 'source'
+        ? 'This Fleet runs from a git checkout. Update it with `git pull`.'
+        : 'This Fleet was not installed with npm, so it cannot update itself.')
+      error.status = 409
+      throw error
+    }
+    this.state = 'installing'
+    this.error = null
+    try {
+      await this.install(`${this.name}@${this.latest}`)
+      this.state = 'installed'
+      this.installed = this.latest
+      return this.status()
+    } catch (error) {
+      this.state = 'failed'
+      this.error = error.message
+      const failure = new Error(error.message)
+      failure.status = 502
+      throw failure
+    }
+  }
+}
+
+module.exports = { Updater, isNewer, detectChannel, CHECK_EVERY }