@gajae-code/coding-agent 0.16.7 → 0.17.1

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

@@ -0,0 +1,274 @@
+import { type BigIntStats, constants } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { NativeExactFileIdentity } from "@gajae-code/natives";
+import { daemonPaths, telegramDaemonOwnerMarkerPath } from "../../sdk/bus/daemon-paths";
+import {
+	BROKER_ARTIFACT_PATHS,
+	CHAT_DAEMON_DIRECTORY,
+	CHAT_DAEMON_FILES,
+	DOCTOR_RESTART_CONTROL_FILE,
+} from "../../sdk/service-artifact-paths";
+import { doctorCheck } from "./checks";
+import type { DoctorContext } from "./context";
+import { type DoctorFileObservation, doctorErrno, doctorMapping, readDoctorFile } from "./files";
+import { artifactTargetId, serviceTargetId } from "./ids";
+import type { DoctorCheck } from "./types";
+
+export const DOCTOR_SERVICES = ["broker", "telegram", "discord", "slack"] as const;
+export type DoctorServiceKind = (typeof DOCTOR_SERVICES)[number];
+export type DoctorArtifactSlot = "discovery" | "owner-lock" | "startup-marker";
+
+export interface DoctorServicePaths {
+	readonly state: string;
+	readonly owner: string;
+	readonly restartIntent: string;
+	readonly directoryOwner?: string;
+	readonly startupMarker?: string;
+}
+
+export interface DoctorDirectoryObservation {
+	readonly status: "directory";
+	readonly mode: number;
+	readonly owner: number;
+	readonly exactIdentity: NativeExactFileIdentity;
+}
+export type DoctorArtifactObservation = DoctorFileObservation | DoctorDirectoryObservation;
+
+export interface DoctorServiceObservation {
+	readonly service: DoctorServiceKind;
+	readonly paths: DoctorServicePaths;
+	readonly state: DoctorFileObservation;
+	readonly owner: DoctorFileObservation;
+	readonly restartIntent: DoctorFileObservation;
+	readonly directoryOwner?: DoctorArtifactObservation;
+	readonly startupMarker?: DoctorFileObservation;
+	readonly ownerMarker?: { readonly path: string; readonly observation: DoctorFileObservation };
+}
+
+/** Only product-defined paths are addressable; record content never supplies a path. */
+export function doctorServicePaths(agentDir: string, service: DoctorServiceKind): DoctorServicePaths {
+	if (service === "broker")
+		return {
+			state: path.join(agentDir, BROKER_ARTIFACT_PATHS.discovery),
+			owner: path.join(agentDir, BROKER_ARTIFACT_PATHS.ownerRecord),
+			restartIntent: path.join(agentDir, BROKER_ARTIFACT_PATHS.restartIntent),
+			directoryOwner: path.join(agentDir, BROKER_ARTIFACT_PATHS.ownerLock),
+		};
+	if (service === "telegram") {
+		const paths = daemonPaths(agentDir);
+		return {
+			state: paths.state,
+			owner: paths.lock,
+			startupMarker: paths.steal,
+			restartIntent: path.join(paths.dir, DOCTOR_RESTART_CONTROL_FILE),
+		};
+	}
+	const directory = path.join(agentDir, CHAT_DAEMON_DIRECTORY, service);
+	return {
+		state: path.join(directory, CHAT_DAEMON_FILES.state),
+		owner: path.join(directory, CHAT_DAEMON_FILES.ownerLock),
+		restartIntent: path.join(directory, DOCTOR_RESTART_CONTROL_FILE),
+	};
+}
+
+async function checkParents(root: string, file: string): Promise<DoctorFileObservation | undefined> {
+	const relative = path.relative(root, file);
+	if (relative === "" || path.isAbsolute(relative) || relative.split(path.sep).includes(".."))
+		return { status: "unreadable", errno: "EINVAL" };
+	let current = root;
+	try {
+		for (const component of ["", ...relative.split(path.sep).slice(0, -1)]) {
+			if (component) current = path.join(current, component);
+			const stat = await fs.lstat(current);
+			if (stat.isSymbolicLink()) return { status: "symlink" };
+			if (!stat.isDirectory()) return { status: "unreadable", errno: "ENOTDIR" };
+		}
+		return undefined;
+	} catch (error) {
+		const errno = doctorErrno(error);
+		return { status: errno === "ENOENT" ? "missing" : "unreadable", errno };
+	}
+}
+
+async function readServiceFile(root: string, file: string): Promise<DoctorFileObservation> {
+	return (await checkParents(root, file)) ?? (await readDoctorFile(file, 128 * 1024));
+}
+
+function sameDirectory(left: BigIntStats, right: BigIntStats): boolean {
+	return (
+		right.isDirectory() &&
+		!right.isSymbolicLink() &&
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.mode === right.mode &&
+		left.uid === right.uid &&
+		left.nlink === right.nlink &&
+		left.size === right.size &&
+		left.mtimeNs === right.mtimeNs &&
+		left.ctimeNs === right.ctimeNs
+	);
+}
+
+async function readServiceDirectory(root: string, directory: string): Promise<DoctorArtifactObservation> {
+	const failure = await checkParents(root, directory);
+	if (failure) return failure;
+	let handle: fs.FileHandle | undefined;
+	try {
+		const before = await fs.lstat(directory, { bigint: true });
+		if (before.isSymbolicLink()) return { status: "symlink" };
+		if (!before.isDirectory()) return { status: "not_regular" };
+		handle = await fs.open(
+			directory,
+			constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+		);
+		const opened = await handle.stat({ bigint: true });
+		const parent = await fs.lstat(path.dirname(directory), { bigint: true });
+		const after = await handle.stat({ bigint: true });
+		const lexical = await fs.lstat(directory, { bigint: true });
+		const parentAfter = await fs.lstat(path.dirname(directory), { bigint: true });
+		if (
+			!sameDirectory(before, opened) ||
+			!sameDirectory(opened, after) ||
+			!sameDirectory(after, lexical) ||
+			parent.isSymbolicLink() ||
+			parentAfter.isSymbolicLink() ||
+			!parent.isDirectory() ||
+			parent.dev !== parentAfter.dev ||
+			parent.ino !== parentAfter.ino
+		)
+			return { status: "changed" };
+		return {
+			status: "directory",
+			mode: Number(after.mode),
+			owner: Number(after.uid),
+			exactIdentity: {
+				dev: after.dev,
+				ino: after.ino,
+				nlink: after.nlink,
+				size: after.size,
+				mtimeNs: after.mtimeNs,
+				parentDev: parent.dev,
+				parentIno: parent.ino,
+				directory: true,
+				detachOnly: true,
+			},
+		};
+	} catch (error) {
+		const errno = doctorErrno(error);
+		return { status: errno === "ENOENT" ? "missing" : "unreadable", errno };
+	} finally {
+		await handle?.close();
+	}
+}
+
+export function parseServiceRecord(observation: DoctorFileObservation): Record<string, unknown> | undefined {
+	if (observation.status !== "read") return undefined;
+	try {
+		return doctorMapping(JSON.parse(observation.text));
+	} catch {
+		return undefined;
+	}
+}
+
+export async function readDoctorService(root: string, service: DoctorServiceKind): Promise<DoctorServiceObservation> {
+	const paths = doctorServicePaths(root, service);
+	const [state, owner, directoryOwner, startupMarker, restartIntent] = await Promise.all([
+		readServiceFile(root, paths.state),
+		readServiceFile(root, paths.owner),
+		paths.directoryOwner ? readServiceDirectory(root, paths.directoryOwner) : undefined,
+		paths.startupMarker ? readServiceFile(root, paths.startupMarker) : undefined,
+		readServiceFile(root, paths.restartIntent),
+	]);
+	let ownerMarker: DoctorServiceObservation["ownerMarker"];
+	if (service === "telegram") {
+		const record = parseServiceRecord(state) ?? parseServiceRecord(owner);
+		const acquisitionId = record?.acquisitionId;
+		if (typeof acquisitionId === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(acquisitionId)) {
+			const marker = telegramDaemonOwnerMarkerPath(root, acquisitionId);
+			ownerMarker = { path: marker, observation: await readServiceFile(root, marker) };
+		}
+	}
+	return { service, paths, state, owner, directoryOwner, startupMarker, ownerMarker, restartIntent };
+}
+
+export function serviceArtifactObservation(
+	service: DoctorServiceObservation,
+	slot: DoctorArtifactSlot,
+): DoctorArtifactObservation | undefined {
+	if (slot === "discovery") return service.state;
+	if (slot === "owner-lock") return service.directoryOwner ?? service.owner;
+	return service.startupMarker;
+}
+
+/** Metadata only: no service import, connection, process probe, or ownership acquisition. */
+export async function collectServiceTargets(context: DoctorContext): Promise<DoctorCheck[]> {
+	const checks: DoctorCheck[] = [];
+	for (const service of DOCTOR_SERVICES) {
+		const observation = await readDoctorService(context.agentRoot.locator, service);
+		const targetId = serviceTargetId(context.agentRoot.rootId, service);
+		context.targets.set(targetId, { kind: "service", targetId, service, root: context.agentRoot, observation });
+		for (const slot of ["discovery", "owner-lock", "startup-marker"] as const) {
+			const artifactId = artifactTargetId(context.agentRoot.rootId, service, slot);
+			context.targets.set(artifactId, {
+				kind: "artifact",
+				targetId: artifactId,
+				service,
+				slot,
+				root: context.agentRoot,
+				observation,
+			});
+			const artifact = serviceArtifactObservation(observation, slot);
+			if (!artifact) continue;
+			const present = artifact.status === "read" || artifact.status === "directory";
+			const malformed = artifact.status === "read" && !parseServiceRecord(artifact);
+			checks.push(
+				doctorCheck(`service.${service}.${slot}`, artifactId, {
+					execution: present || artifact.status === "missing" ? "completed" : "blocked",
+					health: malformed
+						? "error"
+						: present
+							? "ok"
+							: artifact.status === "missing"
+								? "not_applicable"
+								: "unknown",
+					evidenceLevel: "observed",
+					reasonCode: malformed
+						? "service_metadata_invalid"
+						: present
+							? "service_artifact_present"
+							: `service_artifact_${artifact.status}`,
+					evidence: {
+						present,
+						runtimeProbed: false,
+						authenticationProbed: false,
+						...(artifact.status === "directory" ? { fileKind: "directory", mode: artifact.mode & 0o777 } : {}),
+						...("errno" in artifact ? { errno: artifact.errno } : {}),
+					},
+					remediationIds: present ? ["service.detach-owned-stale-artifact"] : [],
+				}),
+			);
+		}
+		checks.push(
+			doctorCheck(`service.${service}.owner`, targetId, {
+				execution:
+					observation.state.status === "read" || observation.state.status === "missing" ? "completed" : "blocked",
+				health:
+					observation.state.status === "missing"
+						? "not_applicable"
+						: observation.state.status === "read"
+							? "ok"
+							: "unknown",
+				evidenceLevel: "observed",
+				reasonCode: "service_metadata_only",
+				evidence: {
+					present: observation.state.status === "read",
+					runtimeProbed: false,
+					authenticationProbed: false,
+				},
+				remediationIds: observation.state.status === "read" ? ["service.restart-owned"] : [],
+			}),
+		);
+	}
+	return checks;
+}

