@recombine-ai/bosun 0.16.2 → 0.17.1

package/README.md

@@ -26,6 +26,30 @@ In your Recombine Agent folder
 
 Bosun automatically chooses free local ports when the default ports are already in use, so you can run it from multiple agent repos at the same time.
 
+## Git mode (optional)
+
+Git mode keeps a personal branch up to date with a release branch. It adds **Discard**, **Save**, and **Prepare for release** controls. It can pull, merge, commit, stash, and push project changes.
+
+Add these settings to the project `.env` where you run `bosun`:
+
+```dotenv
+BOSUN_GIT_MODE=true
+BOSUN_CURRENT_BRANCH=next-release
+BOSUN_PERSONAL_BRANCH=your-name/next-release
+# Optional; the default is 10.
+BOSUN_GIT_ACTIVATION_IDLE_MINUTES=10
+```
+
+Before you start Bosun:
+
+- Use macOS, Linux, or WSL. Native Windows is not supported.
+- Run `bosun` from the root of the primary Git checkout, with the personal branch checked out.
+- Create both branches locally. They must track different branches on the same remote. The remote must use one URL for both fetch and push.
+- Do not use a linked worktree or a repository with submodules. The release branch must not be open in another worktree.
+- Finish or abort any merge or rebase.
+
+The first Bosun page that you open after startup refreshes the repository. **Save** commits all project changes to the personal branch and pushes them. **Discard** moves tracked and non-ignored untracked changes to the Git stash. **Prepare for release** publishes the result to both upstream branches in one atomic push. If pulled files change, Bosun installs locked dependencies without project scripts, restarts, and reloads its pages.
+
 ## Roleplay context and variants
 
 Bosun keeps roleplay conversation state separately from agent context:

package/bin/bosun.js

@@ -6,6 +6,14 @@ import { existsSync, readFileSync } from 'fs'
 import { createServer } from 'net'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
+import {
+	cleanupGitModeRuntime,
+	createBosunChildEnvironment,
+	GIT_ACTIVATION_RESTART_EXIT_CODE,
+	prepareGitModeRuntime,
+	registerGitModeChildProcess,
+	unregisterGitModeChildProcess
+} from './git-mode.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -29,6 +37,11 @@ let backendProcess = null
 let frontendProcess = null
 
 let isShuttingDown = false
+/** @type {Promise<void> | null} */
+let shutdownPromise = null
+
+/** @type {WeakMap<ChildProcess, Promise<{ code: number | null, signal: NodeJS.Signals | null }>>} */
+const childExitPromises = new WeakMap()
 
 const BACKEND_RESTART_EXIT_CODE = 75
 
@@ -36,10 +49,13 @@ const envPath = resolve(process.cwd(), '.env')
 const envConfig = existsSync(envPath) ? dotenv.parse(readFileSync(envPath)) : {}
 const baseEnv = { ...process.env, ...envConfig }
 
+/** @type {import('./git-mode.js').GitModeRuntime | null} */
+let gitModeRuntime = null
+
 /** @type {{ frontend: number, ws: number, trpc: number } | null} */
 let ports = null
 
-main()
+void main()
 
 /* ========= Implementation =========== */
 
