remo-code-supervisor 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# remo-code-supervisor
+
+Local supervisor for Remo Code — manage and remote-launch `claude-code` sessions in your local repos from the Remo Code web UI.
+
+## Prerequisites
+
+- Windows 10/11 (other OSes can run the foreground mode but not the service)
+- [Bun](https://bun.sh) installed and on PATH
+- `claude` CLI installed and on PATH
+- `git` on PATH
+- A Remo Code account with an API key (https://app.remo-code.com → Settings → API Keys)
+
+## Install
+
+```powershell
+npx remo-code-supervisor install `
+  --api-key olx_xxx `
+  --roots "C:\Users\you\GitHub" `
+  --service-user ".\you" `
+  --service-password "<your windows password>"
+```
+
+This installs a Windows Service named `RemoCodeSupervisor` (via NSSM) that runs as your user, auto-starts at boot, and stays connected to the hub.
+
+If you don't supply `--service-user`/`--service-password`, the service is created but runs as LocalSystem — which **cannot read your SSH keys, `gh` auth, or `~/.config`**. Strongly prefer running as your own user.
+
+## Run in foreground (no service)
+
+```powershell
+npx remo-code-supervisor run
+```
+
+## Other commands
+
+```powershell
+npx remo-code-supervisor status      # service status
+npx remo-code-supervisor scan        # list discovered repos
+npx remo-code-supervisor uninstall   # remove the service
+```
+
+## Config file
+
+`%APPDATA%\remo-code\supervisor.json`
+
+```json
+{
+  "api_key": "olx_xxx",
+  "hub_url": "https://app.remo-code.com",
+  "roots": ["C:\\Users\\you\\GitHub"],
+  "max_concurrent": 1
+}
+```
+
+## Logs
+
+`%LOCALAPPDATA%\remo-code\logs\stdout.log` and `stderr.log` (rotating at 10MB).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "remo-code-supervisor",
+  "version": "0.1.0",
+  "description": "Local supervisor for Remo Code — manage and remote-launch claude-code sessions in your local repos from the web UI",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "remo-code-supervisor": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun --watch src/index.ts run",
+    "start": "bun src/index.ts run"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": ["claude", "claude-code", "remote", "supervisor", "remo-code"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finedesignz/remo-code.git",
+    "directory": "supervisor"
+  }
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { homedir, platform } from 'os'
+
+export interface SupervisorConfig {
+  hubUrl: string
+  apiKey: string
+  roots: string[]
+  maxConcurrent: number
+}
+
+function defaultConfigDir(): string {
+  if (platform() === 'win32') {
+    const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming')
+    return join(appData, 'remo-code')
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(xdg, 'remo-code')
+}
+
+export const CONFIG_DIR = defaultConfigDir()
+export const CONFIG_PATH = join(CONFIG_DIR, 'supervisor.json')
+const DEFAULT_HUB_URL = 'https://app.remo-code.com'
+
+export function loadConfig(): SupervisorConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    throw new Error(`Supervisor not configured. Run: npx remo-code-supervisor install --api-key <olx_...>`)
+  }
+  const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))
+  if (!raw.api_key) throw new Error('config missing api_key')
+  return {
+    hubUrl: raw.hub_url || DEFAULT_HUB_URL,
+    apiKey: raw.api_key,
+    roots: raw.roots || [],
+    maxConcurrent: raw.max_concurrent || 1,
+  }
+}
+
+export function saveConfig(cfg: Partial<SupervisorConfig> & { apiKey: string }) {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  const existing = existsSync(CONFIG_PATH) ? JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')) : {}
+  const merged = {
+    ...existing,
+    api_key: cfg.apiKey,
+    hub_url: cfg.hubUrl || existing.hub_url || DEFAULT_HUB_URL,
+    roots: cfg.roots || existing.roots || [],
+    max_concurrent: cfg.maxConcurrent || existing.max_concurrent || 1,
+  }
+  writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2), 'utf-8')
+}
+
+export function parseRoots(input: string | undefined): string[] {
+  if (!input) return []
+  return input.split(/[,;]/).map((s) => s.trim()).filter(Boolean)
+}

package/src/git-ops.ts

