@gajae-code/coding-agent 0.17.2 → 0.17.4

package/scripts/vendor-markit.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env bun
+/** Reproduce the patched MIT converter; --check is strictly local and read-only. */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $ } from "bun";
+
+const packageRoot = path.resolve(import.meta.dir, "..");
+const vendorRoot = path.join(packageRoot, "vendor");
+const vendorDir = path.join(vendorRoot, "markit-ai");
+const patchPath = path.join(vendorRoot, "markit-ai.patch");
+const sourceUrl = "https://registry.npmjs.org/markit-ai/-/markit-ai-0.5.3.tgz";
+const sourceIntegrity =
+	"sha512-h4nhn6a/SNXEdc3kLVtL37TspxjUNCNL0OM7LRWxd389ZByI/B7bjNNgxFdVAT0O+H7ZekSwLdVe/lws1l2AZQ==";
+const provenanceName = "MANIFEST.json";
+const maxArchiveBytes = 16 * 1024 * 1024;
+
+interface FileHash {
+	path: string;
+	sha256: string;
+}
+
+function sha256(bytes: Uint8Array): string {
+	return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function selectedFile(name: string): boolean {
+	return name === "LICENSE" || name === "package.json" || name.startsWith("dist/");
+}
+
+async function inventory(directory: string): Promise<FileHash[]> {
+	const files: FileHash[] = [];
+	async function walk(relative: string): Promise<void> {
+		const absolute = path.join(directory, relative);
+		const metadata = await fs.lstat(absolute);
+		if (metadata.isDirectory()) {
+			if (relative !== "" && relative !== "dist" && !relative.startsWith("dist/")) {
+				throw new Error(`Unexpected vendor directory: ${relative}`);
+			}
+			for (const name of (await fs.readdir(absolute)).sort()) {
+				await walk(relative ? `${relative}/${name}` : name);
+			}
+		} else if (metadata.isFile()) {
+			if (relative === provenanceName) return;
+			if (!selectedFile(relative)) throw new Error(`Unexpected vendor file: ${relative}`);
+			files.push({ path: relative, sha256: sha256(await Bun.file(absolute).bytes()) });
+		} else {
+			throw new Error(`Vendor entries must be regular files or directories: ${relative}`);
+		}
+	}
+	await walk("");
+	for (const required of [
+		"LICENSE",
+		"package.json",
+		"dist/index.js",
+		"dist/index.d.ts",
+		"dist/converters/pdf/extract.js",
+		"dist/markit.js",
+	]) {
+		if (!files.some(file => file.path === required)) throw new Error(`Missing vendor file: ${required}`);
+	}
+	return files.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+}
+
+async function provenance(directory: string): Promise<string> {
+	return `${JSON.stringify(
+		{
+			schemaVersion: 1,
+			upstream: { name: "markit-ai", version: "0.5.3", license: "MIT", url: sourceUrl, integrity: sourceIntegrity },
+			patch: { path: "../markit-ai.patch", sha256: sha256(await Bun.file(patchPath).bytes()) },
+			files: await inventory(directory),
+		},
+		null,
+		"\t",
+	)}\n`;
+}
+
+async function verifyContents(directory: string): Promise<void> {
+	const upstream = await Bun.file(path.join(directory, "package.json")).json();
+	if (upstream.name !== "markit-ai" || upstream.version !== "0.5.3" || upstream.license !== "MIT") {
+		throw new Error("Vendored manifest must identify MIT markit-ai@0.5.3");
+	}
+	const manifest = await Bun.file(path.join(packageRoot, "package.json")).json();
+	for (const dependency of Object.keys(upstream.dependencies)) {
+		if (typeof manifest.dependencies?.[dependency] !== "string") {
+			throw new Error(`Missing direct converter runtime dependency: ${dependency}`);
+		}
+	}
+	if (manifest.dependencies.mupdf !== "1.28.0" || manifest.dependencies["markit-ai"] !== undefined) {
+		throw new Error("Converter must use vendored Markit and pinned mupdf@1.28.0");
+	}
+	const extract = await Bun.file(path.join(directory, "dist/converters/pdf/extract.js")).text();
+	const mupdfLoader = await Bun.file(path.join(directory, "dist/converters/pdf/mupdf-loader.js")).text();
+	const markit = await Bun.file(path.join(directory, "dist/markit.js")).text();
+	if (
+		/require\(["']mupdf["']\)/u.test(extract) ||
+		!extract.includes("\nlet mupdf;\n") ||
+		!extract.includes('import { loadMuPdf } from "./mupdf-loader.js";') ||
+		!extract.includes("mupdf = await loadMuPdf()") ||
+		!mupdfLoader.includes('import("mupdf")') ||
+		!extract.includes('new Error("MuPDF module initialization failed", { cause })') ||
+		!markit.includes("new AggregateError(errors.map((entry) => entry.error)") ||
+		!markit.includes("{ cause: errors[0].error }")
+	)
+		throw new Error("Vendored Markit is missing the required MuPDF/diagnostics patch");
+}
+
+async function check(): Promise<void> {
+	if (!(await fs.lstat(vendorRoot)).isDirectory()) throw new Error("Vendor root must be a real directory");
+	if (!(await fs.lstat(patchPath)).isFile()) throw new Error("Vendor patch must be a regular file");
+	// Inventory rejects symlinks before any content verification reads them.
+	const expected = await provenance(vendorDir);
+	if ((await Bun.file(path.join(vendorDir, provenanceName)).text()) !== expected) {
+		throw new Error("Markit vendor inventory or patch hash differs; regenerate from the pinned artifact");
+	}
+	await verifyContents(vendorDir);
+	process.stdout.write("Markit vendor verification passed (markit-ai@0.5.3, local hashes)\n");
+}
+
+async function download(): Promise<Uint8Array> {
+	const response = await fetch(sourceUrl, { redirect: "error", signal: AbortSignal.timeout(60_000) });
+	if (!response.ok || !response.body) throw new Error(`Pinned Markit download failed: HTTP ${response.status}`);
+	const chunks: Uint8Array[] = [];
+	let length = 0;
+	for await (const chunk of response.body) {
+		length += chunk.byteLength;
+		if (length > maxArchiveBytes) throw new Error("Pinned Markit archive exceeds size limit");
+		chunks.push(chunk);
+	}
+	const bytes = Buffer.concat(chunks, length);
+	if (`sha512-${crypto.createHash("sha512").update(bytes).digest("base64")}` !== sourceIntegrity) {
+		throw new Error("Pinned Markit archive integrity mismatch");
+	}
+	return bytes;
+}
+
+async function generate(): Promise<void> {
+	const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-vendor-markit-"));
+	try {
+		const bytes = await download();
+		await Bun.write(path.join(temporaryRoot, "markit-ai-0.5.3.tgz"), bytes);
+		const source = path.join(temporaryRoot, "source");
+		await fs.mkdir(source);
+		// Read verified archive entries as data and create only regular files. Never
+		// ask an extractor to recreate upstream symlinks, permissions, or devices.
+		const entries = await new Bun.Archive(bytes).files();
+		let unpackedBytes = 0;
+		for (const [name, file] of entries) {
+			if (
+				!name.startsWith("package/") ||
+				name.includes("\\") ||
+				name.includes("\0") ||
+				name.split("/").some(part => part === "" || part === "." || part === "..")
+			) {
+				throw new Error(`Unsafe pinned archive entry: ${name}`);
+			}
+			unpackedBytes += file.size;
+			if (unpackedBytes > maxArchiveBytes) throw new Error("Pinned Markit unpacked files exceed size limit");
+			const relative = name.slice("package/".length);
+			if (!selectedFile(relative)) continue;
+			const destination = path.join(source, relative);
+			await Bun.write(destination, file);
+			await fs.chmod(destination, 0o644);
+		}
+		await $`git apply --check ${patchPath}`.cwd(source);
+		await $`git apply ${patchPath}`.cwd(source);
+		await verifyContents(source);
+		await Bun.write(path.join(source, provenanceName), await provenance(source));
+		if (!(await fs.lstat(vendorRoot)).isDirectory()) throw new Error("Vendor root must be a real directory");
+		const existing = await fs.lstat(vendorDir).catch((error: NodeJS.ErrnoException) => {
+			if (error.code === "ENOENT") return undefined;
+			throw error;
+		});
+		if (existing) {
+			// Refuse unrelated contents and symlinks rather than silently deleting them.
+			await inventory(vendorDir);
+			const oldManifest = await Bun.file(path.join(vendorDir, "package.json")).json();
+			if (oldManifest.name !== "markit-ai") throw new Error("Refusing to replace an unrelated vendor tree");
+			await fs.rm(vendorDir, { recursive: true });
+		}
+		await fs.cp(source, vendorDir, { recursive: true, force: false, errorOnExist: true });
+		await check();
+	} finally {
+		await fs.rm(temporaryRoot, { recursive: true, force: true });
+	}
+}
+
+if (import.meta.main) {
+	const args = process.argv.slice(2);
+	if (args.length !== 1 || (args[0] !== "--check" && args[0] !== "--generate")) {
+		throw new Error("Use exactly --check (offline verification) or --generate (pinned regeneration)");
+	}
+	if (args[0] === "--generate") await generate();
+	else await check();
+}

package/src/async/job-manager.ts

@@ -2713,7 +2713,28 @@ export class AsyncJobManager {
 	markBackgrounded(jobId: string, generation: string, reason: FoldReason): boolean {
 		const job = this.#jobs.get(jobId);
 		if (!job || job.generation !== generation) return false;
-		if (job.metadata?.backgrounded === true) return true;
+		if (job.metadata?.backgrounded === true) {
+			// A direct async start is already backgrounded, but a later `job` await
+			// can still be folded by a steer. Preserve the existing background state
+			// while recording the first fold reason and publishing its event.
+			if (job.metadata.foldReason !== undefined) return true;
+			job.metadata = { ...job.metadata, foldReason: reason };
+			for (const delivery of [...this.#deliveries, ...this.#inFlightDeliveries]) {
+				if (delivery.jobId === jobId && delivery.generation === generation) delivery.foldReason = reason;
+			}
+			this.#notifyChange();
+			const event: JobFoldEvent = { jobId, generation, reason };
+			for (const cb of this.#foldListeners) {
+				try {
+					cb(event);
+				} catch (error) {
+					logger.warn("Async job fold listener failed", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}
+			return true;
+		}
 		job.metadata = { ...job.metadata, backgrounded: true, foldReason: reason };
 		for (const delivery of [...this.#deliveries, ...this.#inFlightDeliveries]) {
 			if (delivery.jobId === jobId && delivery.generation === generation) {

package/src/cli/daemon-cli.ts

@@ -12,26 +12,28 @@ import type {
 	DaemonKind,
 	DaemonOperationOptions,
 	DaemonOperationResult,
+	DaemonStatus,
 } from "../daemon/control-types";
 import {
 	DAEMON_ACTION_TOKENS,
-	DAEMON_EXIT,
+	daemonOperationOutcome,
 	formatDaemonResult,
 	formatDaemonStatus,
 	resolveDaemonAction,
 } from "../daemon/operator-contract";
 import { runChatDaemonInternal } from "../sdk/bus/chat-daemon-cli";
+import { PublicCommandFailure, type PublicDaemonTargetOutcome } from "./public-command-errors";
 
 export type DaemonCliAction = "list" | "status" | "stop" | "restart";
 export type DaemonInternalCliAction = "discord-internal" | "slack-internal";
 export type DaemonCommandAction = DaemonCliAction | DaemonInternalCliAction;
 
-export class UnknownDaemonKindError extends Error {
+export class UnknownDaemonKindError extends PublicCommandFailure {
 	constructor(
 		readonly kinds: readonly string[],
 		readonly knownKinds: readonly DaemonKind[],
 	) {
-		super(`Unknown daemon kind(s): ${kinds.join(", ")}. Known kinds: ${knownKinds.join(", ")}.`);
+		super({ kind: "operation_failed", proof: "pre-effect" });
 		this.name = "UnknownDaemonKindError";
 	}
 }
@@ -60,6 +62,7 @@ export interface DaemonCommandArgs {
 export interface DaemonCommandDeps {
 	settings?: Settings;
 	controllers?: BuiltInDaemonController[];
+	/** Internal update orchestration retains result rendering and failure aggregation. */
 	setExitCode?: (code: number) => void;
 }
 
@@ -131,15 +134,36 @@ export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonComma
 	}
 	const unknownKinds = cmd.kinds.filter(kind => !(KNOWN_KINDS as readonly string[]).includes(kind));
 	if (unknownKinds.length > 0) throw new UnknownDaemonKindError(unknownKinds, KNOWN_KINDS);
+	// Settings and controller construction failures are NOT an availability
+	// condition. Malformed configuration, permission/IO errors, and programming
+	// errors are permanent and each needs its own root cause: collapsing them into
+	// `unavailable` tells an operator (or an AI caller) to retry a failure that
+	// will never succeed. Let them propagate to the normal CLI error rendering,
+	// which is the pre-existing contract for this path.
 	const settings = deps.settings ?? (await Settings.init());
-	const controllers = deps.controllers ?? selectDaemonControllers(settings, cmd.kinds, cmd.all);
+	const controllers: BuiltInDaemonController[] =
+		deps.controllers ?? selectDaemonControllers(settings, cmd.kinds, cmd.all);
 
 	if (cmd.action === "list" || cmd.action === "status") {
-		const statuses = await Promise.all(controllers.map(c => c.status()));
-		if (cmd.json) {
-			process.stdout.write(`${JSON.stringify(statuses, null, 2)}\n`);
-		} else {
-			process.stdout.write(`${statuses.map(s => formatDaemonStatus(s, { verbose: cmd.verbose })).join("\n")}\n`);
+		const statusResults = await Promise.allSettled(controllers.map(controller => controller.status()));
+		const statuses: DaemonStatus[] = [];
+		const failedTargets: PublicDaemonTargetOutcome[] = [];
+		for (const [index, result] of statusResults.entries()) {
+			if (result.status === "fulfilled") statuses.push(result.value);
+			else failedTargets.push({ kind: controllers[index]!.kind, outcome: "unknown" });
+		}
+		if (failedTargets.length > 0) {
+			throw new PublicCommandFailure({
+				kind: "daemon_mixed",
+				proof: "pre-effect",
+				targets: failedTargets,
+				partialStatuses: statuses,
+			});
+		}
+		if (statuses.length > 0) {
+			if (cmd.json) process.stdout.write(`${JSON.stringify(statuses, null, 2)}\n`);
+			else
+				process.stdout.write(`${statuses.map(s => formatDaemonStatus(s, { verbose: cmd.verbose })).join("\n")}\n`);
 		}
 		return;
 	}
@@ -152,19 +176,30 @@ export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonComma
 		allowDisabledNoop: cmd.allowDisabledNoop,
 	};
 	const results: DaemonOperationResult[] = [];
-	for (const controller of controllers) {
-		results.push(cmd.action === "restart" ? await controller.reload(opts) : await controller.stop(opts));
+	const targets: PublicDaemonTargetOutcome[] = [];
+	for (const [index, controller] of controllers.entries()) {
+		let result: DaemonOperationResult;
+		try {
+			result = cmd.action === "restart" ? await controller.reload(opts) : await controller.stop(opts);
+		} catch {
+			targets.push({ kind: controller.kind, outcome: "unknown" });
+			for (const pending of controllers.slice(index + 1))
+				targets.push({ kind: pending.kind, outcome: "not-applied" });
+			// Completed targets keep their full results: the envelope warns against
+			// replaying applied mutations, so it must carry the resulting state the
+			// caller has to reconcile against.
+			throw new PublicCommandFailure({ kind: "daemon_mixed", targets, partialResults: results });
+		}
+		results.push(result);
+		targets.push({ kind: controller.kind, outcome: daemonOperationOutcome(result) });
 	}
+	const failed = results.some(result => !result.ok);
+	if (failed && !deps.setExitCode)
+		throw new PublicCommandFailure({ kind: "daemon_mixed", targets, partialResults: results });
 	if (cmd.json) {
 		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
 	} else {
 		process.stdout.write(`${results.map(formatDaemonResult).join("\n")}\n`);
 	}
-	if (results.some(r => !r.ok))
-		(
-			deps.setExitCode ??
-			(code => {
-				process.exitCode = code;
-			})
-		)(DAEMON_EXIT.failure);
+	if (failed) deps.setExitCode?.(1);
 }

package/src/cli/github-release.ts

@@ -10,7 +10,8 @@ import type { UpdateChannel } from "../config/update-channel";
 
 export const RELEASE_REPO = "Yeachan-Heo/gajae-code";
 export const GITHUB_API_ORIGIN = "https://api.github.com";
-export const GITHUB_RELEASE_DOWNLOAD_ORIGIN = `https://github.com/${RELEASE_REPO}/releases/download`;
+export const GITHUB_WEB_ORIGIN = "https://github.com";
+export const GITHUB_RELEASE_DOWNLOAD_ORIGIN = `${GITHUB_WEB_ORIGIN}/${RELEASE_REPO}/releases/download`;
 export const BINARY_SHA256_ASSET = "gajae-release-binaries.sha256";
 export const BINARY_MANIFEST_ASSET = "gajae-release-binaries-v1.json";
 
@@ -34,10 +35,30 @@ export interface GithubReleaseLookupOptions {
 	fetchImpl?: GithubFetch;
 	lookupEnv?: (name: string) => string | undefined;
 	apiOrigin?: string;
+	webOrigin?: string;
 	timeoutMs?: number;
 	useAmbientToken?: boolean;
 }
 
+/** A GitHub REST response that failed, carrying the status the caller must branch on. */
+export class GithubApiStatusError extends Error {
+	constructor(
+		readonly url: string,
+		readonly status: number,
+	) {
+		super(`${url} responded ${status}`);
+		this.name = "GithubApiStatusError";
+	}
+
+	/** 403/429 is how api.github.com reports an exhausted unauthenticated budget. */
+	get isRateLimited(): boolean {
+		return this.status === 403 || this.status === 429;
+	}
+}
+
+const TOKEN_HINT =
+	"Set GITHUB_TOKEN or GH_TOKEN to raise the api.github.com rate limit (60 requests/hour per IP when unauthenticated).";
+
 interface GithubReleaseJson {
 	tag_name?: unknown;
 	draft?: unknown;
@@ -79,7 +100,7 @@ async function readGithubJson(url: string, options: GithubReleaseLookupOptions):
 		redirect: "follow",
 	});
 	if (!response.ok) {
-		throw new Error(`${url} responded ${response.status}`);
+		throw new GithubApiStatusError(url, response.status);
 	}
 	return await response.json();
 }
@@ -109,12 +130,57 @@ function parseRelease(value: unknown, expectedChannel: UpdateChannel): GithubRel
 	};
 }
 
+/**
+ * Resolve the stable tag through the `github.com` web route, which 302s from
+ * `/releases/latest` to `/releases/tag/<tag>`. That origin serves the binary
+ * downloads too and is not bound by the api.github.com rate limit, so it keeps
+ * `gjc update` working on a shared IP whose unauthenticated budget is spent.
+ */
+export async function resolveStableReleaseTagFromWeb(options: GithubReleaseLookupOptions = {}): Promise<string> {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const webOrigin = options.webOrigin ?? GITHUB_WEB_ORIGIN;
+	const url = `${webOrigin}/${RELEASE_REPO}/releases/latest`;
+	const response = await fetchImpl(url, {
+		method: "HEAD",
+		headers: { "User-Agent": "gjc-update" },
+		signal: AbortSignal.timeout(options.timeoutMs ?? 20_000),
+		redirect: "manual",
+	});
+	// `redirect: "manual"` keeps the 302 and its Location; a runtime that follows
+	// it anyway still exposes the resolved tag URL through `response.url`.
+	const location = response.headers.get("location") ?? (response.redirected ? response.url : undefined);
+	if (!location) {
+		throw new Error(`${url} responded ${response.status} without a release redirect`);
+	}
+	const target = new URL(location, url);
+	// The redirect decides which tag gets installed, so it must stay on the
+	// release origin and repository it was issued for; an off-origin Location
+	// would let a hijacked hop name any tag and choose the downloaded binary.
+	const expectedPrefix = `/${RELEASE_REPO}/releases/tag/`;
+	if (target.origin !== new URL(webOrigin).origin || !target.pathname.startsWith(expectedPrefix)) {
+		throw new Error(`Refusing a GitHub release redirect outside ${webOrigin}${expectedPrefix}: ${target.href}`);
+	}
+	const tag = decodeURIComponent(target.pathname.slice(expectedPrefix.length));
+	if (!isSafeReleaseTag(tag)) throw new Error(`Refusing unsafe GitHub release tag: ${tag || "<empty>"}`);
+	if (!STABLE_VERSION_RE.test(versionFromTag(tag))) {
+		throw new Error(`GitHub release ${tag} is not a stable vX.Y.Z release`);
+	}
+	return tag;
+}
+
 export async function fetchGithubChannelRelease(options: GithubReleaseLookupOptions = {}): Promise<GithubReleaseInfo> {
 	const channel = options.channel ?? "stable";
 	const apiOrigin = options.apiOrigin ?? GITHUB_API_ORIGIN;
 	if (channel === "nightly") {
 		const url = `${apiOrigin}/repos/${RELEASE_REPO}/releases?per_page=40`;
-		const payload = await readGithubJson(url, options);
+		// Nightly has no unauthenticated web listing to fall back to, so a spent
+		// budget can only be answered with the token hint.
+		const payload = await readGithubJson(url, options).catch((error: unknown) => {
+			if (error instanceof GithubApiStatusError && error.isRateLimited) {
+				throw new Error(`${error.message}. ${TOKEN_HINT}`);
+			}
+			throw error;
+		});
 		if (!Array.isArray(payload)) {
 			throw new Error(`${url} did not return a release list`);
 		}
@@ -139,8 +205,24 @@ export async function fetchGithubChannelRelease(options: GithubReleaseLookupOpti
 		);
 	}
 	const url = `${apiOrigin}/repos/${RELEASE_REPO}/releases/latest`;
-	const payload = await readGithubJson(url, options);
-	return parseRelease(payload, "stable");
+	try {
+		return parseRelease(await readGithubJson(url, options), "stable");
+	} catch (error) {
+		if (!(error instanceof GithubApiStatusError) || !error.isRateLimited) throw error;
+		try {
+			const tag = await resolveStableReleaseTagFromWeb(options);
+			return {
+				tag,
+				version: versionFromTag(tag),
+				channel: "stable",
+				htmlUrl: `${options.webOrigin ?? GITHUB_WEB_ORIGIN}/${RELEASE_REPO}/releases/tag/${tag}`,
+				warnings: [`${error.message}; resolved the latest stable tag through github.com instead. ${TOKEN_HINT}`],
+			};
+		} catch (fallbackError) {
+			const detail = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+			throw new Error(`${error.message}, and the github.com fallback failed: ${detail}. ${TOKEN_HINT}`);
+		}
+	}
 }
 
 export function parseChecksumForAsset(text: string, assetName: string): string | undefined {

package/src/cli/mcp-cli.ts

@@ -19,7 +19,13 @@ import {
 	resolveScopeMCPConfigPath,
 	upsertScopeMCPServer,
 } from "../runtime-mcp/scope-config";
-import { type AutoloadStatus, computeAutoloadStatus } from "../runtime-mcp/startup-policy";
+import {
+	type AutoloadStatus,
+	computeAutoloadStatus,
+	DEFAULT_MCP_STARTUP_WAIT_MS,
+	MAX_MCP_STARTUP_WAIT_MS,
+	MCP_STARTUP_WAIT_GRACE_MS,
+} from "../runtime-mcp/startup-policy";
 import type { MCPServerConfig } from "../runtime-mcp/types";
 
 export type MCPAction = "add" | "list" | "remove";
@@ -64,6 +70,8 @@ interface RuntimeServerEntry extends RedactedServerEntry {
 	runtimeStatus: AutoloadStatus;
 	/** Human-readable explanation of the runtime status. */
 	runtimeNote: string;
+	/** Actionable guidance when startup can disconnect an untimed registration. */
+	startupDiagnostic?: string;
 }
 
 const REDACTED = "<redacted>";
@@ -90,6 +98,18 @@ function autoloadStatusNote(status: AutoloadStatus): string {
 	}
 }
 
+function startupDiagnostic(config: MCPServerConfig, status: AutoloadStatus): string | undefined {
+	if (status !== "autoload") return undefined;
+	const timeout = config.timeout;
+	if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) return undefined;
+	return (
+		`No per-server timeout is declared. Ordinary standalone sessions wait ${DEFAULT_MCP_STARTUP_WAIT_MS}ms when no ` +
+		`registration declares a positive timeout; otherwise the batch wait uses the largest declared timeout plus ` +
+		`${MCP_STARTUP_WAIT_GRACE_MS}ms grace, capped at ${MAX_MCP_STARTUP_WAIT_MS}ms. Unfinished connections are ` +
+		"disconnected; add --timeout <ms> when registering slower servers."
+	);
+}
+
 function resolvePath(args: MCPCommandArgs): ScopedPath {
 	const scope: MCPConfigScope = args.flags.project ? "project" : "user";
 	return { scope, path: resolveScopeMCPConfigPath(scope, args.cwd ?? getProjectDir()) };
@@ -243,8 +263,14 @@ export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig
 function withRuntimeDisclosure<T extends object>(
 	value: T,
 	status: AutoloadStatus,
+	diagnostic?: string,
 ): T & { runtimeStatus: AutoloadStatus; runtimeNote: string } {
-	return { ...value, runtimeStatus: status, runtimeNote: autoloadStatusNote(status) };
+	return {
+		...value,
+		runtimeStatus: status,
+		runtimeNote: autoloadStatusNote(status),
+		...(diagnostic === undefined ? {} : { startupDiagnostic: diagnostic }),
+	};
 }
 
 async function collectEntries(scoped: ScopedPath, cwd?: string): Promise<RuntimeServerEntry[]> {
@@ -257,12 +283,14 @@ async function collectEntries(scoped: ScopedPath, cwd?: string): Promise<Runtime
 		.sort(([a], [b]) => a.localeCompare(b))
 		.map(([name, serverConfig]) => {
 			const runtimeStatus = computeAutoloadStatus(name, serverConfig, disabledSet);
+			const diagnostic = startupDiagnostic(serverConfig, runtimeStatus);
 			return {
 				name,
 				scope: scoped.scope,
 				path: scoped.path,
 				runtimeStatus,
 				runtimeNote: autoloadStatusNote(runtimeStatus),
+				...(diagnostic === undefined ? {} : { startupDiagnostic: diagnostic }),
 				config: redactMCPServerConfig(serverConfig),
 			};
 		});
@@ -297,9 +325,11 @@ async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 		},
 		args.cwd,
 	);
-	const redacted = redactMCPServerConfig(config);
+	const disclosedConfig = result.status === "skipped" ? (storedConfig.mcpServers?.[args.name] ?? config) : config;
+	const redacted = redactMCPServerConfig(disclosedConfig);
 	const disabled = new Set(storedConfig.disabledServers ?? (await readScopeDisabledServers(scoped.scope, args.cwd)));
-	const runtimeStatus = computeAutoloadStatus(args.name, config, disabled);
+	const runtimeStatus = computeAutoloadStatus(args.name, disclosedConfig, disabled);
+	const diagnostic = startupDiagnostic(disclosedConfig, runtimeStatus);
 	if (args.flags.json) {
 		writeJson(
 			withRuntimeDisclosure(
@@ -312,6 +342,7 @@ async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 					config: redacted,
 				},
 				runtimeStatus,
+				diagnostic,
 			),
 		);
 		return;
@@ -321,12 +352,14 @@ async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
 			`MCP server "${args.name}" already exists in ${scoped.scope} config. Pass --force to overwrite. ` +
 				`Runtime: ${autoloadStatusNote(runtimeStatus)}\n`,
 		);
+		if (diagnostic) process.stdout.write(`Startup: ${diagnostic}\n`);
 		return;
 	}
 	process.stdout.write(
 		`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\n` +
 			`Runtime: ${autoloadStatusNote(runtimeStatus)}\n`,
 	);
+	if (diagnostic) process.stdout.write(`Startup: ${diagnostic}\n`);
 }
 
 async function runList(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
@@ -348,6 +381,7 @@ async function runList(args: MCPCommandArgs, scoped: ScopedPath): Promise<void>
 	for (const entry of entries) {
 		process.stdout.write(`${renderDetails(entry)}\n`);
 		process.stdout.write(`Runtime: ${entry.runtimeNote}\n`);
+		if (entry.startupDiagnostic) process.stdout.write(`Startup: ${entry.startupDiagnostic}\n`);
 	}
 }