@gajae-code/coding-agent 0.2.5 → 0.3.0

package/src/gjc-runtime/workflow-manifest.ts

@@ -0,0 +1,425 @@
+/**
+ * TypeScript is the authoritative source of truth for GJC workflow manifests.
+ * Any JSON manifest projection is derived from this module and must never be
+ * hand-edited.
+ */
+
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/active-state";
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
+
+export interface WorkflowState {
+	id: string;
+	initial?: boolean;
+	terminal?: boolean;
+}
+
+export interface WorkflowTransition {
+	from: string;
+	to: string;
+	verb: string;
+}
+
+export interface WorkflowVerb {
+	name: string;
+	planned?: boolean;
+	/** Invocation surface that exposes this verb in the real CLI parser. */
+	surface?: "state-action" | "command-positional" | "command-flag";
+}
+
+export interface TypedArgSpec {
+	name: string;
+	type: "string" | "number" | "boolean" | "enum" | "object";
+	enumValues?: string[];
+	required?: boolean;
+	appliesToVerbs?: string[];
+	planned?: boolean;
+}
+
+export interface RetentionPolicy {
+	category: string;
+	keep?: number;
+	maxAgeDays?: number;
+}
+
+export interface SkillManifest {
+	skill: CanonicalGjcWorkflowSkill;
+	states: WorkflowState[];
+	initialState: string;
+	terminalStates: string[];
+	transitions: WorkflowTransition[];
+	verbs: WorkflowVerb[];
+	typedArgs: TypedArgSpec[];
+	retention: RetentionPolicy[];
+	hudFields: string[];
+	graphLabel: string;
+}
+
+const STATE_RETENTION: RetentionPolicy = { category: "state", keep: 1 };
+const ARTIFACT_RETENTION: RetentionPolicy = { category: "artifact" };
+const LEDGER_RETENTION: RetentionPolicy = { category: "ledger" };
+const LOG_RETENTION: RetentionPolicy = { category: "log", maxAgeDays: 30 };
+const REPORT_RETENTION: RetentionPolicy = { category: "report", maxAgeDays: 30 };
+const AGENTS_RETENTION: RetentionPolicy = { category: "agents" };
+const PRUNE_RETENTION: RetentionPolicy = { category: "prune/delete", maxAgeDays: 30 };
+const FORCE_RETENTION: RetentionPolicy = { category: "force", maxAgeDays: 90 };
+
+const STATE_VERBS = ["read", "write", "clear", "contract", "handoff"] as const;
+const PLANNED_ADMIN_VERBS = ["graph", "prune", "migrate", "force-overwrite"] as const;
+
+const COMMON_TYPED_ARGS: TypedArgSpec[] = [
+	{ name: "input", type: "string", appliesToVerbs: ["write", "api"] },
+	{ name: "mode", type: "enum", enumValues: [...CANONICAL_GJC_WORKFLOW_SKILLS], appliesToVerbs: [...STATE_VERBS] },
+	{ name: "session-id", type: "string", appliesToVerbs: [...STATE_VERBS, "kickoff", "write-spec", "write-artifact"] },
+	{ name: "thread-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
+	{ name: "turn-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
+	{
+		name: "to",
+		type: "enum",
+		enumValues: [...CANONICAL_GJC_WORKFLOW_SKILLS],
+		required: true,
+		appliesToVerbs: ["handoff"],
+	},
+	{ name: "replace", type: "boolean", appliesToVerbs: ["write"] },
+	{ name: "force", type: "boolean", appliesToVerbs: ["write", "clear", "handoff"] },
+];
+
+function verb(name: string, surface: WorkflowVerb["surface"]): WorkflowVerb {
+	return { name, surface };
+}
+
+function stateVerbs(): WorkflowVerb[] {
+	return STATE_VERBS.map(name => verb(name, "state-action"));
+}
+
+function positionalVerbs(names: readonly string[]): WorkflowVerb[] {
+	return names.map(name => verb(name, "command-positional"));
+}
+
+function flagVerbs(names: readonly string[]): WorkflowVerb[] {
+	return names.map(name => verb(name, "command-flag"));
+}
+
+function plannedVerbs(names: readonly string[]): WorkflowVerb[] {
+	return names.map(name => ({ ...verb(name, "state-action"), planned: true }));
+}
+
+function state(id: string, initialState: string, terminalStates: readonly string[]): WorkflowState {
+	const entry: WorkflowState = { id };
+	if (id === initialState) entry.initial = true;
+	if (terminalStates.includes(id)) entry.terminal = true;
+	return entry;
+}
+
+function manifest(input: {
+	skill: CanonicalGjcWorkflowSkill;
+	states: string[];
+	terminalStates: string[];
+	transitions: WorkflowTransition[];
+	verbs: WorkflowVerb[];
+	typedArgs?: TypedArgSpec[];
+	retention: RetentionPolicy[];
+	hudFields: string[];
+	graphLabel: string;
+	initialState?: string;
+}): SkillManifest {
+	const staleInitialState = initialPhaseForSkill(input.skill);
+	const initialState = input.initialState ?? staleInitialState;
+	return {
+		skill: input.skill,
+		states: input.states.map(item => state(item, initialState, input.terminalStates)),
+		initialState,
+		terminalStates: input.terminalStates,
+		transitions: input.transitions,
+		verbs: input.verbs,
+		typedArgs: [...COMMON_TYPED_ARGS, ...(input.typedArgs ?? [])],
+		retention: input.retention,
+		hudFields: input.hudFields,
+		graphLabel: input.graphLabel,
+	};
+}
+
+export const WORKFLOW_MANIFEST: Record<CanonicalGjcWorkflowSkill, SkillManifest> = {
+	"deep-interview": manifest({
+		skill: "deep-interview",
+		states: ["interviewing", "handoff", "complete"],
+		terminalStates: ["handoff", "complete"],
+		transitions: [
+			{ from: "interviewing", to: "handoff", verb: "write-spec" },
+			{ from: "handoff", to: "complete", verb: "clear" },
+			{ from: "interviewing", to: "complete", verb: "clear" },
+		],
+		verbs: [...stateVerbs(), ...flagVerbs(["kickoff", "write-spec"]), ...plannedVerbs(PLANNED_ADMIN_VERBS)],
+		typedArgs: [
+			{ name: "quick", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "standard", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "deep", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "threshold", type: "number", appliesToVerbs: ["kickoff"] },
+			{ name: "threshold-source", type: "string", appliesToVerbs: ["kickoff"] },
+			{ name: "stage", type: "enum", enumValues: ["final"], appliesToVerbs: ["write-spec"] },
+			{ name: "slug", type: "string", appliesToVerbs: ["write-spec"] },
+			{ name: "spec", type: "string", required: true, appliesToVerbs: ["write-spec"] },
+			{ name: "handoff", type: "enum", enumValues: ["ralplan"], appliesToVerbs: ["write-spec"] },
+			{ name: "deliberate", type: "boolean", appliesToVerbs: ["write-spec"] },
+			{ name: "json", type: "boolean", appliesToVerbs: ["write-spec"] },
+			{ name: "args", type: "string", planned: true },
+			{ name: "metadata-json", type: "string", planned: true },
+		],
+		retention: [STATE_RETENTION, ARTIFACT_RETENTION, PRUNE_RETENTION, FORCE_RETENTION],
+		hudFields: ["current_phase", "ambiguity_score", "threshold", "spec_slug", "spec_path", "topology"],
+		graphLabel: "Deep Interview",
+	}),
+	ralplan: manifest({
+		skill: "ralplan",
+		states: ["planner", "architect", "critic", "revision", "adr", "final", "handoff"],
+		terminalStates: ["final", "handoff"],
+		transitions: [
+			{ from: "planner", to: "architect", verb: "write-artifact" },
+			{ from: "architect", to: "critic", verb: "write-artifact" },
+			{ from: "critic", to: "revision", verb: "write-artifact" },
+			{ from: "revision", to: "adr", verb: "write-artifact" },
+			{ from: "adr", to: "final", verb: "write-artifact" },
+			{ from: "planner", to: "handoff", verb: "handoff" },
+			{ from: "architect", to: "handoff", verb: "handoff" },
+			{ from: "critic", to: "handoff", verb: "handoff" },
+			{ from: "revision", to: "handoff", verb: "handoff" },
+			{ from: "adr", to: "handoff", verb: "handoff" },
+		],
+		verbs: [...stateVerbs(), ...flagVerbs(["kickoff", "write-artifact"]), ...plannedVerbs(PLANNED_ADMIN_VERBS)],
+		typedArgs: [
+			{ name: "interactive", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "deliberate", type: "boolean", appliesToVerbs: ["kickoff"] },
+			{ name: "architect", type: "string", appliesToVerbs: ["kickoff"] },
+			{ name: "critic", type: "string", appliesToVerbs: ["kickoff"] },
+			{ name: "json", type: "boolean", appliesToVerbs: ["kickoff", "write-artifact"] },
+			{
+				name: "stage",
+				type: "enum",
+				enumValues: ["planner", "architect", "critic", "revision", "adr", "final"],
+				appliesToVerbs: ["write-artifact"],
+			},
+			{ name: "stage_n", type: "number", appliesToVerbs: ["write-artifact"] },
+			{ name: "artifact", type: "string", required: true, appliesToVerbs: ["write-artifact"] },
+			{ name: "run-id", type: "string", appliesToVerbs: ["write-artifact"] },
+			{ name: "args", type: "string", planned: true },
+			{ name: "metadata-json", type: "string", planned: true },
+		],
+		retention: [STATE_RETENTION, ARTIFACT_RETENTION, LEDGER_RETENTION, PRUNE_RETENTION, FORCE_RETENTION],
+		hudFields: ["current_phase", "mode", "run_id", "stage", "stage_n", "plan_path"],
+		graphLabel: "Ralplan",
+	}),
+	ultragoal: manifest({
+		skill: "ultragoal",
+		states: ["goal-planning", "pending", "active", "blocked", "failed", "complete", "handoff"],
+		terminalStates: ["failed", "complete", "handoff"],
+		transitions: [
+			{ from: "goal-planning", to: "pending", verb: "create-goals" },
+			{ from: "pending", to: "active", verb: "complete-goals" },
+			{ from: "active", to: "blocked", verb: "checkpoint" },
+			{ from: "active", to: "failed", verb: "checkpoint" },
+			{ from: "active", to: "complete", verb: "checkpoint" },
+			{ from: "blocked", to: "active", verb: "checkpoint" },
+			{ from: "failed", to: "active", verb: "complete-goals" },
+			{ from: "goal-planning", to: "handoff", verb: "handoff" },
+			{ from: "pending", to: "handoff", verb: "handoff" },
+			{ from: "active", to: "handoff", verb: "handoff" },
+			{ from: "blocked", to: "handoff", verb: "handoff" },
+		],
+		verbs: [
+			...stateVerbs(),
+			...positionalVerbs([
+				"status",
+				"create",
+				"create-goals",
+				"complete-goals",
+				"checkpoint",
+				"record-review-blockers",
+				"steer",
+			]),
+			...plannedVerbs(PLANNED_ADMIN_VERBS),
+		],
+		typedArgs: [
+			{ name: "brief", type: "string", appliesToVerbs: ["create-goals"] },
+			{ name: "brief-file", type: "string", appliesToVerbs: ["create-goals"] },
+			{ name: "from-stdin", type: "boolean", appliesToVerbs: ["create-goals"] },
+			{
+				name: "gjc-goal-mode",
+				type: "enum",
+				enumValues: ["aggregate", "per-story"],
+				appliesToVerbs: ["create-goals"],
+			},
+			{ name: "retry-failed", type: "boolean", appliesToVerbs: ["complete-goals"] },
+			{ name: "goal-id", type: "string", required: true, appliesToVerbs: ["checkpoint", "record-review-blockers"] },
+			{
+				name: "status",
+				type: "enum",
+				enumValues: ["pending", "active", "complete", "failed", "blocked", "review_blocked", "superseded"],
+				required: true,
+				appliesToVerbs: ["checkpoint"],
+			},
+			{
+				name: "evidence",
+				type: "string",
+				required: true,
+				appliesToVerbs: ["checkpoint", "record-review-blockers", "steer"],
+			},
+			{ name: "gjc-goal-json", type: "string", appliesToVerbs: ["checkpoint", "record-review-blockers"] },
+			{ name: "quality-gate-json", type: "string", appliesToVerbs: ["checkpoint"] },
+			{ name: "kind", type: "enum", enumValues: ["add_subgoal"], appliesToVerbs: ["steer"] },
+			{ name: "title", type: "string", appliesToVerbs: ["record-review-blockers", "steer"] },
+			{ name: "objective", type: "string", appliesToVerbs: ["record-review-blockers", "steer"] },
+			{ name: "rationale", type: "string", appliesToVerbs: ["steer"] },
+			{
+				name: "json",
+				type: "boolean",
+				appliesToVerbs: [
+					"status",
+					"create-goals",
+					"complete-goals",
+					"checkpoint",
+					"record-review-blockers",
+					"steer",
+				],
+			},
+			{ name: "directive-json", type: "string", appliesToVerbs: ["steer"], planned: true },
+			{ name: "args", type: "string", planned: true },
+			{ name: "metadata-json", type: "string", planned: true },
+		],
+		retention: [STATE_RETENTION, ARTIFACT_RETENTION, LEDGER_RETENTION, PRUNE_RETENTION, FORCE_RETENTION],
+		hudFields: ["current_phase", "active_goal_id", "status", "counts", "ledger_path", "brief_path"],
+		graphLabel: "Ultragoal",
+	}),
+	team: manifest({
+		skill: "team",
+		states: ["starting", "running", "awaiting_integration", "complete", "failed", "cancelled", "handoff"],
+		terminalStates: ["complete", "failed", "cancelled", "handoff"],
+		transitions: [
+			{ from: "starting", to: "running", verb: "start" },
+			{ from: "starting", to: "failed", verb: "start" },
+			{ from: "running", to: "awaiting_integration", verb: "api" },
+			{ from: "running", to: "complete", verb: "shutdown" },
+			{ from: "running", to: "failed", verb: "shutdown" },
+			{ from: "running", to: "cancelled", verb: "shutdown" },
+			{ from: "awaiting_integration", to: "running", verb: "resume" },
+			{ from: "awaiting_integration", to: "complete", verb: "shutdown" },
+			{ from: "starting", to: "handoff", verb: "handoff" },
+			{ from: "running", to: "handoff", verb: "handoff" },
+			{ from: "awaiting_integration", to: "handoff", verb: "handoff" },
+		],
+		verbs: [
+			...stateVerbs(),
+			...positionalVerbs(["start", "list", "status", "monitor", "resume", "shutdown", "api"]),
+			...plannedVerbs(PLANNED_ADMIN_VERBS),
+		],
+		typedArgs: [
+			{ name: "dry-run", type: "boolean", appliesToVerbs: ["start"] },
+			{ name: "worktree", type: "string", appliesToVerbs: ["start"] },
+			{ name: "w", type: "string", appliesToVerbs: ["start"] },
+			{ name: "input", type: "string", required: true, appliesToVerbs: ["api"] },
+			{
+				name: "operation",
+				type: "enum",
+				enumValues: [
+					"send-message",
+					"broadcast",
+					"mailbox-list",
+					"mailbox-mark-delivered",
+					"mailbox-mark-notified",
+					"notification-list",
+					"notification-read",
+					"notification-replay",
+					"notification-mark-pane-attempt",
+					"worker-startup-ack",
+					"create-task",
+					"read-task",
+					"list-tasks",
+					"update-task",
+					"claim-task",
+					"transition-task-status",
+					"transition-task",
+					"release-task-claim",
+					"read-config",
+					"read-manifest",
+					"read-worker-status",
+					"read-worker-heartbeat",
+					"update-worker-heartbeat",
+					"write-worker-inbox",
+					"write-worker-identity",
+					"append-event",
+					"read-events",
+					"await-event",
+					"write-shutdown-request",
+					"read-shutdown-ack",
+					"read-monitor-snapshot",
+					"write-monitor-snapshot",
+					"read-task-approval",
+					"write-task-approval",
+				],
+				required: true,
+				appliesToVerbs: ["api"],
+			},
+			{ name: "worker-id", type: "string", appliesToVerbs: ["api"] },
+			{ name: "task-id", type: "string", appliesToVerbs: ["api"] },
+			{ name: "claim-token", type: "string", appliesToVerbs: ["api"] },
+			{
+				name: "status",
+				type: "enum",
+				enumValues: ["pending", "blocked", "in_progress", "completed", "failed"],
+				appliesToVerbs: ["api"],
+			},
+			{ name: "completion_evidence", type: "object", appliesToVerbs: ["api"] },
+			{ name: "completionEvidence", type: "object", appliesToVerbs: ["api"] },
+			{ name: "args", type: "string", planned: true },
+			{ name: "metadata-json", type: "string", planned: true },
+		],
+		retention: [
+			STATE_RETENTION,
+			ARTIFACT_RETENTION,
+			LEDGER_RETENTION,
+			LOG_RETENTION,
+			REPORT_RETENTION,
+			AGENTS_RETENTION,
+			PRUNE_RETENTION,
+			FORCE_RETENTION,
+		],
+		hudFields: ["current_phase", "team_name", "workers", "task_counts", "phase", "integration"],
+		graphLabel: "Team",
+	}),
+};
+
+export function getSkillManifest(skill: CanonicalGjcWorkflowSkill): SkillManifest {
+	return WORKFLOW_MANIFEST[skill];
+}
+
+export function isKnownWorkflowState(skill: CanonicalGjcWorkflowSkill, state: string): boolean {
+	return WORKFLOW_MANIFEST[skill].states.some(entry => entry.id === state);
+}
+
+export function isValidTransition(skill: CanonicalGjcWorkflowSkill, from: string, to: string): boolean {
+	if (from === to) return true;
+	return WORKFLOW_MANIFEST[skill].transitions.some(transition => transition.from === from && transition.to === to);
+}
+
+export function listVerbs(skill: CanonicalGjcWorkflowSkill): string[] {
+	return WORKFLOW_MANIFEST[skill].verbs.map(verb => verb.name);
+}
+
+export function typedArgsFor(skill: CanonicalGjcWorkflowSkill, verb: string): TypedArgSpec[] {
+	return WORKFLOW_MANIFEST[skill].typedArgs.filter(
+		arg => arg.appliesToVerbs === undefined || arg.appliesToVerbs.includes(verb),
+	);
+}
+
+function stableSort(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(item => stableSort(item));
+	if (value === null || typeof value !== "object") return value;
+	return Object.fromEntries(
+		Object.entries(value)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, item]) => [key, stableSort(item)]),
+	);
+}
+
+export function serializeManifestProjection(): string {
+	return `${JSON.stringify(stableSort(WORKFLOW_MANIFEST), null, 2)}\n`;
+}