@@ -0,0 +1,85 @@
+import { existsSync, writeFileSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+async function runGit(args: string[], cwd?: string, timeoutMs = 60_000): Promise<{ stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(['git', ...args], {
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      try { proc.kill() } catch {}
+      reject(new Error(`git timed out: ${args.join(' ')}`))
+    }, timeoutMs)
+  })
+  try {
+    const code = await Promise.race([proc.exited, timeout])
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    if (code !== 0) throw new Error(stderr.trim() || `git exited ${code}`)
+    return { stdout, stderr, code: code as number }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+export async function isDirty(repoPath: string): Promise<boolean> {
+  try {
+    const { stdout } = await runGit(['status', '--porcelain'], repoPath, 10_000)
+    return stdout.trim().length > 0
+  } catch { return false }
+}
+
+export async function currentBranch(repoPath: string): Promise<string | null> {
+  try {
+    const { stdout } = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], repoPath, 10_000)
+    return stdout.trim() || null
+  } catch { return null }
+}
+
+export interface GitOpResult {
+  ok: boolean
+  error?: string
+  data?: any
+}
+
+export async function cloneRepo(cloneUrl: string, targetPath: string): Promise<GitOpResult> {
+  try {
+    if (existsSync(targetPath)) return { ok: false, error: `target already exists: ${targetPath}` }
+    await runGit(['clone', '--no-recurse-submodules', cloneUrl, targetPath], undefined, 600_000)
+    const cfgPath = join(targetPath, '.git', 'config')
+    if (existsSync(cfgPath)) {
+      const raw = readFileSync(cfgPath, 'utf-8')
+      const stripped = raw.replace(/https:\/\/[^@\s]+@github\.com/g, 'https://github.com')
+      writeFileSync(cfgPath, stripped, 'utf-8')
+    }
+    return { ok: true, data: { path: targetPath } }
+  } catch (err: any) {
+    return { ok: false, error: err.message }
+  }
+}
+
+export async function pullRepo(repoPath: string, branch: string, tokenizedUrl: string): Promise<GitOpResult> {
+  try {
+    if (await isDirty(repoPath)) return { ok: false, error: 'worktree is dirty; refusing to pull' }
+    await runGit(['fetch', tokenizedUrl, branch], repoPath, 120_000)
+    await runGit(['checkout', branch], repoPath, 60_000)
+    await runGit(['merge', '--ff-only', 'FETCH_HEAD'], repoPath, 60_000)
+    return { ok: true }
+  } catch (err: any) {
+    return { ok: false, error: err.message }
+  }
+}
+
+export async function checkoutBranch(repoPath: string, branch: string, create: boolean): Promise<GitOpResult> {
+  try {
+    if (await isDirty(repoPath)) return { ok: false, error: 'worktree is dirty; refusing to switch branches' }
+    if (create) await runGit(['checkout', '-b', branch], repoPath, 30_000)
+    else await runGit(['checkout', branch], repoPath, 30_000)
+    return { ok: true }
+  } catch (err: any) {
+    return { ok: false, error: err.message }
+  }
+}

package/src/hub-client.ts