package/src/cli/doctor/types.ts

@@ -0,0 +1,164 @@
+export type DoctorMode = "diagnose" | "dry-run" | "fix";
+/**
+ * `unsupported` and `not_selected` are the coverage vocabulary this process
+ * accepts across the worker/probe boundary and reports in `DoctorCoverage`; the
+ * collectors on this platform never emit them, so their consumers are deliberate
+ * validation rather than reachable branches.
+ */
+export type CheckExecution = "completed" | "blocked" | "timeout" | "cancelled" | "unsupported" | "not_selected";
+export type Health = "ok" | "warning" | "error" | "unknown" | "not_applicable";
+export type EvidenceLevel = "observed" | "not_probed";
+export type Verdict = "healthy" | "degraded" | "unhealthy" | "inconclusive";
+export type RepairState =
+	| "planned"
+	| "blocked"
+	| "not_needed"
+	// Transient base value only: every construction site overrides it before the
+	// repair is returned, so it never reaches a report.
+	| "preparing"
+	| "pending_activation"
+	| "verified"
+	| "failed"
+	| "uncertain"
+	| "rolled_back"
+	| "rollback_conflict";
+export type ReadinessFactCode =
+	| "authorization_missing"
+	| "confirmation_required"
+	| "candidate_unresolved"
+	| "pin_missing"
+	| "candidate_selection_missing"
+	| "identity_recheck_required"
+	| "target_resolution_incomplete"
+	| "unsupported";
+export type DoctorScope = "user" | "project";
+
+export type DoctorRiskClass =
+	| "config-change"
+	| "permission-change"
+	| "install-replace"
+	| "plugin-change"
+	| "service-interruption"
+	| "artifact-detach"
+	| "network"
+	| "external-execution";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { readonly [key: string]: JsonValue };
+
+export interface CheckEvidence {
+	readonly runtimeVersion?: string;
+	readonly platform?: string;
+	readonly arch?: string;
+	readonly channel?: string;
+	readonly schemaCoverage?: "selected_fields" | "complete";
+	readonly startupStatus?: "autoload" | "autoload-off" | "disabled";
+	readonly runtimeProbed?: boolean;
+	readonly aclCoverage?: "not_probed" | "verified";
+	readonly mode?: number;
+	readonly ownerMatches?: boolean;
+	readonly contentsRead?: boolean;
+	readonly authenticationProbed?: boolean;
+	readonly present?: boolean;
+	readonly enabled?: boolean;
+	readonly autoload?: boolean;
+	readonly hasAuth?: boolean;
+	readonly status?: string;
+	readonly sourceClass?: string;
+	/** Closed observation of a known plugin artifact; never a path or content. */
+	readonly artifactStatus?: "present" | "absent" | "unreadable";
+	readonly transport?: "stdio" | "http" | "sse" | "unknown";
+	readonly count?: number;
+	readonly warningCount?: number;
+	readonly counts?: Readonly<Record<string, number>>;
+	readonly errno?: string;
+	readonly fileKind?: string;
+	readonly schemaLocation?: string;
+	readonly version?: string;
+	readonly integrityResult?: string;
+	readonly processObservation?: JsonValue;
+	readonly generation?: string;
+	readonly occupancy?: string;
+	readonly readiness?: readonly ReadinessFactCode[];
+	readonly rootId?: string;
+	readonly safeLabel?: string;
+	readonly candidateCount?: number;
+}
+export interface DoctorCheck {
+	readonly id: string;
+	readonly targetId: string;
+	readonly scope?: DoctorScope;
+	readonly execution: CheckExecution;
+	readonly health: Health;
+	readonly reasonCode?: string;
+	readonly evidenceLevel: EvidenceLevel;
+	readonly observedAt?: string;
+	readonly durationMs?: number;
+	readonly dependsOn: readonly string[];
+	readonly evidence: CheckEvidence;
+	readonly remediationIds: readonly string[];
+}
+export interface RepairCandidate {
+	readonly id: string;
+	readonly sourceChannel: string;
+	readonly ref?: string;
+	readonly sha256?: string;
+	readonly evidence: CheckEvidence;
+}
+export interface DoctorRepair {
+	readonly id: string;
+	readonly targetId: string;
+	readonly riskClasses: readonly DoctorRiskClass[];
+	readonly authorization: readonly string[];
+	readonly readiness: readonly ReadinessFactCode[];
+	readonly sourceChannel?: string;
+	readonly candidates: readonly RepairCandidate[];
+	readonly selectedCandidate?: string;
+	readonly preconditions: readonly string[];
+	readonly rollbackClass?: string;
+	readonly state: RepairState;
+	readonly reasonCode?: string;
+	readonly sideEffectStarted?: boolean;
+	readonly outcome?: { readonly mutationVerified: boolean; readonly desiredStartupStateAchieved?: boolean };
+	readonly beforeCheckIds: readonly string[];
+	readonly afterCheckIds: readonly string[];
+	readonly restartRequired: boolean;
+	readonly restartScope?: "none" | "new-session" | "service";
+	readonly nonrollbackableEffects: readonly string[];
+	readonly activationRecordRef?: string;
+}
+export interface DoctorCoverage {
+	readonly requested: number;
+	readonly expanded: number;
+	readonly attempted: number;
+	readonly completed: number;
+	readonly blocked: number;
+	readonly timedOut: number;
+	readonly unsupported: number;
+}
+export interface DoctorSummary {
+	readonly verdict: Verdict;
+	readonly exitCode: number;
+}
+export interface DoctorReport {
+	readonly schemaVersion: 1;
+	readonly command: "doctor";
+	readonly runId: string;
+	readonly mode: DoctorMode;
+	readonly generatedAt: string;
+	readonly durationMs: number;
+	readonly subject: {
+		readonly gjcVersion: string;
+		readonly platform: string;
+		readonly arch: string;
+		readonly channel: string;
+		readonly scope?: DoctorScope;
+		readonly rootIds: readonly string[];
+	};
+	readonly selection: { readonly checks: readonly string[]; readonly repair?: string; readonly targetId?: string };
+	readonly coverage: DoctorCoverage;
+	readonly summary: DoctorSummary;
+	readonly checks: readonly DoctorCheck[];
+	readonly repairs: readonly DoctorRepair[];
+	readonly limits: { readonly [key: string]: JsonValue };
+	readonly invocationError?: string;
+}