package/src/harness-control-plane/classifier.ts

@@ -0,0 +1,128 @@
+/**
+ * Deterministic recovery classifier (pure).
+ *
+ * Maps a bounded {@link Observation} + remaining retry budget to exactly one
+ * {@link RecoveryDecision}. Encodes the plan's hard data-loss invariants:
+ *   - dirty deltas are NEVER `restart-clean`; they map to `restart-preserve-delta`.
+ *   - unknown deltas are NEVER destructive; they map to `human-check`.
+ *   - a deleted/mismatched worktree maps to `human-check` (never recreate over unknown data).
+ * `send-enter` is intentionally never emitted: it is unsupported for the gajae-code
+ * RPC adapter in v1 (no blind key injection).
+ */
+import type { ClassifyInput, RecoveryDecision } from "./types";
+
+export function classifyRecovery(input: ClassifyInput): RecoveryDecision {
+	const { observation: o, retryBudget: budget } = input;
+
+	// Deleted worktree / path mismatch — never recreate over unknown data.
+	if (o.risk === "deleted-worktree") {
+		return {
+			classification: "human-check",
+			reason: "deleted-worktree-or-path-mismatch",
+			severity: "critical",
+			ownerRequired: false,
+			requiredReceiptFamily: "vanish",
+		};
+	}
+
+	if (o.ownerLive) {
+		if (o.risk === "prompt-not-accepted") {
+			if (budget.reinjectPrompt > 0) {
+				return {
+					classification: "reinject-prompt",
+					reason: "prompt-ack-without-agent-start",
+					severity: "warn",
+					ownerRequired: true,
+					requiredReceiptFamily: "prompt-acceptance",
+				};
+			}
+			return {
+				classification: "human-check",
+				reason: "prompt-not-accepted-budget-exhausted",
+				severity: "critical",
+				ownerRequired: false,
+				requiredReceiptFamily: null,
+			};
+		}
+		if (o.observedSignals.includes("validation-failed")) {
+			if (budget.validationRepair > 0) {
+				return {
+					classification: "continue",
+					reason: "validation-failed-repair-budget-remains",
+					severity: "warn",
+					ownerRequired: true,
+					requiredReceiptFamily: "validation",
+				};
+			}
+			return {
+				classification: "human-check",
+				reason: "validation-failed-budget-exhausted",
+				severity: "critical",
+				ownerRequired: false,
+				requiredReceiptFamily: "validation",
+			};
+		}
+		return {
+			classification: "continue",
+			reason: "owner-live-active",
+			severity: "info",
+			ownerRequired: true,
+			requiredReceiptFamily: null,
+		};
+	}
+
+	// Owner / RPC vanished — branch on git delta. Every branch requires a `vanish` receipt.
+	switch (o.gitDelta) {
+		case "dirty":
+			if (budget.dirtyVanishPreserve > 0) {
+				return {
+					classification: "restart-preserve-delta",
+					reason: "owner-vanished-dirty-delta",
+					severity: "critical",
+					ownerRequired: true,
+					requiredReceiptFamily: "vanish",
+				};
+			}
+			return {
+				classification: "fallback-codex-exec",
+				reason: "dirty-vanish-preserve-budget-exhausted",
+				severity: "critical",
+				ownerRequired: true,
+				requiredReceiptFamily: "vanish",
+			};
+		case "zero-delta":
+			if (budget.zeroDeltaVanish > 0) {
+				return {
+					classification: "restart-clean",
+					reason: "owner-vanished-zero-delta",
+					severity: "warn",
+					ownerRequired: true,
+					requiredReceiptFamily: "vanish",
+				};
+			}
+			return {
+				classification: "fallback-codex-exec",
+				reason: "zero-delta-vanish-budget-exhausted",
+				severity: "critical",
+				ownerRequired: true,
+				requiredReceiptFamily: "vanish",
+			};
+		case "clean":
+			return {
+				classification: "restart-clean",
+				reason: "owner-vanished-clean",
+				severity: "warn",
+				ownerRequired: true,
+				requiredReceiptFamily: "vanish",
+			};
+		default:
+			// unknown delta — critical, never destructive.
+			return {
+				classification: "human-check",
+				reason: "owner-vanished-unknown-delta",
+				severity: "critical",
+				ownerRequired: false,
+				requiredReceiptFamily: "vanish",
+			};
+	}
+}

