feat(tui): register launch directory instances

Made-with: Cursor

Author: chenxin-yan

apps/tui/src/index.tsx

@@ -2,6 +2,7 @@ import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { App } from "./components/app";
 import { OnboardingError } from "./components/onboarding";
+import { ensureDirectoryInstance } from "./lib/instance";
 import { runOnboardingChecks } from "./lib/onboarding";
 
 const runtime = {
@@ -33,6 +34,7 @@ export async function runTui(): Promise<void> {
 	};
 
 	if (onboarding.ok) {
+		await ensureDirectoryInstance();
 		root.render(<App onQuit={close} />);
 	} else {
 		root.render(<OnboardingError checks={onboarding.checks} onQuit={close} />);

apps/tui/src/lib/instance.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { basename, resolve } from "node:path";
+import type { ManagedInstance } from "@techatnyu/ralphd";
+import { ensureDirectoryInstance } from "./instance";
+
+function instance(overrides: Partial<ManagedInstance>): ManagedInstance {
+	const now = new Date("2026-01-01T00:00:00.000Z").toISOString();
+	return {
+		id: "instance-1",
+		name: "project",
+		directory: "/tmp/project",
+		status: "stopped",
+		maxConcurrency: 1,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	};
+}
+
+describe("ensureDirectoryInstance", () => {
+	test("returns an existing instance for the launch directory", async () => {
+		const cwd = resolve("/tmp/project");
+		const existing = instance({ directory: cwd });
+		let creates = 0;
+
+		const result = await ensureDirectoryInstance(cwd, {
+			listInstances: async () => ({ instances: [existing] }),
+			createInstance: async () => {
+				creates += 1;
+				return { instance: existing };
+			},
+		});
+
+		expect(result).toBe(existing);
+		expect(creates).toBe(0);
+	});
+
+	test("creates an instance named after the launch directory", async () => {
+		const cwd = resolve("/tmp/project-two");
+		let createInput:
+			| { name: string; directory: string; maxConcurrency?: number }
+			| undefined;
+		const created = instance({
+			id: "instance-2",
+			name: basename(cwd),
+			directory: cwd,
+		});
+
+		const result = await ensureDirectoryInstance(cwd, {
+			listInstances: async () => ({ instances: [] }),
+			createInstance: async (input) => {
+				createInput = input;
+				return { instance: created };
+			},
+		});
+
+		expect(result).toBe(created);
+		expect(createInput).toEqual({ name: "project-two", directory: cwd });
+	});
+});

apps/tui/src/lib/instance.ts

@@ -0,0 +1,56 @@
+import { basename, resolve } from "node:path";
+import type { ManagedInstance } from "@techatnyu/ralphd";
+import { daemon } from "@techatnyu/ralphd";
+
+type InstanceClient = {
+	listInstances(): Promise<{ instances: ManagedInstance[] }>;
+	createInstance(input: {
+		name: string;
+		directory: string;
+		maxConcurrency?: number;
+	}): Promise<{ instance: ManagedInstance }>;
+};
+
+function instanceNameForDirectory(directory: string): string {
+	return basename(directory) || directory;
+}
+
+async function findInstanceByDirectory(
+	client: InstanceClient,
+	directory: string,
+): Promise<ManagedInstance | undefined> {
+	const result = await client.listInstances();
+	return result.instances.find(
+		(instance) => resolve(instance.directory) === directory,
+	);
+}
+
+export async function ensureDirectoryInstance(
+	directory = process.cwd(),
+	client: InstanceClient = daemon,
+): Promise<ManagedInstance> {
+	const normalizedDirectory = resolve(directory);
+	const existing = await findInstanceByDirectory(client, normalizedDirectory);
+	if (existing) {
+		return existing;
+	}
+
+	try {
+		const created = await client.createInstance({
+			name: instanceNameForDirectory(normalizedDirectory),
+			directory: normalizedDirectory,
+		});
+		return created.instance;
+	} catch (error) {
+		const code = (error as { code?: string } | undefined)?.code;
+		if (code !== "conflict") {
+			throw error;
+		}
+
+		const raced = await findInstanceByDirectory(client, normalizedDirectory);
+		if (raced) {
+			return raced;
+		}
+		throw error;
+	}
+}