@@ -47,6 +63,7 @@ async function main() {
 	// Initial start
 	try {
 		checkBosunLibVersionMatch()
+		gitModeRuntime = prepareGitModeRuntime({ cwd: process.cwd(), projectEnv: envConfig })
 		ports = await selectPorts()
 
 		// Start backend
@@ -63,25 +80,31 @@ async function main() {
 		console.log(`WebSocket: ws://localhost:${ports.ws}`)
 		console.log(`tRPC: http://localhost:${ports.trpc}`)
 	} catch (error) {
-		console.error('❌ Error:', String(error))
-		process.exit(1)
+		console.error(
+			'❌ Bosun could not start:',
+			error instanceof Error ? error.message : String(error)
+		)
+		await shutdown(1)
 	}
 }
 
 function startBackend() {
 	if (!ports) throw new Error('Ports were not selected before starting the backend.')
 
-	const tsxBin = process.platform === 'win32' ? 'tsx.cmd' : 'tsx'
-	const tsxPath = resolve(rootDir, 'node_modules', '.bin', tsxBin)
 	const serverPath = resolve(rootDir, 'src', 'backend', 'server.ts')
-	const command = process.platform === 'win32' ? tsxPath : process.execPath
-	const commandArgs = process.platform === 'win32' ? [serverPath] : [tsxPath, serverPath]
-
-	const child = spawn(command, commandArgs, {
+	// The tsx CLI launches the actual TypeScript program in a grandchild. Run its loader in this
+	// child instead so SIGTERM reaches the server that owns the write/command drains.
+	const tsxLoaderUrl = import.meta.resolve('tsx')
+	const childEnv = createBosunChildEnvironment(
+		baseEnv,
+		gitModeRuntime,
+		`http://localhost:${ports.frontend}`
+	)
+	const child = spawn(process.execPath, ['--import', tsxLoaderUrl, serverPath], {
 		cwd: process.cwd(),
 		stdio: 'inherit',
 		env: {
-			...baseEnv,
+			...childEnv,
 			BOSUN_WS_PORT: String(ports.ws),
 			BOSUN_TRPC_PORT: String(ports.trpc),
 			PUBLIC_WS_HOST: `ws://localhost:${ports.ws}`,
@@ -90,8 +113,9 @@ function startBackend() {
 			PUBLIC_TRPC_PORT: String(ports.trpc),
 			BOSUN_NPX_RUN: 'true'
 		},
-		shell: process.platform === 'win32'
+		shell: false
 	})
+	registerChildOrStop(child, 'backend')
 	watchChild(child, 'backend')
 	return child
 }
@@ -101,12 +125,17 @@ function startFrontend() {
 
 	const frontPath = resolve(rootDir, 'build', 'index.js')
 	const bodySizeLimit = baseEnv.BODY_SIZE_LIMIT || 'Infinity'
+	const childEnv = createBosunChildEnvironment(
+		baseEnv,
+		gitModeRuntime,
+		`http://localhost:${ports.frontend}`
+	)
 
 	const child = spawn(process.execPath, [frontPath], {
 		cwd: process.cwd(),
 		stdio: 'inherit',
 		env: {
-			...baseEnv,
+			...childEnv,
 			HOST: 'localhost',
 			PORT: String(ports.frontend),
 			PUBLIC_WS_HOST: `ws://localhost:${ports.ws}`,
@@ -118,8 +147,9 @@ function startFrontend() {
 			// Latency recordings are uploaded as WAV files and can be large.
 			BODY_SIZE_LIMIT: bodySizeLimit
 		},
-		shell: process.platform === 'win32'
+		shell: false
 	})
+	registerChildOrStop(child, 'frontend')
 	watchChild(child, 'frontend')
 	return child
 }
@@ -253,40 +283,143 @@ function isUnsupportedIpv6Error(error) {
  * @param {string} name
  */
 function watchChild(child, name) {
+	/** @type {(outcome: { code: number | null, signal: NodeJS.Signals | null }) => void} */
+	let resolveExit = () => {}
+	const exitPromise = new Promise((resolvePromise) => {
+		resolveExit = resolvePromise
+	})
+	childExitPromises.set(child, exitPromise)
+
 	child.on('error', (error) => {
 		if (isShuttingDown) return
 		console.error(`❌ Bosun ${name} failed to start:`, error.message)
-		shutdown(1)
+		void shutdown(1)
 	})
 
-	child.on('exit', (code, signal) => {
+	child.on('close', (code, signal) => {
+		try {
+			unregisterGitModeChildProcess(gitModeRuntime, child.pid)
+		} catch (error) {
+			console.error(`❌ Bosun could not update ${name} process state:`, error)
+		}
+		resolveExit({ code, signal })
 		if (isShuttingDown) return
 		if (name === 'backend' && code === BACKEND_RESTART_EXIT_CODE && !signal) {
 			console.log('🔄 Bosun backend restarting to load project changes')
 			backendProcess = startBackend()
 			return
 		}
+		if (name === 'backend' && code === GIT_ACTIVATION_RESTART_EXIT_CODE && !signal) {
+			console.log('🔄 Bosun backend restarting after Git refresh')
+			backendProcess = startBackend()
+			return
+		}
 
 		const reason = signal ? `signal ${signal}` : `exit code ${code ?? 1}`
 		console.error(`❌ Bosun ${name} stopped unexpectedly (${reason}).`)
-		shutdown(code ?? 1)
+		void shutdown(code ?? 1)
 	})
 }
 
+/** @param {ChildProcess} child @param {string} name */
+function registerChildOrStop(child, name) {
+	try {
+		registerGitModeChildProcess(gitModeRuntime, child.pid, name)
+	} catch (error) {
+		try {
+			child.kill('SIGKILL')
+		} catch {}
+		throw error
+	}
+}
+
 // Handle cleanup
-process.on('SIGINT', () => shutdown(0))
-process.on('SIGTERM', () => shutdown(0))
+process.on('SIGINT', () => void shutdown(0))
+process.on('SIGTERM', () => void shutdown(0))
 
 /**
  * @param {number} code
  */
 function shutdown(code) {
+	if (shutdownPromise) return shutdownPromise
 	isShuttingDown = true
-	if (backendProcess) backendProcess.kill()
-	if (frontendProcess) frontendProcess.kill()
+	shutdownPromise = performShutdown(code)
+	return shutdownPromise
+}
+
+/** @param {number} code */
+async function performShutdown(code) {
+	const backendAtShutdown = backendProcess
+	const frontendAtShutdown = frontendProcess
+	// The backend first closes the cross-process write gate and drains any frontend file operation
+	// admitted before that lock. Keep the frontend alive for that drain, then stop it.
+	const backendStopped = await stopChild(backendAtShutdown, 'backend')
+	const frontendStopped = await stopChild(frontendAtShutdown, 'frontend')
+	const childrenStopped = backendStopped && frontendStopped
+
+	if (gitModeRuntime) {
+		if (childrenStopped) {
+			try {
+				cleanupGitModeRuntime(gitModeRuntime)
+			} catch (error) {
+				code = 1
+				console.error(
+					'❌ Bosun retained the repository lease because shutdown cleanup could not be verified:',
+					error instanceof Error ? error.message : String(error)
+				)
+			}
+		} else {
+			code = 1
+			console.error(
+				'❌ Bosun could not confirm that all child processes stopped. Restart Bosun after they exit.'
+			)
+		}
+	}
+
 	process.exit(code)
 }
 
+/**
+ * @param {ChildProcess | null} child
+ * @param {string} name
+ * @returns {Promise<boolean>}
+ */
+async function stopChild(child, name) {
+	if (!child) return true
+	const exit = childExitPromises.get(child)
+	if (!exit) {
+		return child.exitCode !== null || child.signalCode !== null
+	}
+
+	if (child.exitCode === null && child.signalCode === null) {
+		try {
+			child.kill('SIGTERM')
+		} catch (error) {
+			console.error(`❌ Bosun could not ask the ${name} process to stop:`, error)
+		}
+	}
+
+	const gracefulOutcome = await settleWithin(exit, 12_000)
+	if (gracefulOutcome) return true
+
+	console.error(`❌ Bosun ${name} did not stop gracefully; forcing it to exit.`)
+	try {
+		child.kill('SIGKILL')
+	} catch (error) {
+		console.error(`❌ Bosun could not force the ${name} process to stop:`, error)
+	}
+	const forcedOutcome = await settleWithin(exit, 3_000)
+	return forcedOutcome !== null
+}
+
+/** @template T @param {Promise<T>} promise @param {number} timeoutMs */
+function settleWithin(promise, timeoutMs) {
+	return Promise.race([
+		promise.then((value) => ({ settled: true, value })),
+		sleep(timeoutMs).then(() => ({ settled: false, value: null }))
+	]).then((result) => (result.settled ? result.value : null))
+}
+
 function isLinked() {
 	return !__filename.includes('node_modules/@recombine-ai/bosun')
 }