@@ -0,0 +1,195 @@
+import { hostname, platform, release } from 'os'
+import { scanAll } from './repo-scanner'
+import { cloneRepo, pullRepo, checkoutBranch } from './git-ops'
+import { ProcessManager, type ProcState } from './process-manager'
+import type { SupervisorConfig } from './config'
+
+const VERSION = '0.1.0'
+
+type OutboundMsg =
+  | { type: 'auth'; api_key: string; project_dir: string; hostname: string; role: 'supervisor' }
+  | { type: 'supervisor.hello'; version: string; os: string; hostname: string; roots: string[]; capabilities: string[] }
+  | { type: 'supervisor.state'; state: ProcState; run_id?: string | null; repo_path?: string | null; pid?: number | null; restart_count?: number; last_exit?: any }
+  | { type: 'supervisor.log'; level: string; message: string; run_id?: string; ts?: string }
+  | { type: 'repo.scan_result'; req_id: string; repos: any[] }
+  | { type: 'repo.op_result'; req_id: string; op: string; ok: boolean; error?: string; data?: any }
+  | { type: 'repo.clone_progress'; req_id: string; stage: string; percent?: number }
+  | { type: 'pong' }
+
+export class SupervisorClient {
+  private ws: WebSocket | null = null
+  private cfg: SupervisorConfig
+  private authenticated = false
+  private reconnectAttempts = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private pm: ProcessManager
+
+  constructor(cfg: SupervisorConfig) {
+    this.cfg = cfg
+    this.pm = new ProcessManager({
+      onStateChange: (state, info) => {
+        this.send({
+          type: 'supervisor.state',
+          state,
+          run_id: info.runId ?? null,
+          repo_path: info.repoPath ?? null,
+          pid: info.pid ?? null,
+          restart_count: info.restartCount ?? 0,
+          last_exit: info.lastExit,
+        })
+      },
+      onLog: (level, message, runId) => {
+        this.log(level, message, runId)
+      },
+    })
+  }
+
+  connect() {
+    const wsUrl = this.cfg.hubUrl.replace('https://', 'wss://').replace('http://', 'ws://') + '/ws/agent'
+    this.log('info', `connecting to ${wsUrl}`)
+    try {
+      this.ws = new WebSocket(wsUrl)
+    } catch (err: any) {
+      this.log('error', `WebSocket construct failed: ${err.message}`)
+      this.scheduleReconnect()
+      return
+    }
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0
+      this.send({
+        type: 'auth',
+        api_key: this.cfg.apiKey,
+        project_dir: '__supervisor__',
+        hostname: hostname(),
+        role: 'supervisor',
+      })
+    }
+    this.ws.onmessage = (event) => {
+      let msg: any
+      try { msg = JSON.parse(typeof event.data === 'string' ? event.data : new TextDecoder().decode(event.data as any)) } catch { return }
+      this.handleMessage(msg)
+    }
+    this.ws.onclose = () => {
+      this.authenticated = false
+      this.log('warn', 'WebSocket closed')
+      this.scheduleReconnect()
+    }
+    this.ws.onerror = () => {
+      // onclose will follow
+    }
+  }
+
+  private scheduleReconnect() {
+    if (this.reconnectTimer) return
+    const delay = Math.min(60_000, 1000 * Math.pow(2, Math.min(this.reconnectAttempts, 6)))
+    this.reconnectAttempts++
+    this.log('info', `reconnecting in ${delay}ms`)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.connect()
+    }, delay)
+  }
+
+  private send(msg: OutboundMsg) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      try { this.ws.send(JSON.stringify(msg)) } catch {}
+    }
+  }
+
+  private log(level: string, message: string, runId?: string) {
+    console.log(`[${level}] ${message}`)
+    this.send({ type: 'supervisor.log', level, message, run_id: runId, ts: new Date().toISOString() })
+  }
+
+  private async handleMessage(msg: any) {
+    if (msg.type === 'ping') { this.send({ type: 'pong' }); return }
+    if (msg.type === 'auth_ok') {
+      this.authenticated = true
+      this.log('info', 'authenticated; sending hello')
+      this.send({
+        type: 'supervisor.hello',
+        version: VERSION,
+        os: `${platform()} ${release()}`,
+        hostname: hostname(),
+        roots: this.cfg.roots,
+        capabilities: ['supervisor', 'agent'],
+      })
+      return
+    }
+    if (msg.type === 'auth_error') {
+      this.log('error', `auth failed: ${msg.error}`)
+      try { this.ws?.close() } catch {}
+      return
+    }
+
+    if (!this.authenticated) return
+
+    switch (msg.type) {
+      case 'repo.scan': await this.onRepoScan(msg); break
+      case 'repo.clone': await this.onRepoClone(msg); break
+      case 'repo.pull': await this.onRepoPull(msg); break
+      case 'repo.branch_checkout': await this.onBranchCheckout(msg); break
+      case 'session.start': await this.onSessionStart(msg); break
+      case 'session.stop': await this.onSessionStop(msg); break
+      case 'session.status': this.onSessionStatus(msg); break
+      default:
+        // unknown
+        break
+    }
+  }
+
+  private async onRepoScan(msg: { req_id: string }) {
+    const repos = scanAll(this.cfg.roots)
+    this.send({ type: 'repo.scan_result', req_id: msg.req_id, repos })
+  }
+
+  private async onRepoClone(msg: { req_id: string; clone_url: string; target_path: string; repo_full_name: string }) {
+    this.send({ type: 'repo.clone_progress', req_id: msg.req_id, stage: 'cloning' })
+    const res = await cloneRepo(msg.clone_url, msg.target_path)
+    this.send({ type: 'repo.op_result', req_id: msg.req_id, op: 'clone', ok: res.ok, error: res.error, data: res.data })
+  }
+
+  private async onRepoPull(msg: { req_id: string; repo_path: string; branch: string; clone_url: string }) {
+    const res = await pullRepo(msg.repo_path, msg.branch, msg.clone_url)
+    this.send({ type: 'repo.op_result', req_id: msg.req_id, op: 'pull', ok: res.ok, error: res.error })
+  }
+
+  private async onBranchCheckout(msg: { req_id: string; repo_path: string; branch: string; create: boolean }) {
+    const res = await checkoutBranch(msg.repo_path, msg.branch, msg.create)
+    this.send({ type: 'repo.op_result', req_id: msg.req_id, op: 'checkout', ok: res.ok, error: res.error })
+  }
+
+  private async onSessionStart(msg: { run_id: string; repo_path: string; branch?: string; pull?: boolean; initial_prompt?: string; api_key: string; hub_url: string }) {
+    // pull/checkout pre-flight (best-effort)
+    if (msg.pull && msg.branch) {
+      this.log('info', `pre-flight: checkout+pull not implemented w/o tokenized url; skipping`, msg.run_id)
+    }
+    if (msg.branch) {
+      const checkout = await checkoutBranch(msg.repo_path, msg.branch, false)
+      if (!checkout.ok) {
+        this.log('warn', `checkout failed: ${checkout.error}`, msg.run_id)
+      }
+    }
+    await this.pm.start({
+      runId: msg.run_id,
+      repoPath: msg.repo_path,
+      branch: msg.branch ?? null,
+      initialPrompt: msg.initial_prompt ?? null,
+      apiKey: this.cfg.apiKey,
+      hubUrl: this.cfg.hubUrl,
+    })
+  }
+
+  private async onSessionStop(msg: { run_id: string; reason: string }) {
+    await this.pm.stop(msg.reason)
+  }
+
+  private onSessionStatus(msg: { req_id: string }) {
+    this.send({
+      type: 'supervisor.state',
+      state: this.pm.currentState,
+      run_id: this.pm.currentRunId,
+      repo_path: this.pm.currentRepoPath,
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+import { loadConfig, saveConfig, parseRoots, CONFIG_PATH } from './config'
+import { SupervisorClient } from './hub-client'
+import { installService, uninstallService, statusService, SERVICE_NAME } from './nssm-installer'
+import { scanAll } from './repo-scanner'
+
+const VERSION = '0.1.0'
+
+function parseArgs(argv: string[]): { cmd: string; flags: Record<string, string | boolean> } {
+  const cmd = argv[0] || 'help'
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      if (a.includes('=')) {
+        const [k, ...v] = a.split('=')
+        flags[k.slice(2)] = v.join('=')
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[a.slice(2)] = argv[++i]
+      } else {
+        flags[a.slice(2)] = true
+      }
+    }
+  }
+  return { cmd, flags }
+}
+
+function printHelp() {
+  console.log(`remo-code-supervisor v${VERSION}
+
+Usage:
+  npx remo-code-supervisor install --api-key <olx_...> [--roots <paths>] [--hub-url <url>] [--service-user <user> --service-password <pwd>]
+  npx remo-code-supervisor uninstall
+  npx remo-code-supervisor run                     # foreground (used by the Windows service)
+  npx remo-code-supervisor status
+  npx remo-code-supervisor scan                    # one-shot: list discovered repos
+
+Notes:
+  - --roots is comma- or semicolon-separated; e.g. "C:\\Users\\artic\\GitHub"
+  - On Windows, install creates an NSSM-backed service that auto-starts at boot.
+    Provide --service-user (e.g. .\\artic) and --service-password to run the
+    service as your own Windows user so SSH keys, gh auth, and ~/.config remain reachable.
+  - Config file: ${CONFIG_PATH}
+`)
+}
+
+async function main() {
+  const { cmd, flags } = parseArgs(process.argv.slice(2))
+
+  if (cmd === 'help' || cmd === '-h' || cmd === '--help') {
+    printHelp(); return
+  }
+
+  if (cmd === 'install') {
+    const apiKey = (flags['api-key'] as string) || ''
+    if (!apiKey) { console.error('error: --api-key required'); process.exit(1) }
+    const hubUrl = (flags['hub-url'] as string) || undefined
+    const roots = parseRoots(flags['roots'] as string | undefined)
+    saveConfig({ apiKey, hubUrl, roots })
+    console.log(`[install] config saved to ${CONFIG_PATH}`)
+    const serviceUser = flags['service-user'] as string | undefined
+    const servicePassword = flags['service-password'] as string | undefined
+    try {
+      await installService({ apiKey, hubUrl, roots, serviceUser, servicePassword })
+    } catch (err: any) {
+      console.error(`[install] ${err.message}`)
+      console.error(`[install] You can still run the supervisor manually with: npx remo-code-supervisor run`)
+      process.exit(2)
+    }
+    return
+  }
+
+  if (cmd === 'uninstall') {
+    await uninstallService()
+    return
+  }
+
+  if (cmd === 'status') {
+    const s = await statusService().catch(() => 'unknown')
+    console.log(`service: ${s}`)
+    console.log(`config:  ${CONFIG_PATH}`)
+    return
+  }
+
+  if (cmd === 'scan') {
+    const cfg = loadConfig()
+    const repos = scanAll(cfg.roots)
+    console.log(JSON.stringify(repos, null, 2))
+    return
+  }
+
+  if (cmd === 'run') {
+    const cfg = loadConfig()
+    console.log(`[run] remo-code-supervisor v${VERSION}`)
+    console.log(`[run] hub=${cfg.hubUrl} roots=${cfg.roots.length}`)
+    const client = new SupervisorClient(cfg)
+    client.connect()
+    process.on('SIGINT', () => { console.log('shutting down'); process.exit(0) })
+    process.on('SIGTERM', () => { console.log('shutting down'); process.exit(0) })
+    // Keep alive
+    await new Promise(() => {})
+    return
+  }
+
+  console.error(`unknown command: ${cmd}`)
+  printHelp()
+  process.exit(1)
+}
+
+main().catch((err) => {
+  console.error('fatal:', err.message)
+  process.exit(1)
+})

package/src/nssm-installer.ts

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { homedir, platform } from 'os'
+
+export const NSSM_DIR = join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'remo-code')
+export const LOG_DIR = join(NSSM_DIR, 'logs')
+export const NSSM_PATH = join(NSSM_DIR, 'nssm.exe')
+export const SERVICE_NAME = 'RemoCodeSupervisor'
+
+const NSSM_DOWNLOAD = 'https://nssm.cc/release/nssm-2.24.zip'
+
+async function nssm(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn([NSSM_PATH, ...args], { stdout: 'pipe', stderr: 'pipe' })
+  const code = await proc.exited
+  const stdout = await new Response(proc.stdout).text()
+  const stderr = await new Response(proc.stderr).text()
+  return { code: code as number, stdout, stderr }
+}
+
+export async function ensureNssm(): Promise<boolean> {
+  if (existsSync(NSSM_PATH)) return true
+  mkdirSync(NSSM_DIR, { recursive: true })
+  mkdirSync(LOG_DIR, { recursive: true })
+  console.log(`[install] NSSM not found at ${NSSM_PATH}`)
+  console.log(`[install] Please download NSSM from ${NSSM_DOWNLOAD}, extract nssm.exe (win64 version), and place it at ${NSSM_PATH}`)
+  console.log(`[install] Then re-run: npx remo-code-supervisor install`)
+  return false
+}
+
+function bunPath(): string {
+  // Best-effort: resolve from Bun.argv0 or PATH
+  return process.execPath
+}
+
+function entryScriptPath(): string {
+  // For `npx remo-code-supervisor install`, the script we want the service to run is this same package's run command.
+  // We resolve the supervisor's own bin script by walking up from process.argv[1].
+  // Fallback: just shell out to `npx` style.
+  return process.argv[1] || ''
+}
+
+export interface InstallOptions {
+  apiKey: string
+  hubUrl?: string
+  roots: string[]
+  serviceUser?: string
+  servicePassword?: string
+}
+
+export async function installService(opts: InstallOptions): Promise<void> {
+  if (platform() !== 'win32') {
+    throw new Error('Service install currently supports Windows only. Use `remo-code-supervisor run` to run in foreground on other OSes.')
+  }
+  const ok = await ensureNssm()
+  if (!ok) throw new Error('NSSM not installed')
+
+  mkdirSync(LOG_DIR, { recursive: true })
+
+  const bun = bunPath()
+  const entry = entryScriptPath()
+
+  // Remove existing service first (idempotent)
+  await nssm(['stop', SERVICE_NAME]).catch(() => {})
+  await nssm(['remove', SERVICE_NAME, 'confirm']).catch(() => {})
+
+  let r = await nssm(['install', SERVICE_NAME, bun, entry, 'run'])
+  if (r.code !== 0) throw new Error(`nssm install failed: ${r.stderr || r.stdout}`)
+
+  await nssm(['set', SERVICE_NAME, 'DisplayName', 'Remo Code Supervisor'])
+  await nssm(['set', SERVICE_NAME, 'Description', 'Remote-control supervisor for Claude Code sessions'])
+  await nssm(['set', SERVICE_NAME, 'Start', 'SERVICE_AUTO_START'])
+  await nssm(['set', SERVICE_NAME, 'AppStdout', join(LOG_DIR, 'stdout.log')])
+  await nssm(['set', SERVICE_NAME, 'AppStderr', join(LOG_DIR, 'stderr.log')])
+  await nssm(['set', SERVICE_NAME, 'AppRotateFiles', '1'])
+  await nssm(['set', SERVICE_NAME, 'AppRotateBytes', '10485760'])
+
+  if (opts.serviceUser && opts.servicePassword) {
+    const r2 = await nssm(['set', SERVICE_NAME, 'ObjectName', opts.serviceUser, opts.servicePassword])
+    if (r2.code !== 0) throw new Error(`nssm set ObjectName failed: ${r2.stderr || r2.stdout}`)
+  }
+
+  const r3 = await nssm(['start', SERVICE_NAME])
+  if (r3.code !== 0) throw new Error(`nssm start failed: ${r3.stderr || r3.stdout}`)
+  console.log(`[install] Service ${SERVICE_NAME} installed and started.`)
+  console.log(`[install] Logs: ${LOG_DIR}`)
+}
+
+export async function uninstallService() {
+  if (platform() !== 'win32') return
+  if (!existsSync(NSSM_PATH)) {
+    console.log('[uninstall] nssm not present; nothing to do')
+    return
+  }
+  await nssm(['stop', SERVICE_NAME]).catch(() => {})
+  await nssm(['remove', SERVICE_NAME, 'confirm']).catch(() => {})
+  console.log(`[uninstall] Service ${SERVICE_NAME} removed.`)
+}
+
+export async function statusService(): Promise<string> {
+  if (platform() !== 'win32') return 'not-windows'
+  if (!existsSync(NSSM_PATH)) return 'nssm-missing'
+  const r = await nssm(['status', SERVICE_NAME])
+  return r.stdout.trim() || 'unknown'
+}

