@sayknow-cli/coding-agent 0.2.3 → 0.2.5

package/src/modes/interactive-mode.ts

@@ -44,7 +44,7 @@ import { BUILTIN_SLASH_COMMANDS, loadSlashCommands } from "../extensibility/slas
 import { type Goal, type GoalModeState, normalizeGoal } from "../goals/state";
 import { t } from "../i18n";
 import { resolveLocalUrlToPath } from "../internal-urls";
-import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
+import { getLspStartupWarningMessage, LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
 import {
 	humanizePlanTitle,
 	type PlanApprovalDetails,
@@ -72,6 +72,7 @@ import { normalizeLocalScheme } from "../tools/path-utils";
 import { type ResolveToolDetails, runResolveInvocation } from "../tools/resolve";
 import { formatPhaseDisplayName } from "../tools/todo-write";
 import { ToolError } from "../tools/tool-errors";
+
 import type { EventBus } from "../utils/event-bus";
 import { getEditorCommand, openInEditor } from "../utils/external-editor";
 import { getSessionAccentAnsi, getSessionAccentHex } from "../utils/session-color";
@@ -86,7 +87,11 @@ import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent } from "./components/hook-selector";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
-import { WelcomeComponent, type LspServerInfo as WelcomeLspServerInfo } from "./components/welcome";
+import {
+	WelcomeComponent,
+	type WelcomeLogoMode,
+	type LspServerInfo as WelcomeLspServerInfo,
+} from "./components/welcome";
 import { BtwController } from "./controllers/btw-controller";
 import { CommandController } from "./controllers/command-controller";
 import { EventController } from "./controllers/event-controller";
@@ -218,6 +223,21 @@ function parseGoalSubcommand(args: string): { sub: GoalSubcommand | undefined; r
 	return { sub: undefined, rest: trimmed };
 }
 
+export type WelcomeBannerSettingMode = "auto" | "unicode" | "square" | "ascii";
+
+export function resolveWelcomeLogoMode(
+	mode: WelcomeBannerSettingMode,
+	env: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): WelcomeLogoMode {
+	void env;
+	void platform;
+	if (mode === "unicode") return "unicode";
+	if (mode === "square") return "square";
+	if (mode === "ascii") return "ascii";
+	return "unicode";
+}
+
 /** Options for creating an InteractiveMode instance (for future API use) */
 export interface InteractiveModeOptions {
 	/** Providers that were migrated during startup */
@@ -479,6 +499,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		);
 
 		const startupQuiet = settings.get("startup.quiet");
+		const welcomeLogoMode = resolveWelcomeLogoMode(settings.get("startup.welcomeBannerMode"));
 		this.#welcomeComponent = undefined;
 
 		for (const warning of this.session.configWarnings) {
@@ -494,6 +515,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				providerName,
 				recentSessions,
 				this.#getWelcomeLspServers(),
+				welcomeLogoMode,
 			);
 
 			// Setup UI layout
@@ -2062,23 +2084,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	#handleLspStartupEvent(event: LspStartupEvent): void {
 		this.#updateWelcomeLspServers();
 
-		if (event.type === "failed") {
-			this.showWarning(`LSP startup failed: ${event.error}. It will retry lazily on write.`);
-			return;
-		}
-
-		const failedServers = event.servers.filter(server => server.status === "error");
-
-		if (failedServers.length === 1) {
-			const failedServer = failedServers[0];
-			const detail = failedServer.error ? `: ${failedServer.error}` : "";
-			this.showWarning(`LSP startup failed for ${failedServer.name}${detail}. It will retry lazily on write.`);
-			return;
-		}
-
-		if (failedServers.length > 1) {
-			const failedNames = failedServers.map(server => server.name).join(", ");
-			this.showWarning(`LSP startup failed for ${failedNames}. It will retry lazily on write.`);
+		const warningMessage = getLspStartupWarningMessage(event);
+		if (warningMessage) {
+			this.showWarning(warningMessage);
 		}
 	}
 

package/src/modes/prompt-action-autocomplete.ts

@@ -28,6 +28,7 @@ interface PromptActionAutocompleteOptions {
 	keybindings: KeybindingsManager;
 	copyCurrentLine: () => void;
 	copyPrompt: () => void;
+	pasteImage: () => void;
 	undo: (prefix: string) => void;
 	moveCursorToMessageEnd: () => void;
 	moveCursorToMessageStart: () => void;
@@ -190,7 +191,9 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			const query = promptActionPrefix.slice(1).toLowerCase();
 			const items = this.#actions
 				.map(action => {
-					const searchable = [action.label, action.description, ...action.keywords].join(" ").toLowerCase();
+					const searchable = [action.id, action.label, action.description, ...action.keywords]
+						.join(" ")
+						.toLowerCase();
 					if (!fuzzyMatch(query, searchable)) return null;
 					return {
 						value: action.label,
@@ -368,6 +371,13 @@ export function createPromptActionAutocompleteProvider(
 			keywords: ["copy", "prompt", "clipboard", "message"],
 			execute: options.copyPrompt,
 		},
+		{
+			id: "paste-image",
+			label: "Paste image from clipboard",
+			description: formatKeyHints(options.keybindings.getKeys("app.clipboard.pasteImage")),
+			keywords: ["paste", "image", "clipboard", "screenshot", "attach", "vision"],
+			execute: options.pasteImage,
+		},
 		{
 			id: "undo",
 			label: "Undo",

package/src/modes/rpc/rpc-mode.ts

@@ -11,7 +11,6 @@
  * - Extension UI: Extension UI requests are emitted, client responds with extension_ui_response
  */
 
-import * as path from "node:path";
 import { $pickenv, logger, readLines, Snowflake } from "@sayknow-cli/utils";
 import type {
 	ExtensionUIContext,
@@ -20,6 +19,7 @@ import type {
 } from "../../extensibility/extensions";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { AgentSession } from "../../session/agent-session";
+import { workflowGatePath } from "../../skc-runtime/session-layout";
 import { initializeExtensions } from "../runtime-init";
 import { dispatchRpcCommand } from "../shared/agent-wire/command-dispatch";
 import { AgentWireFrameSequencer, toAgentWireEventFrame } from "../shared/agent-wire/event-envelope";
@@ -336,7 +336,7 @@ export async function runRpcMode(
 	// Unattended control plane (#318/#319/#323/G011): routes negotiate_unattended +
 	// workflow_gate_response and lets skill runtimes emit gates over RPC.
 	const gateStore = new FileGateStore(
-		path.join(session.sessionManager.getCwd(), ".skc", "state", "workflow-gates", `${session.sessionId}.json`),
+		workflowGatePath(session.sessionManager.getCwd(), session.sessionId, session.sessionId),
 	);
 	const unattendedControlPlane = new UnattendedSessionControlPlane({
 		runId: session.sessionId,

package/src/modes/shared/agent-wire/unattended-audit.ts

@@ -12,6 +12,7 @@
  */
 import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import * as path from "node:path";
+import { sessionAuditDir } from "../../../skc-runtime/session-layout";
 import type { RpcBudgetExceeded, RpcWorkflowGateKind, RpcWorkflowStage } from "../../rpc/rpc-types";
 import { answerHashOf } from "./workflow-gate-schema";
 
@@ -69,9 +70,9 @@ function defaultId(): string {
 	return `ae_${Date.now().toString(36)}_${idCounter.toString(36)}`;
 }
 
-export function defaultAuditPath(runId: string, root = process.cwd()): string {
+export function defaultAuditPath(runId: string, root = process.cwd(), skcSessionId = runId): string {
 	const safe = runId.replace(/[^a-zA-Z0-9_.-]/g, "_");
-	return path.join(root, ".skc", "audit", "unattended", `${safe}.jsonl`);
+	return path.join(sessionAuditDir(root, skcSessionId), "unattended", `${safe}.jsonl`);
 }
 
 /** Append-only audit log writer + reader for one unattended run. */

package/src/prompts/agents/init.md

@@ -5,7 +5,7 @@ thinking-level: medium
 hide: true
 ---
 
-Generate AGENTS.md by launching multiple `explore` agents in parallel (via `task` tool) scanning different areas (core src, tests, configs/build, scripts/docs), then synthesize findings into a single file.
+Generate AGENTS.md by launching multiple canonical role agents in parallel (via `task` tool, usually `planner` or `architect`) scanning different areas (core src, tests, configs/build, scripts/docs), then synthesize findings into a single file.
 
 <structure>
 - **Project Overview**: Brief description of project purpose

package/src/prompts/system/plan-mode-active.md

@@ -82,7 +82,7 @@ The plan MUST be scannable yet detailed enough to execute.
 
 <procedure>
 ### Phase 1: Understand
-You MUST focus on the request and associated code. You SHOULD launch parallel explore agents when scope spans multiple areas.
+You MUST focus on the request and associated code. You SHOULD launch parallel canonical role agents (`planner` or `architect`) when scope spans multiple areas.
 
 ### Phase 2: Design
 You MUST draft an approach based on exploration. You MUST consider trade-offs briefly, then choose.

package/src/prompts/tools/ast-grep.md

@@ -38,5 +38,5 @@ Performs structural code search using AST matching via native ast-grep.
 <critical>
 - Avoid repo-root scans — narrow `paths` first
 - Parse issues are query failure, not evidence of absence: repair the pattern or tighten `paths` before concluding "no matches"
-- For broad/open-ended exploration across subsystems, use Task tool with explore subagent first
+- For broad/open-ended inspection across subsystems, delegate a bounded fact-finding task to an appropriate canonical role agent (`planner` or `architect`) first
 </critical>

package/src/prompts/tools/search.md

@@ -21,5 +21,5 @@ Searches files using powerful regex matching.
 - You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
 - Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
 - If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
-- If the search is open-ended, requiring multiple rounds, you MUST use the Task tool with the explore subagent instead of chaining `search` calls yourself.
+- If the search is open-ended and requires multiple rounds across subsystems, delegate a bounded fact-finding task to an appropriate canonical role agent (`planner` for sequencing/context maps or `architect` for read-only architecture assessment) instead of chaining broad `search` calls yourself.
 </critical>

package/src/prompts/tools/task.md

@@ -28,13 +28,12 @@ Subagents have no conversation history. Every fact, file path, and direction the
 {{/if}}
 {{#if independentMode}}- `.inheritContext`: independent mode cannot inherit parent conversation. Omit it or set `"none"`; any non-`none` value is rejected before scheduling.{{/if}}
 {{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
-- `spawnPlan` (optional): required before any batch with more than 4 tasks, and before a reviewer agent spawns `explore`; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
+- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
 {{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
 </parameters>
 
 <rules>
 - HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.
-- Reviewer->explore gate: a `reviewer` spawning `explore` is rejected before launch unless `spawnPlan` is complete, even for a single task.
 - NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
 - **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
 {{#if ircEnabled}}

package/src/research-plan/index.ts

@@ -0,0 +1 @@
+export * from "./ledger";

package/src/research-plan/ledger.ts

@@ -0,0 +1,177 @@
+export type ResearchPlanConfidence = "low" | "medium" | "high";
+
+export type ResearchEvidenceVerdict = "support" | "contradict" | "uncertain";
+
+export interface ResearchPlanItem {
+	claim: string;
+	confidence: ResearchPlanConfidence;
+	unknowns: string[];
+	evidenceNeeded: string[];
+	counterexampleQueries: string[];
+	sourceConflictPolicy: string;
+	dropCondition: string;
+	verifierChecks: string[];
+}
+
+export interface ResearchEvidenceEntry {
+	claim: string;
+	source: string;
+	confidence: ResearchPlanConfidence;
+	verdict: ResearchEvidenceVerdict;
+	notes?: string;
+}
+
+export interface ResearchLedgerVerdict {
+	claim: string;
+	finalVerdict: "accepted" | "rejected" | "uncertain";
+	survivingSources: ResearchEvidenceEntry[];
+	rejectReason?: string;
+	unresolvedUnknowns: string[];
+}
+
+export interface ResearchPlanValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+const CONFIDENCE_VALUES = new Set<ResearchPlanConfidence>(["low", "medium", "high"]);
+const EVIDENCE_VERDICTS = new Set<ResearchEvidenceVerdict>(["support", "contradict", "uncertain"]);
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function validateStringArray(value: unknown, field: string, minLength = 1): string[] {
+	if (!Array.isArray(value)) return [`${field} must be an array`];
+	if (value.length < minLength) return [`${field} must contain at least ${minLength} item(s)`];
+	return value.flatMap((item, index) =>
+		isNonEmptyString(item) ? [] : [`${field}[${index}] must be a non-empty string`],
+	);
+}
+
+export function validateResearchPlanItem(item: Partial<ResearchPlanItem>): ResearchPlanValidationResult {
+	const errors: string[] = [];
+	if (!isNonEmptyString(item.claim)) errors.push("claim must be a non-empty string");
+	if (!item.confidence || !CONFIDENCE_VALUES.has(item.confidence)) {
+		errors.push("confidence must be one of: low, medium, high");
+	}
+	errors.push(...validateStringArray(item.unknowns, "unknowns", 0));
+	errors.push(...validateStringArray(item.evidenceNeeded, "evidenceNeeded"));
+	errors.push(...validateStringArray(item.counterexampleQueries, "counterexampleQueries"));
+	if (!isNonEmptyString(item.sourceConflictPolicy)) errors.push("sourceConflictPolicy must be a non-empty string");
+	if (!isNonEmptyString(item.dropCondition)) errors.push("dropCondition must be a non-empty string");
+	errors.push(...validateStringArray(item.verifierChecks, "verifierChecks"));
+	return { valid: errors.length === 0, errors };
+}
+
+export function validateResearchEvidenceEntry(entry: Partial<ResearchEvidenceEntry>): ResearchPlanValidationResult {
+	const errors: string[] = [];
+	if (!isNonEmptyString(entry.claim)) errors.push("claim must be a non-empty string");
+	if (!isNonEmptyString(entry.source)) errors.push("source must be a non-empty string");
+	if (!entry.confidence || !CONFIDENCE_VALUES.has(entry.confidence)) {
+		errors.push("confidence must be one of: low, medium, high");
+	}
+	if (!entry.verdict || !EVIDENCE_VERDICTS.has(entry.verdict)) {
+		errors.push("verdict must be one of: support, contradict, uncertain");
+	}
+	return { valid: errors.length === 0, errors };
+}
+
+function lower(value: string): string {
+	return value.toLowerCase();
+}
+
+function matchesDropCondition(item: ResearchPlanItem, evidence: ResearchEvidenceEntry[]): string | undefined {
+	const condition = lower(item.dropCondition);
+	const contradiction = evidence.find(entry => entry.verdict === "contradict");
+	if (contradiction && /(counterexample|contradict|conflict|falsif)/.test(condition)) {
+		return `dropCondition matched by contradictory source: ${contradiction.source}`;
+	}
+	const unresolved = evidence.find(entry => entry.verdict === "uncertain");
+	if (unresolved && /(unknown|unresolved|uncertain)/.test(condition)) {
+		return `dropCondition matched by unresolved evidence: ${unresolved.source}`;
+	}
+	return undefined;
+}
+
+function sourceConflictReason(item: ResearchPlanItem, evidence: ResearchEvidenceEntry[]): string | undefined {
+	const supporting = evidence.filter(entry => entry.verdict === "support");
+	const contradicting = evidence.filter(entry => entry.verdict === "contradict");
+	if (supporting.length === 0 || contradicting.length === 0) return undefined;
+	const policy = lower(item.sourceConflictPolicy);
+	if (/(reject|drop|do not accept|prefer contradiction|requires resolution)/.test(policy)) {
+		return `sourceConflictPolicy rejected mixed support/contradiction (${supporting.length} support, ${contradicting.length} contradict)`;
+	}
+	return "source conflict remains unresolved";
+}
+
+export function evaluateResearchLedger(
+	item: ResearchPlanItem,
+	evidence: readonly ResearchEvidenceEntry[],
+): ResearchLedgerVerdict {
+	const relevantEvidence = evidence.filter(entry => entry.claim === item.claim);
+	const invalidItem = validateResearchPlanItem(item);
+	if (!invalidItem.valid) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: [],
+			rejectReason: `invalid research plan item: ${invalidItem.errors.join("; ")}`,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const invalidEvidence = relevantEvidence.flatMap(entry => validateResearchEvidenceEntry(entry).errors);
+	if (invalidEvidence.length > 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: [],
+			rejectReason: `invalid evidence entry: ${invalidEvidence.join("; ")}`,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	if (relevantEvidence.length === 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "uncertain",
+			survivingSources: [],
+			rejectReason: "no evidence collected for claim",
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const supporting = relevantEvidence.filter(entry => entry.verdict === "support");
+	const firstContradiction = relevantEvidence.find(entry => entry.verdict === "contradict");
+	let dropReason = matchesDropCondition(item, relevantEvidence) ?? sourceConflictReason(item, relevantEvidence);
+	// A counterexample with no surviving support falsifies the claim regardless of how the
+	// dropCondition / sourceConflictPolicy prose is worded. Without this, a purely contradicted
+	// claim would slip through as "uncertain" and reopen the hallucination survival path the
+	// evidence ledger exists to close (a contested claim already rejects via sourceConflictReason).
+	if (!dropReason && firstContradiction && supporting.length === 0) {
+		dropReason = `claim contradicted by counterexample with no supporting evidence: ${firstContradiction.source}`;
+	}
+	if (dropReason) {
+		return {
+			claim: item.claim,
+			finalVerdict: "rejected",
+			survivingSources: supporting,
+			rejectReason: dropReason,
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	const uncertain = relevantEvidence.some(entry => entry.verdict === "uncertain");
+	if (uncertain || supporting.length === 0) {
+		return {
+			claim: item.claim,
+			finalVerdict: "uncertain",
+			survivingSources: supporting,
+			rejectReason: uncertain ? "unresolved uncertainty remains" : "no supporting evidence survived verification",
+			unresolvedUnknowns: item.unknowns,
+		};
+	}
+	return {
+		claim: item.claim,
+		finalVerdict: "accepted",
+		survivingSources: supporting,
+		unresolvedUnknowns: [],
+	};
+}

package/src/rlm/artifacts.ts

@@ -1,12 +1,17 @@
 /**
- * RLM session artifact layout under <cwd>/.skc/rlm/<sessionId>/.
+ * RLM session artifact layout under <cwd>/.skc/_session-{skcSessionId}/rlm/<rlmSessionId>/.
+ *
+ * The SKC session id (process boundary) scopes the directory; the RLM session id
+ * names the individual research run within it. The two ids are kept distinct.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { readNotebookDocument } from "../edit/notebook";
+import { rlmArtifactRoot } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForWrite } from "../skc-runtime/session-resolution";
 import type { RlmArtifactPaths } from "./types";
 
-export const RLM_DIR_SEGMENT = path.join(".skc", "rlm");
+export const RLM_DIR_SEGMENT = "rlm";
 
 const SESSION_ID_RE = /^[A-Za-z0-9_-]+$/;
 
@@ -25,7 +30,11 @@ export function resolveRlmArtifactPaths(cwd: string, sessionId: string): RlmArti
 	if (!isValidRlmSessionId(sessionId)) {
 		throw new Error(`Invalid RLM session id: ${JSON.stringify(sessionId)}`);
 	}
-	const dir = path.join(cwd, RLM_DIR_SEGMENT, sessionId);
+	const dir = rlmArtifactRoot(
+		cwd,
+		resolveSkcSessionForWrite(cwd, { envSessionId: process.env.SKC_SESSION_ID }).skcSessionId,
+		sessionId,
+	);
 	return {
 		dir,
 		notebookPath: path.join(dir, "notebook.ipynb"),

package/src/rlm/index.ts

@@ -15,6 +15,7 @@ import { type RlmPreset, runRootCommand } from "../main";
 import rlmReportCommandPrompt from "../prompts/system/rlm-report-command.md" with { type: "text" };
 import type { CreateAgentSessionOptions } from "../sdk";
 import type { AgentSession } from "../session/agent-session";
+import { resolveSessionIdFromSources, writeSessionActivityMarker } from "../skc-runtime/session-resolution";
 import {
 	ensureRlmSessionDir,
 	generateRlmSessionId,
@@ -231,6 +232,12 @@ async function writeRlmMetadata(input: {
 		successfulRuns: input.successfulRuns,
 	};
 	await Bun.write(input.paths.metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+	// Best-effort: update the per-session activity marker so latest-session auto-detect
+	// accounts for RLM-only generated output (AC2). Never let marker failure break RLM.
+	const skcSessionId = resolveSessionIdFromSources({ envSessionId: process.env.SKC_SESSION_ID })?.skcSessionId;
+	if (skcSessionId) {
+		await writeSessionActivityMarker(input.cwd, skcSessionId, { writer: "rlm" }).catch(() => {});
+	}
 }
 
 export async function runRlmCommand(argv: string[]): Promise<void> {

package/src/runtime-mcp/config-writer.ts

@@ -149,6 +149,52 @@ export async function updateMCPServer(filePath: string, name: string, config: MC
 	await writeMCPConfigFile(filePath, updated);
 }
 
+/**
+ * Result of an {@link upsertMCPServer} call.
+ * - `added`: server did not exist and was written.
+ * - `updated`: server existed and was overwritten because `force` was set.
+ * - `skipped`: server existed and `force` was not set, so nothing was written.
+ */
+export type UpsertMCPServerResult =
+	| { status: "added" }
+	| { status: "updated" }
+	| { status: "skipped"; reason: "exists" };
+
+/**
+ * Add an MCP server, or overwrite an existing one only when `force` is set.
+ *
+ * Collision-aware wrapper over {@link addMCPServer} / {@link updateMCPServer} used by
+ * `skc migrate`. Never connects to the server. Reuses the underlying writers so the
+ * rest of the config file (including `disabledServers`) is preserved on update.
+ *
+ * @throws Error if the server name or config is invalid (validated before any write).
+ */
+export async function upsertMCPServer(
+	filePath: string,
+	name: string,
+	config: MCPServerConfig,
+	options: { force?: boolean } = {},
+): Promise<UpsertMCPServerResult> {
+	// Validate name up front so an invalid name fails regardless of collision state.
+	const nameError = validateServerName(name);
+	if (nameError) {
+		throw new Error(nameError);
+	}
+
+	const existing = await getMCPServer(filePath, name);
+	if (existing) {
+		if (!options.force) {
+			return { status: "skipped", reason: "exists" };
+		}
+		// updateMCPServer preserves the rest of MCPConfigFile, incl. disabledServers.
+		await updateMCPServer(filePath, name, config);
+		return { status: "updated" };
+	}
+
+	await addMCPServer(filePath, name, config);
+	return { status: "added" };
+}
+
 /**
  * Remove an MCP server from a config file.
  *