package/src/harness-control-plane/control-endpoint.ts

@@ -0,0 +1,137 @@
+/**
+ * Per-session control endpoint — a Unix domain socket served by the RuntimeOwner so
+ * stateless `gjc harness` CLI calls can route owner-routed primitives (submit, observe,
+ * recover, retire) to the live owner. One JSON request line in, one JSON response line out.
+ *
+ * The owner is the only listener; clients connect per call. When no socket is reachable
+ * the caller falls back to the no-owner behavior (read-only observe, owner-not-live submit).
+ *
+ * FIFO fallback (for platforms/paths where AF_UNIX is unavailable or path-length limited)
+ * is a documented seam tracked as an ADR follow-up.
+ */
+
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as path from "node:path";
+import { MAX_UNIX_SOCKET_PATH_BYTES } from "./storage";
+
+export interface EndpointRequest {
+	verb: string;
+	input: Record<string, unknown>;
+}
+
+export type EndpointHandler = (req: EndpointRequest) => Promise<unknown>;
+
+function frame(value: unknown): string {
+	return `${JSON.stringify(value)}\n`;
+}
+
+export class ControlServer {
+	#server: net.Server | null = null;
+	constructor(
+		readonly socketPath: string,
+		private readonly handler: EndpointHandler,
+	) {}
+
+	async listen(): Promise<void> {
+		await fs.mkdir(path.dirname(this.socketPath), { recursive: true });
+		if (Buffer.byteLength(this.socketPath) > MAX_UNIX_SOCKET_PATH_BYTES) {
+			throw new Error(`socket_path_too_long:${this.socketPath}`);
+		}
+		await fs.rm(this.socketPath, { force: true });
+		await new Promise<void>((resolve, reject) => {
+			const server = net.createServer(socket => this.#onConnection(socket));
+			server.once("error", reject);
+			server.listen(this.socketPath, () => {
+				server.removeListener("error", reject);
+				this.#server = server;
+				resolve();
+			});
+		});
+	}
+
+	#onConnection(socket: net.Socket): void {
+		socket.setEncoding("utf8");
+		let buffer = "";
+		let handled = false;
+		socket.on("data", (chunk: string) => {
+			if (handled) return;
+			buffer += chunk;
+			const idx = buffer.indexOf("\n");
+			if (idx < 0) return;
+			handled = true;
+			const line = buffer.slice(0, idx).trim();
+			void this.#dispatch(line)
+				.then(response => {
+					socket.end(frame(response));
+				})
+				.catch((error: unknown) => {
+					socket.end(frame({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+				});
+		});
+	}
+
+	async #dispatch(line: string): Promise<unknown> {
+		const req = JSON.parse(line) as EndpointRequest;
+		if (!req || typeof req.verb !== "string") throw new Error("bad_request");
+		return this.handler({ verb: req.verb, input: req.input ?? {} });
+	}
+
+	async close(): Promise<void> {
+		const server = this.#server;
+		this.#server = null;
+		if (server) {
+			await new Promise<void>(resolve => server.close(() => resolve()));
+		}
+		await fs.rm(this.socketPath, { force: true });
+	}
+}
+
+export class EndpointUnreachableError extends Error {
+	constructor(readonly socketPath: string) {
+		super(`endpoint_unreachable:${socketPath}`);
+		this.name = "EndpointUnreachableError";
+	}
+}
+
+/** Call the owner's control endpoint. Rejects with {@link EndpointUnreachableError} when no owner listens. */
+export function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs = 5_000): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		const socket = net.connect(socketPath);
+		let buffer = "";
+		let settled = false;
+		const done = (fn: () => void): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			fn();
+		};
+		const timer = setTimeout(() => done(() => reject(new Error(`endpoint_timeout:${socketPath}`))), timeoutMs);
+		socket.setEncoding("utf8");
+		socket.on("connect", () => socket.write(frame(req)));
+		socket.on("data", (chunk: string) => {
+			buffer += chunk;
+			const idx = buffer.indexOf("\n");
+			if (idx >= 0) {
+				const line = buffer.slice(0, idx).trim();
+				done(() => {
+					try {
+						resolve(JSON.parse(line));
+					} catch (error) {
+						reject(error instanceof Error ? error : new Error(String(error)));
+					}
+				});
+			}
+		});
+		socket.on("error", (error: NodeJS.ErrnoException) => {
+			done(() => {
+				if (error.code === "ENOENT" || error.code === "ECONNREFUSED") {
+					reject(new EndpointUnreachableError(socketPath));
+				} else {
+					reject(error);
+				}
+			});
+		});
+	});
+}