@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/cli/doctor/plugin-targets.ts

@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getPluginsDir, getPluginsLockfile, getProjectPluginOverridesPath } from "@gajae-code/utils";
+import { resolveOrDefaultProjectRegistryPath } from "../../discovery/helpers";
+import { GJC_BUNDLE_KIND, type LocalRestorePlanV1 } from "../../extensibility/gjc-plugins/types";
+import {
+	getInstalledPluginsRegistryPath,
+	getMarketplacesCacheDir,
+	getMarketplacesRegistryPath,
+	getPluginsCacheDir,
+	MarketplaceManager,
+} from "../../extensibility/plugins/marketplace/index.js";
+import type { MarketplaceRestorePlanV1 } from "../../extensibility/plugins/marketplace/manager";
+import { sourcePin } from "../../extensibility/plugins/marketplace/source-resolver";
+import { doctorCheck } from "./checks";
+import type { DoctorConfigSource, DoctorContext } from "./context";
+import { type DoctorFileObservation, doctorMapping, readDoctorFile } from "./files";
+import { pluginTargetId } from "./ids";
+import { type PluginQuarantinePlan, previewPluginQuarantine } from "./plugin-quarantine";
+import { runPluginRestoreAction } from "./plugin-restore";
+import type { DoctorCheck } from "./types";
+
+/**
+ * Construct the marketplace manager exactly as the ordinary plugin CLI does, so
+ * doctor reads and repairs the same canonical registries and cache roots the
+ * product itself owns. Never a doctor-private layout.
+ */
+export async function createDoctorMarketplaceManager(cwd: string): Promise<MarketplaceManager> {
+	return new MarketplaceManager({
+		marketplacesRegistryPath: getMarketplacesRegistryPath(),
+		installedRegistryPath: getInstalledPluginsRegistryPath(),
+		projectInstalledRegistryPath: await resolveOrDefaultProjectRegistryPath(cwd),
+		marketplacesCacheDir: getMarketplacesCacheDir(),
+		pluginsCacheDir: getPluginsCacheDir(),
+	});
+}
+
+/**
+ * The immutable commit the private-marketplace catalog records for this plugin.
+ * Uses the product's own pin resolver so doctor and the restore lane agree on
+ * what counts as immutable; a mutable source yields no pin and stays
+ * unauthorizable.
+ */
+function marketplacePin(plan: MarketplaceRestorePlanV1 | undefined): string | undefined {
+	if (!plan) return undefined;
+	const pin = sourcePin(plan.source);
+	return pin.immutable ? pin.sha : undefined;
+}
+
+type Family = "gjc" | "npm" | "marketplace";
+interface PluginEntry {
+	readonly name: string;
+	readonly enabled: unknown;
+	readonly restoreRef?: string;
+	readonly restoreArtifactDigest?: string;
+}
+
+/**
+ * Stable artifact-tree digest of the recorded bundle: sorted relative path plus
+ * per-file content hash, exactly the shape the restore lifecycle recomputes from
+ * the resolved source. Derived only from already-read registry metadata, so it
+ * remains identical across runs and can be authorized before any effect.
+ */
+function storedArtifactDigest(entry: Record<string, unknown>): string | undefined {
+	const files = entry.copiedFiles;
+	if (!Array.isArray(files) || files.length === 0 || files.length > 10_000) return undefined;
+	const rows: Array<readonly [string, string]> = [];
+	for (const raw of files) {
+		const file = doctorMapping(raw);
+		if (
+			!file ||
+			typeof file.relativePath !== "string" ||
+			typeof file.sha256 !== "string" ||
+			!/^[0-9a-f]{64}$/.test(file.sha256)
+		)
+			return undefined;
+		rows.push([file.relativePath, file.sha256]);
+	}
+	const hash = createHash("sha256");
+	for (const [relativePath, sha256] of rows.sort((a, b) => a[0].localeCompare(b[0]))) {
+		hash.update(relativePath);
+		hash.update("\0");
+		hash.update(sha256);
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+/**
+ * Immutable `--ref` a restore must be pinned to, derived only from the already-read
+ * registry record. Never resolves, fetches, or inspects the source itself; a source
+ * that carries no immutable identity yields no pin, so restore stays unauthorizable.
+ */
+function storedRestoreRef(entry: Record<string, unknown>): string | undefined {
+	const source = doctorMapping(entry.source);
+	if (!source) return undefined;
+	if (source.kind === "git")
+		return typeof source.sha === "string" && /^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(source.sha)
+			? source.sha
+			: undefined;
+	if (source.kind === "path")
+		return typeof entry.manifestHash === "string" && /^[0-9a-f]{64}$/.test(entry.manifestHash)
+			? `local:${entry.manifestHash}`
+			: undefined;
+	if (source.kind === "tarball")
+		return typeof entry.version === "string" && entry.version.length > 0 && entry.version.length <= 128
+			? `version:${entry.version}`
+			: undefined;
+	return undefined;
+}
+
+function registryFailure(
+	source: DoctorConfigSource,
+	family: Family,
+	observation: DoctorFileObservation,
+	malformed = false,
+): DoctorCheck {
+	return doctorCheck(
+		`plugin.${family}.${source.scope}.registry`,
+		`t1:plugin-registry:${source.root.rootId}:${family}:${source.scope}`,
+		{
+			scope: source.scope,
+			execution: malformed || observation.status === "missing" ? "completed" : "blocked",
+			health: malformed ? "error" : observation.status === "missing" ? "not_applicable" : "unknown",
+			evidenceLevel: "observed",
+			reasonCode: malformed ? "plugin_registry_invalid" : `plugin_registry_${observation.status}`,
+			evidence: {
+				present: observation.status === "read",
+				runtimeProbed: false,
+				...("errno" in observation ? { errno: observation.errno } : {}),
+			},
+		},
+	);
+}
+
+function parse(observation: DoctorFileObservation): Record<string, unknown> | undefined {
+	if (observation.status !== "read") return undefined;
+	try {
+		return doctorMapping(JSON.parse(observation.text));
+	} catch {
+		return undefined;
+	}
+}
+
+async function addEntries(
+	context: DoctorContext,
+	source: DoctorConfigSource,
+	family: Family,
+	entries: readonly PluginEntry[],
+	checks: DoctorCheck[],
+	registryPath?: string,
+): Promise<void> {
+	if (entries.length > 1000)
+		checks.push(
+			doctorCheck(
+				`plugin.${family}.${source.scope}.coverage`,
+				`t1:plugin-registry:${source.root.rootId}:${family}:${source.scope}`,
+				{
+					scope: source.scope,
+					execution: "blocked",
+					health: "unknown",
+					evidenceLevel: "observed",
+					reasonCode: "limit_exceeded",
+					evidence: { count: 1000 },
+				},
+			),
+		);
+	for (const entry of entries.slice(0, 1000)) {
+		if (!entry.name || entry.name.length > 256) continue;
+		const targetId = pluginTargetId(source.root.rootId, family, source.scope, entry.name);
+		let quarantinePlan: PluginQuarantinePlan | undefined;
+		if (context.options.repair === "plugin.quarantine-selected" && context.options.targetId === targetId) {
+			quarantinePlan = await previewPluginQuarantine({
+				family,
+				scope: source.scope,
+				name: entry.name,
+				cwd: context.cwd,
+				home: os.homedir(),
+				rootId: source.root.rootId,
+				registryPath,
+			});
+		}
+		// Read-only observation only: preview never resolves a source, fetches, stages, or writes.
+		let restorePlan: LocalRestorePlanV1 | undefined;
+		if (
+			family === "gjc" &&
+			entry.restoreRef &&
+			entry.restoreArtifactDigest &&
+			context.options.repair === "plugin.restore-known-artifact" &&
+			context.options.targetId === targetId
+		) {
+			const preview = await runPluginRestoreAction({
+				kind: "preview",
+				target: { identity: { kind: GJC_BUNDLE_KIND, scope: source.scope, name: entry.name }, cwd: context.cwd },
+			});
+			if ("ok" in preview && preview.ok && "value" in preview) {
+				const value = preview.value;
+				if (
+					typeof value === "object" &&
+					value !== null &&
+					"kind" in value &&
+					value.kind === "gjc-plugin.restore-artifact" &&
+					"artifact" in value
+				)
+					restorePlan = value;
+			}
+		}
+		// Private-marketplace lane: the same read-only preview contract. It reads the
+		// installed registry, the marketplace catalog and the cached artifact; it never
+		// resolves a source, fetches, stages, or writes.
+		let marketplaceRestorePlan: MarketplaceRestorePlanV1 | undefined;
+		if (
+			family === "marketplace" &&
+			context.options.repair === "plugin.restore-known-artifact" &&
+			context.options.targetId === targetId
+		) {
+			try {
+				const preview = await runPluginRestoreAction({
+					kind: "marketplace-preview",
+					manager: await createDoctorMarketplaceManager(context.cwd),
+					pluginId: entry.name,
+					scope: source.scope,
+				});
+				if (
+					typeof preview === "object" &&
+					preview !== null &&
+					"kind" in preview &&
+					preview.kind === "marketplace-plugin.restore-artifact" &&
+					"artifact" in preview
+				)
+					marketplaceRestorePlan = preview;
+			} catch {
+				// A refused preview leaves the target unrepairable rather than guessing a plan.
+			}
+		}
+		context.targets.set(targetId, {
+			kind: "plugin",
+			targetId,
+			family,
+			scope: source.scope,
+			name: entry.name,
+			root: source.root,
+			quarantinePlan,
+			restorePlan,
+			marketplaceRestorePlan,
+			// The marketplace pin is the catalog's recorded immutable commit, observed
+			// read-only during preview. A version alone is a moving selector and must
+			// never authorize a restore.
+			restoreRef: entry.restoreRef ?? marketplacePin(marketplaceRestorePlan),
+			// For the marketplace family the pin is the CATALOG fingerprint, never the
+			// installed artifact's digest: the artifact is the thing being repaired, so
+			// pinning it would make an absent or unreadable tree — D6's whole purpose —
+			// permanently unrepairable, and would authorize the damaged bytes rather
+			// than the intended ones. The candidate bytes are still bound: the apply
+			// path independently recomputes the resolved source digest.
+			restoreArtifactDigest: entry.restoreArtifactDigest ?? marketplaceRestorePlan?.catalogFingerprint,
+			registryPath,
+		});
+		const valid = entry.enabled === undefined || typeof entry.enabled === "boolean";
+		checks.push(
+			doctorCheck(`plugin.${family}.${source.scope}.${targetId.split(":").at(-1)}`, targetId, {
+				scope: source.scope,
+				execution: "completed",
+				health: valid ? "ok" : "error",
+				evidenceLevel: "observed",
+				reasonCode: valid ? "plugin_registry_entry_observed" : "plugin_enabled_invalid",
+				evidence: {
+					enabled: quarantinePlan?.enabled ?? entry.enabled !== false,
+					sourceClass: family,
+					runtimeProbed: false,
+					...(restorePlan ? { artifactStatus: restorePlan.artifact.status } : {}),
+					...(marketplaceRestorePlan ? { artifactStatus: marketplaceRestorePlan.artifact.status } : {}),
+				},
+				remediationIds: ["plugin.quarantine-selected", "plugin.restore-known-artifact"],
+			}),
+		);
+	}
+}
+
+/** Inventory only: registry data is read, never source-resolved or executed. */
+export async function collectPluginTargets(context: DoctorContext): Promise<DoctorCheck[]> {
+	const checks: DoctorCheck[] = [];
+	const npm = await readDoctorFile(getPluginsLockfile());
+	const npmRegistry = parse(npm);
+	const npmPlugins = doctorMapping(npmRegistry?.plugins);
+	const marketplacePath = path.join(getPluginsDir(), "installed_plugins.json");
+	const marketplace = await readDoctorFile(marketplacePath);
+	const marketplaceRegistry = parse(marketplace);
+	const marketplacePlugins = doctorMapping(marketplaceRegistry?.plugins);
+	for (const source of context.sources) {
+		// Same canonical layout as registryPathForScope; keep this collector free
+		// of installer/compiler imports so broken native code cannot block it.
+		const gjc = await readDoctorFile(path.join(source.root.locator, "gjc-plugins", "registry.json"));
+		const registry = parse(gjc);
+		if (gjc.status !== "read") checks.push(registryFailure(source, "gjc", gjc));
+		else if (registry?.version !== 1 || registry.scope !== source.scope || !Array.isArray(registry.plugins))
+			checks.push(registryFailure(source, "gjc", gjc, true));
+		else {
+			const entries: PluginEntry[] = [];
+			let malformed = false;
+			for (const raw of registry.plugins) {
+				const entry = doctorMapping(raw);
+				if (!entry || typeof entry.name !== "string" || entry.scope !== source.scope) {
+					malformed = true;
+					continue;
+				}
+				entries.push({
+					name: entry.name,
+					enabled: entry.enabled,
+					restoreRef: storedRestoreRef(entry),
+					restoreArtifactDigest: storedArtifactDigest(entry),
+				});
+			}
+			if (malformed) checks.push(registryFailure(source, "gjc", gjc, true));
+			await addEntries(context, source, "gjc", entries, checks);
+		}
+		if (npm.status !== "read") checks.push(registryFailure(source, "npm", npm));
+		else if (!npmPlugins) checks.push(registryFailure(source, "npm", npm, true));
+		else {
+			let disabled: readonly unknown[] = [];
+			let validOverrides = true;
+			if (source.scope === "project") {
+				const overrides = await readDoctorFile(getProjectPluginOverridesPath(context.cwd));
+				const parsed = parse(overrides);
+				if (
+					overrides.status !== "missing" &&
+					(overrides.status !== "read" ||
+						!parsed ||
+						(parsed.disabled !== undefined && !Array.isArray(parsed.disabled)))
+				) {
+					checks.push(registryFailure(source, "npm", overrides, overrides.status === "read"));
+					validOverrides = false;
+				} else if (Array.isArray(parsed?.disabled)) disabled = parsed.disabled;
+			}
+			if (validOverrides)
+				await addEntries(
+					context,
+					source,
+					"npm",
+					Object.entries(npmPlugins).map(([name, value]) => ({
+						name,
+						enabled: disabled.includes(name) ? false : doctorMapping(value)?.enabled,
+					})),
+					checks,
+				);
+		}
+		if (marketplace.status !== "read") checks.push(registryFailure(source, "marketplace", marketplace));
+		else if (!marketplacePlugins || marketplaceRegistry?.version !== 2)
+			checks.push(registryFailure(source, "marketplace", marketplace, true));
+		else {
+			const entries: PluginEntry[] = [];
+			let malformed = false;
+			for (const [name, values] of Object.entries(marketplacePlugins)) {
+				if (!Array.isArray(values)) {
+					malformed = true;
+					continue;
+				}
+				for (const raw of values) {
+					const value = doctorMapping(raw);
+					if (!value) {
+						malformed = true;
+						continue;
+					}
+					if (value.scope === source.scope) entries.push({ name, enabled: value.enabled });
+				}
+			}
+			if (malformed) checks.push(registryFailure(source, "marketplace", marketplace, true));
+			await addEntries(context, source, "marketplace", entries, checks, marketplacePath);
+		}
+	}
+	return checks;
+}

package/src/cli/doctor/probe-client.ts

@@ -0,0 +1,195 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { DoctorContext } from "./context";
+import { doctorMapping } from "./files";
+import type { DoctorProbeKind, DoctorProbeReceipt } from "./probe-types";
+
+const PROBE_OUTPUT_LIMIT = 64 * 1024;
+const PROBE_ENV_KEYS = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"SYSTEMROOT",
+	"WINDIR",
+	"TMPDIR",
+	"TEMP",
+	"TMP",
+	"LANG",
+	"LC_ALL",
+	"TZ",
+	"GJC_CONFIG_DIR",
+	"PI_CONFIG_DIR",
+	"GJC_CODING_AGENT_DIR",
+	"PI_CODING_AGENT_DIR",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_STATE_HOME",
+	"XDG_CACHE_HOME",
+] as const;
+
+export interface DoctorProbeResult {
+	readonly status: "completed" | "failed" | "timeout" | "cancelled";
+	readonly reasonCode: string;
+	readonly receipt?: DoctorProbeReceipt;
+}
+
+function probeEnvironment(): NodeJS.ProcessEnv {
+	const environment: NodeJS.ProcessEnv = { NO_COLOR: "1", BUN_RUNTIME_TRANSPILER_CACHE_PATH: "0" };
+	for (const key of PROBE_ENV_KEYS) {
+		const value = process.env[key];
+		if (value !== undefined) environment[key] = value;
+	}
+	return environment;
+}
+
+async function readBoundedStream(stream: ReadableStream<Uint8Array>): Promise<string> {
+	const reader = stream.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const result = await reader.read();
+			if (result.done) break;
+			size += result.value.byteLength;
+			if (size > PROBE_OUTPUT_LIMIT) throw new Error("probe_output_limit");
+			chunks.push(result.value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const buffer = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		buffer.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+}
+
+function parseReceipt(text: string, kind: DoctorProbeKind): DoctorProbeReceipt | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	const record = doctorMapping(parsed);
+	if (
+		record?.schemaVersion !== 1 ||
+		record.kind !== kind ||
+		(record.status !== "completed" && record.status !== "failed") ||
+		typeof record.reasonCode !== "string" ||
+		!/^[a-z_]{1,80}$/.test(record.reasonCode) ||
+		!Array.isArray(record.checks) ||
+		record.checks.length > 2000
+	)
+		return undefined;
+	const executions = new Set(["completed", "blocked", "timeout", "cancelled", "unsupported", "not_selected"]);
+	const healthStates = new Set(["ok", "warning", "error", "unknown", "not_applicable"]);
+	const evidenceLevels = new Set(["observed", "not_probed"]);
+	const safeId = (value: unknown): value is string =>
+		typeof value === "string" && value.length <= 512 && /^[a-zA-Z0-9_.:-]+$/.test(value);
+	// The fixed core child is still a process boundary. Unknown states are not executable facts.
+	if (
+		record.checks.some(value => {
+			const check = doctorMapping(value);
+			return (
+				!check ||
+				!safeId(check.id) ||
+				!safeId(check.targetId) ||
+				typeof check.execution !== "string" ||
+				!executions.has(check.execution) ||
+				typeof check.health !== "string" ||
+				!healthStates.has(check.health) ||
+				typeof check.evidenceLevel !== "string" ||
+				!evidenceLevels.has(check.evidenceLevel) ||
+				!doctorMapping(check.evidence) ||
+				!Array.isArray(check.dependsOn) ||
+				check.dependsOn.length > 32 ||
+				!check.dependsOn.every(safeId) ||
+				!Array.isArray(check.remediationIds) ||
+				check.remediationIds.length > 16 ||
+				!check.remediationIds.every(safeId) ||
+				(check.scope !== undefined && check.scope !== "user" && check.scope !== "project") ||
+				(check.reasonCode !== undefined &&
+					(typeof check.reasonCode !== "string" || !/^[a-z_]{1,80}$/.test(check.reasonCode)))
+			);
+		})
+	)
+		return undefined;
+	return record as unknown as DoctorProbeReceipt;
+}
+
+/** Run a bounded child of the current product runtime, never a PATH-discovered executable. */
+export async function collectDoctorProbe(context: DoctorContext, kind: DoctorProbeKind): Promise<DoctorProbeResult> {
+	if (context.options.mode === "dry-run") return { status: "failed", reasonCode: "probe_not_permitted_in_preview" };
+	if (context.options.signal?.aborted) return { status: "cancelled", reasonCode: "cancelled" };
+	const timeoutMs = Math.min(4_000, context.deadline - performance.now());
+	if (timeoutMs <= 0) return { status: "timeout", reasonCode: "deadline_exceeded" };
+	const args = context.compiled
+		? [process.execPath, "--internal-doctor-probe", kind]
+		: [
+				process.execPath,
+				"--no-env-file",
+				`--config=${fileURLToPath(new URL("../../sdk/broker/internal-source.bunfig.toml", import.meta.url))}`,
+				context.cliPath ?? "",
+				"--internal-doctor-probe",
+				kind,
+			];
+	if (!path.isAbsolute(args[0]) || (!context.compiled && !context.cliPath))
+		return { status: "failed", reasonCode: "runtime_identity_unavailable" };
+	let child: Bun.Subprocess<"ignore", "pipe", "pipe">;
+	try {
+		child = Bun.spawn(args, {
+			cwd: context.cwd,
+			env: probeEnvironment(),
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+	} catch {
+		return { status: "failed", reasonCode: "probe_spawn_failed" };
+	}
+	const interrupted = Promise.withResolvers<DoctorProbeResult>();
+	let timeout: NodeJS.Timeout | undefined;
+	const abort = () => interrupted.resolve({ status: "cancelled", reasonCode: "cancelled" });
+	context.options.signal?.addEventListener("abort", abort, { once: true });
+	timeout = setTimeout(() => interrupted.resolve({ status: "timeout", reasonCode: "probe_timeout" }), timeoutMs);
+	const output = Promise.all([readBoundedStream(child.stdout), readBoundedStream(child.stderr), child.exited])
+		.then(([stdout, _stderr, exitCode]): DoctorProbeResult => {
+			const receipt = parseReceipt(stdout, kind);
+			if (!receipt)
+				return {
+					status: "failed",
+					reasonCode: child.signalCode ? "probe_signalled" : "probe_invalid_receipt",
+				};
+			return {
+				status: exitCode === 0 && receipt.status === "completed" ? "completed" : "failed",
+				reasonCode: receipt.reasonCode,
+				receipt,
+			};
+		})
+		.catch((): DoctorProbeResult => ({ status: "failed", reasonCode: "probe_output_unavailable" }));
+	let result: DoctorProbeResult;
+	try {
+		result = await Promise.race([output, interrupted.promise]);
+	} finally {
+		clearTimeout(timeout);
+		context.options.signal?.removeEventListener("abort", abort);
+	}
+	if (child.exitCode === null) {
+		// The only killable process here is this retained, fixed core probe child.
+		try {
+			child.kill("SIGKILL");
+			const stopped = Promise.withResolvers<void>();
+			const cleanupTimer = setTimeout(() => stopped.resolve(), 1_000);
+			await Promise.race([child.exited, stopped.promise]);
+			clearTimeout(cleanupTimer);
+		} catch {
+			return { status: "failed", reasonCode: "probe_termination_unverified" };
+		}
+		if (child.exitCode === null && child.signalCode === null)
+			return { status: "failed", reasonCode: "probe_termination_unverified" };
+	}
+	return result;
+}

package/src/cli/doctor/probe-types.ts

@@ -0,0 +1,21 @@
+import type { DoctorCheck } from "./types";
+
+/** Maximum UTF-8 payload accepted by the doctor probe transport. */
+export const PROBE_OUTPUT_LIMIT_BYTES = 64 * 1024;
+/**
+ * Producer-side budget for a projection receipt. Kept below the transport limit
+ * so the probe never has to discard a whole surface: the producer sheds its own
+ * lowest-value item checks instead. The headroom covers the trailing newline
+ * and transport framing.
+ */
+export const PROJECTION_RECEIPT_BUDGET_BYTES = PROBE_OUTPUT_LIMIT_BYTES - 1024;
+
+export type DoctorProbeKind = "native" | "projection";
+
+export interface DoctorProbeReceipt {
+	readonly schemaVersion: 1;
+	readonly kind: DoctorProbeKind;
+	readonly status: "completed" | "failed";
+	readonly reasonCode: string;
+	readonly checks: readonly DoctorCheck[];
+}

package/src/cli/doctor/probe.ts

@@ -0,0 +1,42 @@
+import { logger } from "@gajae-code/utils";
+import type { DoctorProbeKind, DoctorProbeReceipt } from "./probe-types";
+import { PROBE_OUTPUT_LIMIT_BYTES } from "./probe-types";
+
+const loaders = {
+	native: () => import("./native-probe"),
+	projection: () => import("./projection-probe"),
+};
+
+/** Only the fixed product probes are executable; no caller-provided program or module path. */
+export async function runDoctorProbe(kind: DoctorProbeKind): Promise<void> {
+	// The projection probe loads real product modules, and any warning they emit
+	// would otherwise create `.gjc/logs/` entries. Diagnosis must not write
+	// product state, so the rotating file sink is disabled before those modules
+	// are loaded; the receipt still travels over stdout.
+	logger.setTransports({ console: false, file: false });
+	let receipt: DoctorProbeReceipt;
+	try {
+		receipt =
+			kind === "native"
+				? await (await loaders.native()).collectNativeProbe()
+				: await (await loaders.projection()).collectProjectionProbe();
+	} catch {
+		receipt = {
+			schemaVersion: 1,
+			kind,
+			status: "failed",
+			reasonCode: kind === "native" ? "native_load_failed" : "projection_load_failed",
+			checks: [],
+		};
+	}
+	const text = JSON.stringify(receipt);
+	if (Buffer.byteLength(text) > PROBE_OUTPUT_LIMIT_BYTES) {
+		process.stdout.write(
+			`${JSON.stringify({ schemaVersion: 1, kind, status: "failed", reasonCode: "limit_exceeded", checks: [] })}\n`,
+		);
+		process.exitCode = 1;
+		return;
+	}
+	process.stdout.write(`${text}\n`);
+	process.exitCode = receipt.status === "completed" ? 0 : 1;
+}