package/src/process-manager.ts

@@ -0,0 +1,189 @@
+import type { Subprocess } from 'bun'
+
+export type ProcState = 'idle' | 'starting' | 'running' | 'stopping' | 'crashed' | 'stopped'
+
+export interface RunSpec {
+  runId: string
+  repoPath: string
+  branch: string | null
+  initialPrompt: string | null
+  apiKey: string
+  hubUrl: string
+}
+
+export interface ProcessManagerCallbacks {
+  onStateChange: (state: ProcState, info: { runId?: string; repoPath?: string; pid?: number; restartCount?: number; lastExit?: { code: number | null; reason: string; stderrTail?: string } }) => void
+  onLog: (level: 'info' | 'warn' | 'error', message: string, runId?: string) => void
+}
+
+const BACKOFF_SCHEDULE = [1000, 2000, 4000, 8000, 16000, 30000]
+const CIRCUIT_WINDOW_MS = 10 * 60_000
+const CIRCUIT_THRESHOLD = 5
+
+export class ProcessManager {
+  private state: ProcState = 'idle'
+  private proc: Subprocess | null = null
+  private currentRun: RunSpec | null = null
+  private restartCount = 0
+  private recentCrashes: number[] = []
+  private restartTimer: ReturnType<typeof setTimeout> | null = null
+  private userStop = false
+  private cb: ProcessManagerCallbacks
+  private stderrTail: string[] = []
+
+  constructor(cb: ProcessManagerCallbacks) {
+    this.cb = cb
+  }
+
+  get currentState() { return this.state }
+  get currentRunId() { return this.currentRun?.runId ?? null }
+  get currentRepoPath() { return this.currentRun?.repoPath ?? null }
+
+  async start(spec: RunSpec) {
+    if (this.state !== 'idle') {
+      this.cb.onLog('warn', `Refusing start: current state=${this.state}`, spec.runId)
+      return
+    }
+    this.currentRun = spec
+    this.restartCount = 0
+    this.recentCrashes = []
+    this.userStop = false
+    this.spawnInner()
+  }
+
+  private spawnInner() {
+    if (!this.currentRun) return
+    const spec = this.currentRun
+
+    this.setState('starting', { runId: spec.runId, repoPath: spec.repoPath, restartCount: this.restartCount })
+
+    // Find the claude binary the same way claude-remote-agent does:
+    // We spawn 'claude' directly (assumed in PATH on user's machine).
+    // Claude's stream-json IO is handled by sending an initial user message via stdin.
+    this.stderrTail = []
+    const cmd = ['claude', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions']
+    const env = { ...process.env }
+    delete (env as any).ANTHROPIC_API_KEY
+
+    try {
+      this.proc = Bun.spawn(cmd, {
+        cwd: spec.repoPath,
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env,
+      })
+    } catch (err: any) {
+      this.cb.onLog('error', `failed to spawn claude: ${err.message}`, spec.runId)
+      this.setState('crashed', { runId: spec.runId, repoPath: spec.repoPath, lastExit: { code: null, reason: `spawn_error: ${err.message}` } })
+      this.scheduleRestart(null, 'spawn_error')
+      return
+    }
+
+    const pid = this.proc.pid
+    this.cb.onLog('info', `claude spawned pid=${pid} in ${spec.repoPath}`, spec.runId)
+    this.setState('running', { runId: spec.runId, repoPath: spec.repoPath, pid, restartCount: this.restartCount })
+
+    // If initial prompt provided, send it once the process is ready.
+    // We treat "ready" as 3s post-spawn (matches agent pattern).
+    if (spec.initialPrompt) {
+      setTimeout(() => this.injectInitialPrompt(spec.initialPrompt!), 4000)
+    }
+
+    this.consumeStderr()
+
+    this.proc.exited.then((code) => {
+      const reason = this.userStop ? 'user' : code === 0 ? 'clean' : 'crash'
+      const tail = this.stderrTail.slice(-40).join('\n')
+      this.cb.onLog(reason === 'crash' ? 'error' : 'info', `claude exited code=${code} reason=${reason}`, spec.runId)
+
+      if (this.userStop) {
+        this.setState('idle', { runId: spec.runId, lastExit: { code: code ?? null, reason, stderrTail: tail } })
+        this.currentRun = null
+        return
+      }
+
+      if (reason === 'clean') {
+        this.setState('idle', { runId: spec.runId, lastExit: { code: code ?? null, reason, stderrTail: tail } })
+        this.currentRun = null
+        return
+      }
+
+      // crash
+      this.recentCrashes.push(Date.now())
+      this.recentCrashes = this.recentCrashes.filter((t) => Date.now() - t < CIRCUIT_WINDOW_MS)
+      if (this.recentCrashes.length >= CIRCUIT_THRESHOLD) {
+        this.cb.onLog('error', `circuit breaker open: ${this.recentCrashes.length} crashes in ${CIRCUIT_WINDOW_MS / 60_000}min — stopping`, spec.runId)
+        this.setState('stopped', { runId: spec.runId, lastExit: { code: code ?? null, reason: 'circuit_open', stderrTail: tail } })
+        this.currentRun = null
+        return
+      }
+      this.scheduleRestart(code ?? null, 'crash', tail)
+    })
+  }
+
+  private scheduleRestart(exitCode: number | null, reason: string, stderrTail = '') {
+    if (!this.currentRun) return
+    const delay = BACKOFF_SCHEDULE[Math.min(this.restartCount, BACKOFF_SCHEDULE.length - 1)]
+    this.restartCount++
+    this.cb.onLog('warn', `restarting in ${delay}ms (attempt ${this.restartCount})`, this.currentRun.runId)
+    this.setState('crashed', { runId: this.currentRun.runId, lastExit: { code: exitCode, reason, stderrTail } })
+    this.restartTimer = setTimeout(() => {
+      this.restartTimer = null
+      if (!this.currentRun) return
+      this.spawnInner()
+    }, delay)
+  }
+
+  private injectInitialPrompt(prompt: string) {
+    if (!this.proc?.stdin) return
+    const msg = JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } })
+    try {
+      this.proc.stdin.write(msg + '\n')
+      this.proc.stdin.flush?.()
+      this.cb.onLog('info', `injected initial prompt (${prompt.length} chars)`, this.currentRun?.runId)
+    } catch (err: any) {
+      this.cb.onLog('warn', `failed to inject initial prompt: ${err.message}`, this.currentRun?.runId)
+    }
+  }
+
+  async stop(reason: string) {
+    if (this.state === 'idle') return
+    this.userStop = true
+    if (this.restartTimer) { clearTimeout(this.restartTimer); this.restartTimer = null }
+    this.setState('stopping', { runId: this.currentRun?.runId })
+    if (this.proc) {
+      try { this.proc.kill('SIGINT') } catch {}
+      // SIGKILL after 10s
+      setTimeout(() => {
+        if (this.proc) {
+          try { this.proc.kill('SIGKILL') } catch {}
+        }
+      }, 10_000)
+    }
+  }
+
+  private setState(state: ProcState, info: any = {}) {
+    this.state = state
+    this.cb.onStateChange(state, { restartCount: this.restartCount, ...info })
+  }
+
+  private async consumeStderr() {
+    if (!this.proc?.stderr) return
+    try {
+      const reader = this.proc.stderr.getReader()
+      const decoder = new TextDecoder()
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        const text = decoder.decode(value, { stream: true })
+        for (const line of text.split('\n')) {
+          if (line.trim()) {
+            this.stderrTail.push(line)
+            if (this.stderrTail.length > 200) this.stderrTail.shift()
+          }
+        }
+      }
+    } catch {}
+  }
+}

