debug: (msg: string) => void

info: (msg: string) => void

warn: (msg: string) => void

error: (msg: string) => void

// Check for control characters

for (let i = 0; i < name.length; i++) {

const code = name.charCodeAt(i)

if (code <= 0x1f || code === 0x7f) return false

}

// Check for invalid git ref characters and shell metacharacters

if (/[~^:?*[\]\\;&|`$()]/.test(name)) return false

return true

constructor(

message: string,

public readonly operation: string,

public readonly cause?: unknown,

) {

super(`${operation}: ${message}`)

this.name = "WorktreeError"

}

ocxBin: string,

baseDirectory: string,

resolveExecutable: ResolveExecutable,

): Result<string, string> {

if (isPathLikeCommand(ocxBin)) {

const resolvedPath = path.isAbsolute(ocxBin) ? ocxBin : path.resolve(baseDirectory, ocxBin)

return Result.ok(resolvedPath)

}

const resolvedFromPath = resolveExecutable(ocxBin)

if (!resolvedFromPath) {

return Result.err(`Configured OCX binary "${ocxBin}" is not available in PATH.`)

}

const resolvedPath = path.isAbsolute(resolvedFromPath)

? resolvedFromPath

: path.resolve(baseDirectory, resolvedFromPath)

return Result.ok(resolvedPath)

try {

const stats = await stat(absolutePath)

if (stats.isDirectory()) {

return false

}

await access(absolutePath, fsConstants.X_OK)

return true

} catch {

return false

}

launchContext: ActiveLaunchContext,

baseDirectory: string,

options: LaunchExecutableValidationOptions = {},

): Promise<ActiveLaunchContext> {

if (launchContext.mode === "plain") {

return launchContext

}

const { ocxBin, profile } = launchContext

const resolveExecutable = options.resolveExecutable ?? ((command: string) => Bun.which(command))

const pathExists = options.pathExists ?? pathPointsToLaunchableBinary

const resolvedPathResult = resolveStableLaunchBinaryPath(ocxBin, baseDirectory, resolveExecutable)

if (!resolvedPathResult.ok) {

throw new WorktreeError(

`${resolvedPathResult.error} Repair the parent OCX profile (${profile}) and recreate this worktree session.`,

"launch",

)

}

const resolvedPath = resolvedPathResult.value

const isLaunchable = await pathExists(resolvedPath)

if (!isLaunchable) {

throw new WorktreeError(

`Configured OCX binary "${ocxBin}" resolved to "${resolvedPath}" but is missing or stale. Repair the parent OCX profile (${profile}) and recreate this worktree session.`,

"launch",

)

}

return {

mode: "ocx",

ocxBin: resolvedPath,

profile,

}

ocxBin: string,

profile: string,

): Promise<Result<void, string>> {

try {

const proc = Bun.spawn([ocxBin, "profile", "show", profile, "--global", "--json"], {

stdout: "pipe",

stderr: "pipe",

})

const [exitCode, stdout, stderr] = await Promise.all([

proc.exited,

new Response(proc.stdout).text(),

new Response(proc.stderr).text(),

])

if (exitCode === 0) {

return Result.ok(undefined)

}

const detail = stderr.trim() || stdout.trim() || `exit ${exitCode}`

return Result.err(detail)

} catch (error) {

return Result.err(error instanceof Error ? error.message : String(error))

}

launchContext: ActiveLaunchContext,

validateProfileAvailability: ValidateProfileAvailability = validateOcxProfileAvailability,

): Promise<void> {

if (launchContext.mode === "plain") {

return

}

const validationResult = await validateProfileAvailability(

launchContext.ocxBin,

launchContext.profile,

)

if (validationResult.ok) {

return

}

throw new WorktreeError(

`Configured OCX profile "${launchContext.profile}" is missing or stale. ${validationResult.error} Repair the parent OCX profile and recreate this worktree session.`,

"launch",

)

try {

await access(filePath)

return true

} catch (e: unknown) {

if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {

return false

}

throw e // Re-throw permission errors, etc.

}

if (!(await pathExists(src))) return false

await copyFile(src, dest)

return true

if (!(await pathExists(src))) return false

await cp(src, dest, { recursive: true })

return true

forkedSession: { id: string }

rootSessionId: string

planCopied: boolean

delegationsCopied: boolean

database: Database

worktreePath: string

launchArgv: string[]

branch: string

forkedSessionId: string

sessionRecord: {

id: string

branch: string

path: string

createdAt: string

launchMode: "plain" | "ocx"

profile: string | null

ocxBin: string | null

}

log: Logger

openTerminalFn?: (cwd: string, argv?: string[], windowName?: string) => Promise<TerminalResult>

addSessionFn?: typeof addSession

deleteForkedSessionFn?: (sessionId: string) => Promise<void>

options: FinalizeWorktreeLaunchOptions,

): Promise<TerminalResult> {

const openTerminalFn = options.openTerminalFn ?? openTerminal

const addSessionFn = options.addSessionFn ?? addSession

const deleteForkedSessionFn =

options.deleteForkedSessionFn ??

(async (_sessionId: string) => {

// Default no-op for tests without cleanup side effects.

})

const terminalResult = await openTerminalFn(

options.worktreePath,

options.launchArgv,

options.branch,

)

if (!terminalResult.success) {

await deleteForkedSessionFn(options.forkedSessionId).catch((cleanupError) => {

options.log.warn(

`[worktree] Failed to clean up forked session ${options.forkedSessionId} after launch failure: ${cleanupError}`,

)

})

return terminalResult

}

addSessionFn(options.database, options.sessionRecord)

return terminalResult

client: OpencodeClient,

sessionId: string,

projectId: string,

getRootSessionIdFn: (sessionId: string) => Promise<string>,

): Promise<ForkResult> {

// Guard clauses (Law 1)

if (!client) throw new WorktreeError("client is required", "forkWithContext")

if (!sessionId) throw new WorktreeError("sessionId is required", "forkWithContext")

if (!projectId) throw new WorktreeError("projectId is required", "forkWithContext")

// Get root session ID with error wrapping

let rootSessionId: string

try {

rootSessionId = await getRootSessionIdFn(sessionId)

} catch (e) {

throw new WorktreeError("Failed to get root session ID", "forkWithContext", e)

}

// Fork session

const forkedSessionResponse = await client.session.fork({

path: { id: sessionId },

body: {},

})

const forkedSession = forkedSessionResponse.data

if (!forkedSession?.id) {

throw new WorktreeError("Failed to fork session: no session data returned", "forkWithContext")

}

// Copy data with cleanup on failure

let planCopied = false

let delegationsCopied = false

try {

const workspaceBase = path.join(os.homedir(), ".local", "share", "opencode", "workspace")

const delegationsBase = path.join(os.homedir(), ".local", "share", "opencode", "delegations")

const destWorkspaceDir = path.join(workspaceBase, projectId, forkedSession.id)

const destDelegationsDir = path.join(delegationsBase, projectId, forkedSession.id)

await mkdir(destWorkspaceDir, { recursive: true })

await mkdir(destDelegationsDir, { recursive: true })

// Copy plan

const srcPlan = path.join(workspaceBase, projectId, rootSessionId, "plan.md")

const destPlan = path.join(destWorkspaceDir, "plan.md")

planCopied = await copyIfExists(srcPlan, destPlan)

// Copy delegations

const srcDelegations = path.join(delegationsBase, projectId, rootSessionId)

delegationsCopied = await copyDirIfExists(srcDelegations, destDelegationsDir)

} catch (error) {

client.app

.log({

body: {

service: "worktree",

level: "error",

message: `forkWithContext: Copy failed, cleaning up forked session: ${error}`,

},

})

.catch(() => {})

// Clean up orphaned directories

const workspaceBase = path.join(os.homedir(), ".local", "share", "opencode", "workspace")

const delegationsBase = path.join(os.homedir(), ".local", "share", "opencode", "delegations")

const destWorkspaceDir = path.join(workspaceBase, projectId, forkedSession.id)

const destDelegationsDir = path.join(delegationsBase, projectId, forkedSession.id)

await rm(destWorkspaceDir, { recursive: true, force: true }).catch((e) => {

client.app

.log({

body: {

service: "worktree",

level: "error",

message: `forkWithContext: Failed to clean up workspace dir ${destWorkspaceDir}: ${e}`,

},

})

.catch(() => {})

})

await rm(destDelegationsDir, { recursive: true, force: true }).catch((e) => {

client.app

.log({

body: {

service: "worktree",

level: "error",

message: `forkWithContext: Failed to clean up delegations dir ${destDelegationsDir}: ${e}`,

},

})

.catch(() => {})

})

await client.session.delete({ path: { id: forkedSession.id } }).catch((e) => {

client.app

.log({

body: {

service: "worktree",

level: "error",

message: `forkWithContext: Failed to clean up forked session ${forkedSession.id}: ${e}`,

},

})

.catch(() => {})

})

throw new WorktreeError(

`Failed to copy session data: ${error instanceof Error ? error.message : String(error)}`,

"forkWithContext",

error,

)

}

return { forkedSession, rootSessionId, planCopied, delegationsCopied }

if (cleanupRegistered) return // Early exit guard

cleanupRegistered = true

const cleanup = () => {

try {

database.exec("PRAGMA wal_checkpoint(TRUNCATE)")

database.close()

} catch {

// Best effort cleanup - process is exiting anyway

}

}

process.once("SIGTERM", cleanup)

process.once("SIGINT", cleanup)

process.once("beforeExit", cleanup)

if (db) return db

if (!projectRoot) {

throw new Error("Database not initialized: projectRoot not set. Call initDb() first.")

}

let lastError: Error | null = null

for (let attempt = 1; attempt <= DB_MAX_RETRIES; attempt++) {

try {

db = await initStateDb(projectRoot)

registerCleanupHandlers(db)

return db

} catch (error) {

lastError = error instanceof Error ? error : new Error(String(error))

log.warn(`Database init attempt ${attempt}/${DB_MAX_RETRIES} failed: ${lastError.message}`)

if (attempt < DB_MAX_RETRIES) {

Bun.sleepSync(DB_RETRY_DELAY_MS)

}

}

}

throw new Error(

`Failed to initialize database after ${DB_MAX_RETRIES} attempts: ${lastError?.message}`,

)

try {

const proc = Bun.spawn(["git", ...args], {

cwd,

stdout: "pipe",

stderr: "pipe",

})

const [stdout, stderr, exitCode] = await Promise.all([

new Response(proc.stdout).text(),

new Response(proc.stderr).text(),

proc.exited,

])

if (exitCode !== 0) {

return Result.err(stderr.trim() || `git ${args[0]} failed`)

}

return Result.ok(stdout.trim())

} catch (error) {

return Result.err(error instanceof Error ? error.message : String(error))

}

repoRoot: string,

branch: string,

baseBranch?: string,

basePath?: string,

): Promise<Result<string, string>> {

const worktreePath = await getWorktreePath(repoRoot, branch, basePath)

// Ensure parent directory exists

await mkdir(path.dirname(worktreePath), { recursive: true })

const exists = await branchExists(repoRoot, branch)

if (exists) {

// Checkout existing branch into worktree

const result = await git(["worktree", "add", worktreePath, branch], repoRoot)

return result.ok ? Result.ok(worktreePath) : result

} else {

// Create new branch from base

const base = baseBranch ?? "HEAD"

const result = await git(["worktree", "add", "-b", branch, worktreePath, base], repoRoot)

return result.ok ? Result.ok(worktreePath) : result

}

repoRoot: string,

worktreePath: string,

): Promise<Result<void, string>> {

const result = await git(["worktree", "remove", "--force", worktreePath], repoRoot)

return result.ok ? Result.ok(undefined) : Result.err(result.error)

// Reject absolute paths

if (path.isAbsolute(filePath)) {

log.warn(`[worktree] Rejected absolute path: ${filePath}`)

return false

}

// Reject obvious path traversal

if (filePath.includes("..")) {

log.warn(`[worktree] Rejected path traversal: ${filePath}`)

return false

}

// Verify resolved path stays within base directory

const resolved = path.resolve(baseDir, filePath)

if (!resolved.startsWith(baseDir + path.sep) && resolved !== baseDir) {

log.warn(`[worktree] Path escapes base directory: ${filePath}`)

return false

}

return true

rootDir: string,

relativePath: string,

log: Logger,

): Promise<string | null> {

const rootRealPath = await realpath(rootDir).catch(() => null)

if (!rootRealPath) {

log.warn(`[worktree] Failed to resolve worktree root: ${rootDir}`)

return null

}

const candidatePath = path.resolve(rootDir, relativePath)

const candidateRealPath = await realpath(candidatePath).catch(() => null)

if (!candidateRealPath) return null

if (!isWithinRealRoot(rootRealPath, candidateRealPath)) {

log.warn(`[worktree] Rejected path escaping worktree via symlink: ${relativePath}`)

return null

}

return candidateRealPath

rootDir: string,

relativeDir: string,

log: Logger,

): Promise<string | null> {

const rootRealPath = await realpath(rootDir).catch(() => null)

if (!rootRealPath) {

log.warn(`[worktree] Failed to resolve worktree root: ${rootDir}`)

return null

}

const rootPath = path.resolve(rootDir)

const targetDir = path.resolve(rootDir, relativeDir)

const resolvedRootRelative = path.relative(rootPath, targetDir)

if (

resolvedRootRelative !== "" &&

(resolvedRootRelative.startsWith("..") || path.isAbsolute(resolvedRootRelative))

) {

log.warn(`[worktree] Rejected path escaping worktree: ${relativeDir}`)

return null

}

const rootRelative = path.relative(rootDir, targetDir)

const parts = rootRelative.split(path.sep).filter(Boolean)

let cursor = rootDir

for (const part of parts) {

cursor = path.join(cursor, part)

const entry = await lstat(cursor).catch(() => null)

if (entry?.isSymbolicLink()) {

log.warn(`[worktree] Rejected symlinked target parent: ${relativeDir}`)

return null

}

if (entry && !entry.isDirectory()) {

log.warn(`[worktree] Rejected non-directory target parent: ${relativeDir}`)

return null

}

if (!entry) {

await mkdir(cursor)

}

}

const finalRealPath = await realpath(targetDir).catch(() => null)

if (!finalRealPath || !isWithinRealRoot(rootRealPath, finalRealPath)) {

log.warn(`[worktree] Rejected path escaping worktree via symlink: ${relativeDir}`)

return null

}

return targetDir

sourceDir: string,

targetDir: string,

files: string[],

log: Logger,

): Promise<void> {

for (const file of files) {

if (!isPathSafe(file, sourceDir, log)) continue

const sourcePath = await resolveExistingPathWithinRoot(sourceDir, file, log)

if (!sourcePath) continue

const targetPath = path.join(targetDir, file)

try {

const sourceFile = Bun.file(sourcePath)

if (!(await sourceFile.exists())) {

log.debug(`[worktree] Skipping missing file: ${file}`)

continue

}

// Ensure target directory exists

const targetFileDir = path.dirname(targetPath)

const targetFileRelativeDir = path.relative(targetDir, targetFileDir)

if (!(await ensureDirectoryWithinRoot(targetDir, targetFileRelativeDir, log))) continue

const existingTarget = await lstat(targetPath).catch(() => null)

if (existingTarget?.isSymbolicLink()) {

log.warn(`[worktree] Rejected symlinked target file: ${file}`)

continue

}

// Copy file

await Bun.write(targetPath, sourceFile)

log.info(`[worktree] Copied: ${file}`)

} catch (error) {

const isNotFound =

error instanceof Error &&

(error.message.includes("ENOENT") || error.message.includes("no such file"))

if (isNotFound) {

log.debug(`[worktree] Skipping missing: ${file}`)

} else {

log.warn(`[worktree] Failed to copy ${file}: ${error}`)

}

}

}

sourceDir: string,

targetDir: string,

dirs: string[],

log: Logger,

): Promise<void> {

for (const dir of dirs) {

if (!isPathSafe(dir, sourceDir, log)) continue

const sourcePath = await resolveExistingPathWithinRoot(sourceDir, dir, log)

if (!sourcePath) continue