package/src/cli/doctor-cli.ts

@@ -0,0 +1,62 @@
+import { parseDoctorArgs } from "./doctor/args";
+import { DOCTOR_EXIT_CODES, renderDoctorJson, renderDoctorText } from "./doctor/report";
+import { runSupervisedDoctor } from "./doctor-supervisor";
+
+/**
+ * Execute the boot-safe doctor parser and delegate collection to an owned,
+ * verified-terminated child worker (`doctor-supervisor.ts`). Diagnostics and
+ * repairs never run in this process: a `Promise.race` here cannot bound
+ * synchronous fs/native work, so only the child-process boundary can.
+ */
+export async function runDoctorCli(argv: readonly string[]): Promise<void> {
+	if (argv.includes("--help") || argv.includes("-h")) {
+		process.stdout.write(doctorHelp());
+		return;
+	}
+	const parsed = parseDoctorArgs(argv);
+	if (parsed.error || !parsed.options) {
+		const message = parsed.error ?? "invalid arguments";
+		if (argv.includes("--json"))
+			process.stdout.write(
+				`${JSON.stringify({
+					schemaVersion: 1,
+					command: "doctor",
+					error: { code: "invalid_arguments", message },
+					summary: { verdict: "inconclusive", exitCode: DOCTOR_EXIT_CODES.usage },
+				})}\n`,
+			);
+		else process.stderr.write(`gjc doctor: ${message}\n`);
+		process.exitCode = DOCTOR_EXIT_CODES.usage;
+		return;
+	}
+	try {
+		const report = await runSupervisedDoctor({
+			argv,
+			options: {
+				...parsed.options,
+				cwd: process.cwd(),
+				tty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+			},
+		});
+		process.stdout.write(parsed.options.json ? renderDoctorJson(report) : renderDoctorText(report));
+		process.exitCode = report.summary.exitCode;
+	} catch {
+		// The supervisor itself synthesizes bounded reports for every abnormal
+		// ending; reaching here means something outside its own contract threw
+		// (e.g. a module load failure), so degrade to the same sanitized envelope
+		// used elsewhere rather than surfacing a raw exception.
+		const envelope = {
+			schemaVersion: 1,
+			command: "doctor",
+			error: { code: "doctor_supervisor_failure", message: "Doctor diagnostics could not be completed." },
+			summary: { verdict: "inconclusive", exitCode: DOCTOR_EXIT_CODES.incomplete },
+		};
+		if (parsed.options.json) process.stdout.write(`${JSON.stringify(envelope)}\n`);
+		else process.stderr.write("gjc doctor: Doctor diagnostics could not be completed.\n");
+		process.exitCode = DOCTOR_EXIT_CODES.incomplete;
+	}
+}
+
+function doctorHelp(): string {
+	return `Usage: gjc doctor [options]\n\nRead-only bootstrap diagnostics and explicitly targeted repairs.\n\nOptions:\n  --json                         Emit machine-readable JSON\n  --fix --repair <action>        Apply one approved repair action\n  --dry-run                      Preview repair candidates without mutation\n  --target <stable-id>           Select the exact report target\n  --check <id>                   Select a check (repeatable)\n  --scope <user|project>         Constrain target scope\n  --set-value-json <true|false>  Boolean value for config/MCP repairs\n  --ref <candidate-ref>          Select a repair candidate\n  --sha256 <hex>                 Pin an artifact by digest\n  --allow-risk <class>           Approve a required risk class (repeatable)\n  --yes                          Skip interactive confirmation\n  --timeout-ms <n>               Bound diagnostic work\n  --drain                        Drain before service restart\n\nPlatform notes:\n  Repairs fenced by the crash-recovery journal (config.set-validated,\n  mcp.set-startup-policy, permissions.restrict-owned-config,\n  install.repair-managed-link, plugin.quarantine-selected,\n  service.detach-owned-stale-artifact) are unsupported on Windows in this\n  release and are refused before any mutation. Diagnosis and --dry-run work\n  on every platform.\n`;
+}