package/src/repo-scanner.ts

@@ -0,0 +1,94 @@
+import { readdirSync, statSync, existsSync, readFileSync } from 'fs'
+import { join, basename } from 'path'
+
+export interface ScannedRepo {
+  path: string
+  name: string
+  remote: string | null
+  branch: string | null
+  dirty: boolean
+  last_commit: string | null
+}
+
+function isDir(p: string): boolean {
+  try { return statSync(p).isDirectory() } catch { return false }
+}
+
+function readRemote(repoPath: string): string | null {
+  try {
+    const cfgPath = join(repoPath, '.git', 'config')
+    if (!existsSync(cfgPath)) return null
+    const cfg = readFileSync(cfgPath, 'utf-8')
+    const m = cfg.match(/\[remote "origin"\][^[]*url\s*=\s*(.+)/m)
+    return m ? m[1].trim() : null
+  } catch { return null }
+}
+
+function readBranch(repoPath: string): string | null {
+  try {
+    const headPath = join(repoPath, '.git', 'HEAD')
+    if (!existsSync(headPath)) return null
+    const head = readFileSync(headPath, 'utf-8').trim()
+    if (head.startsWith('ref: refs/heads/')) return head.slice('ref: refs/heads/'.length)
+    return head.slice(0, 12)
+  } catch { return null }
+}
+
+function gitSync(args: string[], cwd: string, timeoutMs = 5000): string | null {
+  try {
+    const result = Bun.spawnSync(['git', ...args], {
+      cwd,
+      stdout: 'pipe',
+      stderr: 'ignore',
+      timeout: timeoutMs,
+    })
+    if (result.exitCode !== 0) return null
+    return new TextDecoder().decode(result.stdout)
+  } catch { return null }
+}
+
+function isDirty(repoPath: string): boolean {
+  const out = gitSync(['status', '--porcelain'], repoPath)
+  if (out == null) return false
+  return out.trim().length > 0
+}
+
+function lastCommit(repoPath: string): string | null {
+  const out = gitSync(['log', '-1', '--pretty=%h%x09%s'], repoPath)
+  return out?.trim() || null
+}
+
+export function scanRoot(root: string): ScannedRepo[] {
+  const out: ScannedRepo[] = []
+  if (!isDir(root)) return out
+  let entries: string[] = []
+  try { entries = readdirSync(root) } catch { return out }
+  for (const entry of entries) {
+    if (entry.startsWith('.')) continue
+    const path = join(root, entry)
+    if (!isDir(path)) continue
+    if (!existsSync(join(path, '.git'))) continue
+    out.push({
+      path: path.replace(/\\/g, '/'),
+      name: basename(path),
+      remote: readRemote(path),
+      branch: readBranch(path),
+      dirty: isDirty(path),
+      last_commit: lastCommit(path),
+    })
+  }
+  return out
+}
+
+export function scanAll(roots: string[]): ScannedRepo[] {
+  const all: ScannedRepo[] = []
+  const seen = new Set<string>()
+  for (const r of roots) {
+    for (const repo of scanRoot(r)) {
+      if (seen.has(repo.path)) continue
+      seen.add(repo.path)
+      all.push(repo)
+    }
+  }
+  return all.sort((a, b) => a.name.localeCompare(b.name))
+}