@roj-ai/sdk 0.1.33 → 0.1.34

package/src/core/system.ts

@@ -10,6 +10,7 @@
 import type z4 from 'zod/v4'
 import type { Logger } from '~/lib/logger/logger.js'
 import type { Platform } from '~/platform/index.js'
+import type { ServicePidRegistry } from '~/plugins/services/pid-registry.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
 import type { PreprocessorRegistry } from '~/plugins/uploads/preprocessor.js'
 import type { EventStore } from './events/event-store.js'
@@ -120,6 +121,7 @@ export interface CreateSystemOptions<TPlugins extends readonly PluginDefinition<
 	preprocessorRegistry?: PreprocessorRegistry
 	llmLogger?: LLMLogger
 	portPool?: PortPool
+	pidRegistry?: ServicePidRegistry
 	/** Host-environment adapters (filesystem, process). */
 	platform: Platform
 }
@@ -145,6 +147,7 @@ export function createSystem<const TPlugins extends readonly PluginDefinition<st
 		preprocessorRegistry,
 		llmLogger,
 		portPool,
+		pidRegistry,
 		platform,
 	} = options
 
@@ -167,6 +170,7 @@ export function createSystem<const TPlugins extends readonly PluginDefinition<st
 		preprocessorRegistry,
 		llmLogger,
 		portPool,
+		pidRegistry,
 		platform,
 		systemPlugins: [...plugins],
 	})

package/src/plugins/services/pid-registry.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'bun:test'
+import { spawn } from 'node:child_process'
+import { readdir, readFile, mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { silentLogger } from '~/lib/logger/logger.js'
+import { createNodePlatform } from '~/testing/node-platform.js'
+import { ServicePidRegistry } from './pid-registry.js'
+import { getProcessStartTime } from './service.js'
+
+const fs = createNodePlatform().fs
+
+async function withDataDir<T>(fn: (dataPath: string) => Promise<T>): Promise<T> {
+	const dataPath = await mkdtemp(join(tmpdir(), 'pid-registry-'))
+	try {
+		return await fn(dataPath)
+	} finally {
+		await rm(dataPath, { recursive: true, force: true })
+	}
+}
+
+/** A detached `sleep`, so `kill(-pid)` has a real process group to take down. */
+function spawnVictim(): { pid: number; exited: Promise<void> } {
+	const child = spawn('/bin/sh', ['-c', 'sleep 60'], { detached: true, stdio: 'ignore' })
+	child.unref()
+	if (!child.pid) throw new Error('failed to spawn victim')
+	const exited = new Promise<void>(resolve => child.on('close', () => resolve()))
+	return { pid: child.pid, exited }
+}
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** A pid the kernel cannot have handed out, so it reads as a dead agent. */
+async function unusablePid(): Promise<number> {
+	const max = Number((await readFile('/proc/sys/kernel/pid_max', 'utf-8')).trim())
+	return max + 1
+}
+
+async function writeRecord(dataPath: string, record: Record<string, unknown>): Promise<string> {
+	const dir = join(dataPath, 'service-pids')
+	await mkdir(dir, { recursive: true })
+	const path = join(dir, `${record.sessionId}__${record.serviceType}.json`)
+	await writeFile(path, JSON.stringify(record))
+	return path
+}
+
+const makeRegistry = (dataPath: string) => new ServicePidRegistry(fs, silentLogger, dataPath)
+
+describe('ServicePidRegistry', () => {
+	it('kills a service left behind by an agent that is gone, and drops the record', async () => {
+		await withDataDir(async dataPath => {
+			const victim = spawnVictim()
+			await writeRecord(dataPath, {
+				sessionId: 'sess-1',
+				serviceType: 'astro-dev',
+				pid: victim.pid,
+				pidStartTime: await getProcessStartTime(fs, victim.pid),
+				command: 'sleep 60',
+				agentPid: await unusablePid(),
+				agentStartTime: 12345,
+			})
+
+			await makeRegistry(dataPath).sweepOrphans()
+
+			await victim.exited
+			expect(isAlive(victim.pid)).toBe(false)
+			expect(await readdir(join(dataPath, 'service-pids'))).toEqual([])
+		})
+	})
+
+	it('leaves a service whose agent is still running', async () => {
+		await withDataDir(async dataPath => {
+			const victim = spawnVictim()
+			try {
+				// This test process stands in for a second, still-live agent.
+				await writeRecord(dataPath, {
+					sessionId: 'sess-1',
+					serviceType: 'astro-dev',
+					pid: victim.pid,
+					pidStartTime: await getProcessStartTime(fs, victim.pid),
+					command: 'sleep 60',
+					agentPid: process.pid,
+					agentStartTime: await getProcessStartTime(fs, process.pid),
+				})
+
+				await makeRegistry(dataPath).sweepOrphans()
+
+				expect(isAlive(victim.pid)).toBe(true)
+				expect(await readdir(join(dataPath, 'service-pids'))).toHaveLength(1)
+			} finally {
+				process.kill(-victim.pid, 'SIGKILL')
+			}
+		})
+	})
+
+	it('refuses to kill when the pid has been recycled', async () => {
+		await withDataDir(async dataPath => {
+			const victim = spawnVictim()
+			try {
+				const actual = await getProcessStartTime(fs, victim.pid)
+				await writeRecord(dataPath, {
+					sessionId: 'sess-1',
+					serviceType: 'astro-dev',
+					pid: victim.pid,
+					// Deliberately not the process now holding this pid.
+					pidStartTime: (actual ?? 0) + 999,
+					command: 'sleep 60',
+					agentPid: await unusablePid(),
+				})
+
+				await makeRegistry(dataPath).sweepOrphans()
+
+				expect(isAlive(victim.pid)).toBe(true)
+				// The record still goes — whatever holds that pid now, it is not ours to track.
+				expect(await readdir(join(dataPath, 'service-pids'))).toEqual([])
+			} finally {
+				process.kill(-victim.pid, 'SIGKILL')
+			}
+		})
+	})
+
+	it('never sweeps what this very process started', async () => {
+		await withDataDir(async dataPath => {
+			const registry = makeRegistry(dataPath)
+			const victim = spawnVictim()
+			try {
+				await registry.record({
+					sessionId: 'sess-1',
+					serviceType: 'astro-dev',
+					pid: victim.pid,
+					pidStartTime: await getProcessStartTime(fs, victim.pid),
+					command: 'sleep 60',
+				})
+
+				await registry.sweepOrphans()
+
+				expect(isAlive(victim.pid)).toBe(true)
+			} finally {
+				process.kill(-victim.pid, 'SIGKILL')
+			}
+		})
+	})
+
+	it('drops an unreadable record instead of throwing', async () => {
+		await withDataDir(async dataPath => {
+			const dir = join(dataPath, 'service-pids')
+			await mkdir(dir, { recursive: true })
+			await writeFile(join(dir, 'sess-1__astro-dev.json'), 'not json')
+
+			await makeRegistry(dataPath).sweepOrphans()
+
+			expect(await readdir(dir)).toEqual([])
+		})
+	})
+
+	it('does nothing when no service has ever been recorded', async () => {
+		await withDataDir(async dataPath => {
+			await makeRegistry(dataPath).sweepOrphans()
+		})
+	})
+
+	it('forget removes the record for a service that has exited', async () => {
+		await withDataDir(async dataPath => {
+			const registry = makeRegistry(dataPath)
+			await registry.record({ sessionId: 'sess-1', serviceType: 'astro-dev', pid: 1, pidStartTime: 1, command: 'x' })
+			expect(await readdir(join(dataPath, 'service-pids'))).toHaveLength(1)
+
+			await registry.forget('sess-1', 'astro-dev')
+
+			expect(await readdir(join(dataPath, 'service-pids'))).toEqual([])
+		})
+	})
+})

package/src/plugins/services/pid-registry.ts

@@ -0,0 +1,191 @@
+/**
+ * ServicePidRegistry — on-disk record of the service processes this host has spawned,
+ * so a later agent can find and kill the ones nobody owns any more.
+ *
+ * The session projection cannot do this job. It remembers one pid per service type, so
+ * every start overwrites the previous generation, and its reconcile runs from
+ * `onSessionReady` — which fires lazily, when a session is loaded. A session nobody
+ * reopens after a restart therefore never reconciles at all, and its dev server keeps
+ * running until the box runs out of memory. That is not theoretical: a production
+ * sandbox on 2026-08-05 held four dev servers at ~500 MB each across three sessions on
+ * 4 GB with no swap, and the kernel OOM-killer fired repeatedly.
+ *
+ * A file per (session, service type) survives both an agent restart and a VM
+ * pause/resume, and is enumerable without knowing which sessions exist — which is what
+ * makes a host-wide sweep at boot possible.
+ */
+
+import { join } from 'node:path'
+import type { FileSystem } from '~/platform/fs.js'
+import type { Logger } from '../../lib/logger/logger.js'
+import { getProcessStartTime } from './service.js'
+
+/**
+ * What we need in order to decide, later and from another process, whether a recorded
+ * pid may be killed.
+ *
+ * `pidStartTime` is /proc's start time in clock ticks: paired with the pid it identifies
+ * one process, so a mismatch means the kernel recycled the pid and killing would hit an
+ * unrelated process. `agentPid`/`agentStartTime` identify the agent that spawned it — a
+ * booting agent must not kill the services of another agent that is still running.
+ */
+export interface ServicePidRecord {
+	sessionId: string
+	serviceType: string
+	pid: number
+	pidStartTime?: number
+	command: string
+	agentPid: number
+	agentStartTime?: number
+}
+
+const REGISTRY_DIR = 'service-pids'
+
+export class ServicePidRegistry {
+	constructor(
+		private readonly fs: FileSystem,
+		private readonly logger: Logger,
+		/** Agent data directory. Never the session workspace — that is a git worktree. */
+		private readonly dataPath: string,
+	) {}
+
+	private get root(): string {
+		return join(this.dataPath, REGISTRY_DIR)
+	}
+
+	private recordPath(sessionId: string, serviceType: string): string {
+		// Service types are plugin-configured identifiers (`astro-dev`, `cms-sidecar`) and
+		// session ids are uuids, so neither needs escaping to be a safe file name.
+		return join(this.root, `${sessionId}__${serviceType}.json`)
+	}
+
+	/**
+	 * Record a freshly spawned service process. Best-effort: failing to record costs us a
+	 * later sweep, so it must never take down the start that just succeeded.
+	 */
+	async record(record: Omit<ServicePidRecord, 'agentPid' | 'agentStartTime'>): Promise<void> {
+		try {
+			await this.fs.mkdir(this.root, { recursive: true })
+			const full: ServicePidRecord = {
+				...record,
+				agentPid: process.pid,
+				agentStartTime: await getProcessStartTime(this.fs, process.pid),
+			}
+			await this.fs.writeFile(this.recordPath(record.sessionId, record.serviceType), JSON.stringify(full))
+		} catch (error) {
+			this.logger.debug('Could not record service pid', { sessionId: record.sessionId, serviceType: record.serviceType, error })
+		}
+	}
+
+	/** Drop the record for a service whose process is gone. */
+	async forget(sessionId: string, serviceType: string): Promise<void> {
+		try {
+			await this.fs.unlink(this.recordPath(sessionId, serviceType))
+		} catch {
+			// Already gone, or never recorded.
+		}
+	}
+
+	/**
+	 * Kill every recorded service process that no live agent owns, and clear its record.
+	 *
+	 * Meant to run once at agent boot, before any session loads: at that moment this agent
+	 * tracks nothing, so every survivor of a previous incarnation is by definition an
+	 * orphan. Records left by an agent that is still running are skipped — during an
+	 * overlapping restart the outgoing agent's services are still its own.
+	 */
+	async sweepOrphans(): Promise<void> {
+		let files: string[]
+		try {
+			files = await this.fs.readdir(this.root)
+		} catch {
+			return // No registry yet — nothing has ever been spawned here.
+		}
+
+		for (const file of files) {
+			if (!file.endsWith('.json')) continue
+			const path = join(this.root, file)
+			const record = await this.readRecord(path)
+			if (!record) {
+				await this.fs.unlink(path).catch(() => {})
+				continue
+			}
+
+			if (await this.isAgentAlive(record)) {
+				this.logger.debug('Leaving service to its still-running agent', {
+					sessionId: record.sessionId,
+					serviceType: record.serviceType,
+					agentPid: record.agentPid,
+				})
+				continue
+			}
+
+			await this.killIfStillOurs(record)
+			await this.fs.unlink(path).catch(() => {})
+		}
+	}
+
+	private async readRecord(path: string): Promise<ServicePidRecord | null> {
+		try {
+			const parsed: unknown = JSON.parse(await this.fs.readFile(path, 'utf-8'))
+			if (typeof parsed !== 'object' || parsed === null) return null
+			const record = parsed as Partial<ServicePidRecord>
+			if (typeof record.pid !== 'number' || typeof record.sessionId !== 'string' || typeof record.serviceType !== 'string') {
+				return null
+			}
+			return {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				pidStartTime: record.pidStartTime,
+				command: typeof record.command === 'string' ? record.command : '',
+				agentPid: typeof record.agentPid === 'number' ? record.agentPid : 0,
+				agentStartTime: record.agentStartTime,
+			}
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * Whether a live agent still owns this record. Ourselves counts: a record carrying our own
+	 * pid describes a service this very process started, which the sweep must never touch —
+	 * that is what makes the sweep safe to run at any time, not only before the first start.
+	 */
+	private async isAgentAlive(record: ServicePidRecord): Promise<boolean> {
+		if (record.agentPid === process.pid) return true
+		if (record.agentPid === 0) return false
+		const currentStartTime = await getProcessStartTime(this.fs, record.agentPid)
+		if (currentStartTime === undefined) return false
+		return record.agentStartTime === undefined || currentStartTime === record.agentStartTime
+	}
+
+	private async killIfStillOurs(record: ServicePidRecord): Promise<void> {
+		const currentStartTime = await getProcessStartTime(this.fs, record.pid)
+		if (currentStartTime === undefined) return // Process is gone.
+		if (record.pidStartTime !== undefined && currentStartTime !== record.pidStartTime) {
+			this.logger.warn('PID reuse detected during orphan sweep — refusing to kill', {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				storedStartTime: record.pidStartTime,
+				currentStartTime,
+			})
+			return
+		}
+
+		try {
+			// Negative pid: services are spawned detached, so this takes the whole group —
+			// the `/bin/sh -c` wrapper and the runtime it exec'd underneath it.
+			process.kill(-record.pid, 'SIGKILL')
+			this.logger.info('Killed orphaned service process group', {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				command: record.command,
+			})
+		} catch (error) {
+			this.logger.debug('Orphaned service process already gone', { pid: record.pid, error })
+		}
+	}
+}

package/src/plugins/services/plugin.ts

@@ -8,6 +8,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { PortPool } from './port-pool.js'
 import { buildServiceStatusMessage } from './prompt.js'
 import type { ServiceConfig, ServiceEntry } from './schema.js'
+import type { ServicePidRegistry } from './pid-registry.js'
 import { getProcessStartTime, ServiceExecutor } from './service.js'
 
 export const serviceEvents = createEventsFactory({
@@ -33,6 +34,8 @@ export type ServiceStatusChangedEvent = (typeof serviceEvents)['Events']['servic
 export interface ServicePluginConfig {
 	services: ServiceConfig[]
 	portPool: PortPool
+	/** Durable pid record swept at agent boot. Absent for embedders without a data dir. */
+	pidRegistry?: ServicePidRegistry
 }
 
 /**
@@ -133,7 +136,11 @@ export const servicePlugin = definePlugin('services')
 		},
 	})
 	.context(async (ctx, pluginConfig) => {
-		const executor = new ServiceExecutor(ctx.logger, pluginConfig.portPool, { fs: ctx.platform.fs, process: ctx.platform.process })
+		const executor = new ServiceExecutor(ctx.logger, pluginConfig.portPool, {
+			fs: ctx.platform.fs,
+			process: ctx.platform.process,
+			pidRegistry: pluginConfig.pidRegistry,
+		})
 		executor.onStatusChanged = (sessionId, serviceType, status, details) => {
 			void ctx.emitEvent(serviceEvents.create('service_status_changed', {
 				serviceType,

package/src/plugins/services/service.ts

@@ -13,6 +13,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
 import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
+import type { ServicePidRegistry } from '~/plugins/services/pid-registry.js'
 import type { ServiceConfig, ServiceStartArgs, ServiceStatus } from '~/plugins/services/schema.js'
 import type { ToolError } from '../../core/tools/executor.js'
 import type { Logger } from '../../lib/logger/logger.js'
@@ -89,6 +90,8 @@ const MAX_PORT_CONFLICT_RETRIES = 3
 export interface ServiceExecutorDeps {
 	fs: FileSystem
 	process: ProcessRunner
+	/** Durable pid record, swept at agent boot. Optional so embedders without a data dir still work. */
+	pidRegistry?: ServicePidRegistry
 }
 
 export class ServiceExecutor {
@@ -103,6 +106,7 @@ export class ServiceExecutor {
 	private readonly portPool: PortPool
 	private readonly fs: FileSystem
 	private readonly processRunner: ProcessRunner
+	private readonly pidRegistry?: ServicePidRegistry
 
 	/** Optional callback invoked on every service status change */
 	onStatusChanged?: (
@@ -117,6 +121,7 @@ export class ServiceExecutor {
 		this.portPool = portPool
 		this.fs = deps.fs
 		this.processRunner = deps.process
+		this.pidRegistry = deps.pidRegistry
 	}
 
 	private notifyStatusChanged(
@@ -354,6 +359,11 @@ export class ServiceExecutor {
 		// "our process" from "an unrelated process that grabbed this PID after ours died"
 		const pidStartTime = await getProcessStartTime(this.fs, child.pid)
 
+		// Durably record the process so a future agent can reap it if we die before the
+		// `close` handler gets to forget it. The session projection cannot serve that
+		// purpose — see ServicePidRegistry.
+		await this.pidRegistry?.record({ sessionId: String(sessionId), serviceType: config.type, pid: child.pid, pidStartTime, command })
+
 		// Emit starting event with PID, port, resolved cwd/command, and start time.
 		this.notifyStatusChanged(sessionId, config.type, 'starting', { port, pid: child.pid, pidStartTime, cwd, command })
 
@@ -512,6 +522,8 @@ export class ServiceExecutor {
 		// Handle unexpected exit
 		child.on('close', (code) => {
 			clearReadinessTimers()
+			// The process is gone, so its durable record has nothing left to reap.
+			void this.pidRegistry?.forget(String(sessionId), config.type)
 			// Flush remaining partial lines
 			if (stdoutPartial) {
 				processLine(stdoutPartial)