@gethmy/mcp 3.7.0 → 3.9.0

package/src/api-client.ts

@@ -6,6 +6,7 @@ import {
   type PlaybookVersionDef,
   type StageGateEvidenceInsert,
   type StageGateEvidenceRow,
+  sanitizeRunEventDraft,
   serializeCommentThread,
   untrustedDataBlock,
   type WorkspaceAgent,
@@ -19,6 +20,16 @@ export interface ApiResponse<T = unknown> {
   [key: string]: T | boolean | string | undefined;
 }
 
+/** One `model_catalog` row (#1104). See `getModelCatalog`. */
+export interface ModelCatalogRow {
+  id: string;
+  display_name?: string | null;
+  status: "available" | "deprecated" | "withdrawn";
+  replaced_by?: string | null;
+  sort_order?: number;
+  notes?: string | null;
+}
+
 // Retry configuration
 const RETRY_CONFIG = {
   maxRetries: 3,
@@ -559,6 +570,46 @@ export class HarmonyApiClient {
     return this.request("POST", `/workspaces/${workspaceId}/agents`, data);
   }
 
+  /**
+   * Report the effective model config this daemon resolved (#1104). Advisory:
+   * the board renders it, nothing routes on it, so a failure here must never
+   * stop a daemon from starting.
+   */
+  async reportAgentConfig(
+    workspaceId: string,
+    agentId: string,
+    config: unknown,
+  ): Promise<{ agent: WorkspaceAgent }> {
+    return this.request(
+      "POST",
+      `/workspaces/${workspaceId}/agents/${agentId}/reported-config`,
+      { config },
+    );
+  }
+
+  /**
+   * The workspace's own model layer (#1104) — `GET /v1/workspaces/:id/model-config`.
+   * `config` is `null` when the workspace has not set one. Deliberately untyped
+   * (`Record<string, unknown>`, not `WorkspaceModelConfig`): this client has no
+   * dependency on `@gethmy/agent`, so the caller (`workspace-model-cache.ts`)
+   * parses the blob into its own shape.
+   */
+  async getWorkspaceModelConfig(
+    workspaceId: string,
+  ): Promise<{ config: Record<string, unknown> | null }> {
+    return this.request("GET", `/workspaces/${workspaceId}/model-config`);
+  }
+
+  /**
+   * The platform-owned supported-model catalog (#1104) — `GET /v1/model-catalog`.
+   * Open to any authenticated caller; a model id is not a secret. The daemon
+   * derives a withdrawn→replacement map from the `withdrawn` rows here and
+   * hands it to `chooseImplementModel`'s `catalog` parameter.
+   */
+  async getModelCatalog(): Promise<{ models: ModelCatalogRow[] }> {
+    return this.request("GET", "/model-catalog");
+  }
+
   // ============ PROJECT OPERATIONS ============
 
   async listProjects(workspaceId: string): Promise<{ projects: unknown[] }> {
@@ -924,6 +975,13 @@ export class HarmonyApiClient {
     });
   }
 
+  async removeExternalLink(
+    cardId: string,
+    linkId: string,
+  ): Promise<{ success: boolean }> {
+    return this.request("DELETE", `/cards/${cardId}/external-links/${linkId}`);
+  }
+
   // ============ ARTIFACTS (hosted HTML documents) ============
 
   async uploadArtifact(data: {
@@ -1409,6 +1467,26 @@ export class HarmonyApiClient {
   /**
    * Append events to a run's agent_run_events stream (card #417). Send drafts in
    * chronological order — the server's seq trigger assigns the monotonic per-run order.
+   *
+   * **Every draft is sanitized here, because this is the one place all three
+   * writers meet (#1110).** `agent_run_events.payload` is JSONB, and Postgres
+   * refuses a JSON string carrying U+0000 or a lone surrogate — it rejects the
+   * whole statement rather than truncating. Measured 75 times in the 2026-09-06
+   * daemon log as `unsupported Unicode escape sequence`, and tool output is
+   * exactly where such a byte comes from (a `grep` over a binary, a compiler
+   * dumping a fixture).
+   *
+   * Three callers reach this method and they fail in different ways, which is
+   * why the repair belongs here rather than at any one of them:
+   *   - `CliAgentRunner.enqueue` (harmony-agent) retries three times, bisects,
+   *     and drops the single bad event — correct handling, still a lost row.
+   *   - `RunEventForwarder.flush` (the MCP `PostToolUse` hook) leaves the batch
+   *     on disk and retries with backoff for ~10 minutes, BLOCKING every later
+   *     tool call queued behind it, then drops the pair.
+   *   - `ci-repair.ts` posts a `detail` built from CI output.
+   * The runner sanitizes again on its own path, above its size check, so a NUL
+   * never costs bytes against the ceiling; that is defence in depth, not a
+   * duplicate — this is the boundary a fourth writer gets for free.
    */
   async appendAgentRunEvents(
     cardId: string,
@@ -1417,7 +1495,10 @@ export class HarmonyApiClient {
       events: (AgentRunEventDraft & { createdAt?: string })[];
     },
   ): Promise<{ inserted: number }> {
-    return this.request("POST", `/cards/${cardId}/agent-run-events`, data);
+    return this.request("POST", `/cards/${cardId}/agent-run-events`, {
+      ...data,
+      events: data.events.map((event) => sanitizeRunEventDraft(event)),
+    });
   }
 
   /**
@@ -1972,12 +2053,21 @@ export class HarmonyApiClient {
     return this.request("GET", `/cards/${cardId}/plan`);
   }
 
+  /**
+   * `startDate` / `endDate` are the plan's own timeline dates (card #1119),
+   * `YYYY-MM-DD` or `null` to return the plan to its cards' derived span. They
+   * are pinned together or not at all — sending one on an unpinned plan is
+   * refused by the route, with a reason that names the missing half. Absent from
+   * a harmony-api older than #1119, where they are silently dropped.
+   */
   async updatePlan(
     planId: string,
     updates: {
       title?: string;
       content?: string;
       status?: "draft" | "active" | "archived";
+      startDate?: string | null;
+      endDate?: string | null;
     },
   ): Promise<{ plan: unknown }> {
     return this.request("PATCH", `/plans/${planId}`, updates);

package/src/config.ts

@@ -1,5 +1,6 @@
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 
 export interface HarmonyConfig {
@@ -93,6 +94,10 @@ let warnedLegacyLocalPin = false;
 export function resetLegacyNoticesForTest(): void {
   warnedLegacyConfigDir = false;
   warnedLegacyLocalPin = false;
+  // #1115's notice latches the same way and for the same reason, so it is
+  // cleared here too — a "said once" contract nothing can reset is a contract
+  // no test can check.
+  warnedUntrackedLocalPin = false;
 }
 
 function noteLegacyConfigDir(path: string): void {
@@ -105,13 +110,30 @@ function noteLegacyConfigDir(path: string): void {
   );
 }
 
-/** Said once when a repo pin is read under the old name. */
+/**
+ * Said once when a repo pin is read under the old name.
+ *
+ * It names the COMMAND, not the outcome (#1108). "Rename it to `.hmy.json`"
+ * described a result and left every operator doing it by hand in every repo —
+ * eight of them on the author's machine, none migrated — while
+ * `harmony-agent doctor --fix` had to be found by reading the source. A notice
+ * for a temporary fallback is worth nothing if acting on it is the hard part.
+ *
+ * The manual rename stays beside it, for two readers the command does not
+ * serve: `harmony-agent` is the bin of `@gethmy/agent`, so a client running
+ * `@gethmy/mcp` alone does not have it — and an INSTALLED agent older than
+ * #1108 accepts the unknown `--fix`, prints `preflight ok` and exits 0 without
+ * migrating anything, which is a false green the notice must not lead a reader
+ * into trusting.
+ */
 export function noteLegacyLocalPin(path: string): void {
   if (warnedLegacyLocalPin) return;
   warnedLegacyLocalPin = true;
   console.error(
     `Harmony: this repo is pinned by ${path}, the pre-#1082 name. ` +
-      `Rename it to ${LOCAL_CONFIG_FILENAME} — the fallback that finds it is temporary.`,
+      `Run \`harmony-agent doctor --fix\` in this repo to write ` +
+      `${LOCAL_CONFIG_FILENAME}, or rename the file yourself. ` +
+      `The fallback that finds it is temporary.`,
   );
 }
 
@@ -122,6 +144,54 @@ function noteLocalPinRename(from: string, to: string): void {
   );
 }
 
+let warnedUntrackedLocalPin = false;
+
+/**
+ * Say once that the file we just wrote will not travel with the branch (#1115).
+ *
+ * The whole argument for putting a repo's commands in the repo is that a
+ * BRANCH carries them: what the file says is then true of the code beside it,
+ * with nothing to keep in sync. A git-ignored file has none of that property —
+ * a fresh clone does not have it, a daemon worktree does not have it, and a
+ * working directory does. That exact difference is what made FinPunk's build
+ * failure so hard to find: the file existed where a person looked and nowhere
+ * the daemon ran.
+ *
+ * A warning rather than a refusal, because it is the repo's `.gitignore` and
+ * not ours to change, and because a pin holding only workspace ids is a
+ * perfectly reasonable thing to keep out of version control. The sentence names
+ * the consequence rather than issuing an instruction.
+ */
+function noteUntrackedLocalPin(path: string): void {
+  if (warnedUntrackedLocalPin) return;
+  warnedUntrackedLocalPin = true;
+  console.error(
+    `Harmony: ${path} is ignored by git, so it will not travel with a branch — ` +
+      `a fresh clone, and every worktree the agent daemon cuts, will not have it. ` +
+      `Commit it if you want it to describe this repo everywhere.`,
+  );
+}
+
+/**
+ * Is `path` ignored by git? `false` on any doubt.
+ *
+ * `git check-ignore` exits 1 for "not ignored" and 128 outside a repository,
+ * and `execFileSync` throws on both, so every uncertain answer becomes "not
+ * ignored" — the direction that stays quiet. A warning nobody can act on is
+ * worse than no warning.
+ */
+function isGitIgnored(path: string): boolean {
+  try {
+    execFileSync("git", ["check-ignore", "--quiet", path], {
+      cwd: dirname(path),
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * `~/.hmy` — the root the whole `hmy` surface shares. Named separately from
  * `getConfigDir()` because the denylists want the WHOLE tree, not just the
@@ -309,21 +379,199 @@ export function saveLocalConfig(
     noteLocalPinRename(foundPath, localConfigPath);
   }
 
-  const existingConfig = loadLocalConfig(cwd) || {
-    workspaceId: null,
-    projectId: null,
-  };
-  const newConfig = { ...existingConfig, ...config };
-
-  // Remove null values from the saved config for cleaner output
-  const cleanConfig: Record<string, string> = {};
-  if (newConfig.workspaceId) cleanConfig.workspaceId = newConfig.workspaceId;
-  if (newConfig.projectId) cleanConfig.projectId = newConfig.projectId;
+  // Start from the file's RAW contents, not from `LocalConfig` (#1115).
+  //
+  // This function used to rebuild the file from two fields it understands, so
+  // every other key was silently deleted on the next `set_project_context`.
+  // That was survivable while `.hmy.json` held nothing else. It stopped being
+  // survivable the moment the file grew a `commands` block a person writes by
+  // hand: a pin update would have thrown away the repo's own account of how to
+  // build itself, hours or days later, with nothing in the output to connect
+  // the two events.
+  //
+  // The writer deliberately does NOT learn what `commands` means. It is the
+  // daemon that reads them (`repo-commands.ts` in `@gethmy/harness`), and
+  // teaching this package the schema would mean a workspace dependency on a
+  // published package, kept in lockstep, to gain nothing: preserving a key
+  // needs no understanding of it.
+  // Read from where the pin was FOUND, which on a legacy rename is not where
+  // it is about to be written — otherwise the rename would drop every key the
+  // old file carried, which is the same deletion one paragraph up.
+  const existing = readRawLocalConfig(foundPath ?? localConfigPath);
+  const merged: Record<string, unknown> = { ...existing };
+  // Null still means "drop it" for the two fields this function owns — that is
+  // what `set_project_context` with a cleared value has always meant — but it
+  // now says so field by field instead of by omission from a rebuild.
+  if ("workspaceId" in config) {
+    if (config.workspaceId) merged.workspaceId = config.workspaceId;
+    else delete merged.workspaceId;
+  }
+  if ("projectId" in config) {
+    if (config.projectId) merged.projectId = config.projectId;
+    else delete merged.projectId;
+  }
 
-  writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  writeFileSync(
+    localConfigPath,
+    `${JSON.stringify(merged, null, localIndent(localConfigPath))}\n`,
+  );
+  if (isGitIgnored(localConfigPath)) noteUntrackedLocalPin(localConfigPath);
   return localConfigPath;
 }
 
+/**
+ * The file's own contents, as written, or `{}` when there is nothing readable.
+ *
+ * Deliberately untyped: the point is to carry keys this package does not
+ * model. A malformed file yields `{}` rather than throwing — the pin write is
+ * the user's immediate intent and must not fail because of something they did
+ * to the file earlier; the daemon's reader reports the malformed file
+ * separately, and loudly.
+ */
+function readRawLocalConfig(path: string): Record<string, unknown> {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    // No file yet. Nothing is being discarded, so nothing to say.
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Fall through to the notice below.
+  }
+  // The write that follows REPLACES this file. An earlier version of this
+  // comment excused that with "the daemon's reader reports the malformed file
+  // separately, and loudly" — which is false: after the overwrite the file
+  // parses cleanly and carries no `commands`, so the daemon sees a perfectly
+  // good pin and nobody is ever told. Hand-written JSON is exactly where a
+  // syntax error happens, and hand-writing this file is the case #1115
+  // creates.
+  //
+  // A copy and a warning rather than a refusal: the pin write is the user's
+  // immediate intent and must not fail because of something they did to the
+  // file earlier — but the bytes they lose have to land somewhere they can
+  // get them back from.
+  noteUnparsableLocalPin(path, text);
+  return {};
+}
+
+/**
+ * Keep a copy of an unparsable pin, and say so, before it is overwritten
+ * (#1115).
+ *
+ * The copy goes to the system temp directory, NOT beside the file. A `.bak` in
+ * the repo root is an untracked file nobody asked for, that no `.gitignore`
+ * covers, that a later failure silently overwrites, and that this code has no
+ * way to clean up. The temp directory is reaped by the OS and the warning names
+ * the exact path, which is all a person needs to get their bytes back.
+ *
+ * A unique name per call, so two failures in one session do not overwrite one
+ * another's copy — the second is likelier to be the interesting one.
+ *
+ * Best-effort on the copy: if it cannot be written, the warning still goes out
+ * and still says the contents are gone. Silence is the one outcome this
+ * function exists to prevent.
+ */
+function noteUnparsableLocalPin(path: string, contents: string): void {
+  let backup: string | null = null;
+  try {
+    backup = join(
+      tmpdir(),
+      `hmy-pin-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json.bak`,
+    );
+    writeFileSync(backup, contents);
+  } catch {
+    backup = null;
+  }
+  console.error(
+    `Harmony: ${path} could not be parsed as JSON, so the pin write REPLACED it. ` +
+      (backup
+        ? `The previous contents are in ${backup}.`
+        : "The previous contents could not be backed up and are gone.") +
+      ` If it carried a "commands" block, re-add it.`,
+  );
+}
+
+/**
+ * The indentation this repo formats with (#1115).
+ *
+ * `JSON.stringify(_, null, 2)` was hardcoded, and that is a real failure and
+ * not a nicety: FinPunk's `biome.json` sets `indentStyle: "tab"`, so the file
+ * the Harmony CLI wrote turned `bun run lint` red in every working directory
+ * that had one — a repo's own gate failing on a file the tool wrote for it. The
+ * card's rule is that a file the CLI writes should follow the repo's formatter.
+ *
+ * Read in the order a formatter itself would: `biome.json` (and `biome.jsonc`),
+ * then `.editorconfig`, then the two-space default. `.prettierrc` is
+ * deliberately not read — Prettier does not format `.hmy.json` unless somebody
+ * configures it to, and guessing from a config that does not govern this file
+ * would be worse than the default.
+ *
+ * Best-effort by construction: any read or parse failure falls through to the
+ * next source. A wrong guess costs a formatter diff, which is exactly what the
+ * old hardcoded value cost every tab-indented repo.
+ */
+function localIndent(configPath: string): string | number {
+  const root = dirname(configPath);
+  for (const name of ["biome.json", "biome.jsonc"]) {
+    const parsed = readJsonish(join(root, name));
+    if (!parsed || typeof parsed !== "object") continue;
+    const formatter = (parsed as { formatter?: Record<string, unknown> })
+      .formatter;
+    if (formatter?.indentStyle === "space") {
+      const width = formatter.indentWidth;
+      return typeof width === "number" && width > 0 ? width : 2;
+    }
+    // Biome's OWN default is `tab`, so a config that exists and says nothing
+    // about `indentStyle` — no `formatter` block at all, or a linter-only
+    // file — still formats with tabs. Reading a present biome config as "two
+    // spaces" reproduces the exact AC-5 failure one config shape away: this
+    // repo passes only because it pins `space` explicitly.
+    return "\t";
+  }
+
+  const editorconfig = readTextSafely(join(root, ".editorconfig"));
+  if (editorconfig) {
+    if (/^\s*indent_style\s*=\s*tab\s*$/im.test(editorconfig)) return "\t";
+    const size = editorconfig.match(/^\s*indent_size\s*=\s*(\d+)\s*$/im);
+    if (size) {
+      const width = Number(size[1]);
+      if (width > 0) return width;
+    }
+  }
+
+  return 2;
+}
+
+/** Parse JSON that may carry comments (biome accepts them). `null` on failure. */
+function readJsonish(path: string): unknown {
+  const text = readTextSafely(path);
+  if (text === null) return null;
+  try {
+    // Strip line comments and trailing commas — enough for a config file, and
+    // a parse failure just falls through to the next source.
+    const stripped = text
+      .replace(/^\s*\/\/.*$/gm, "")
+      .replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafely(path: string): string | null {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
 export function hasLocalConfig(cwd?: string): boolean {
   // Same walk as `loadLocalConfig`, or this reports "no local config" for a
   // session an ancestor file actually governs.

package/src/prompt-builder.ts

@@ -249,7 +249,7 @@ const DEFAULT_ROLE_FRAMINGS: Record<LabelCategory, RoleFraming> = {
 // Variant-specific instructions
 const VARIANT_INSTRUCTIONS: Record<PromptVariant, string> = {
   analysis: `ANALYSIS MODE: Analyze this task thoroughly. Identify requirements, constraints, edge cases, and potential challenges. Do NOT implement anything yet - focus on understanding and planning.`,
-  draft: `DRAFT MODE: Create a detailed implementation plan with code structure, key decisions, and approach. Include pseudocode or skeleton code where helpful. This is for review before full implementation.`,
+  draft: `DRAFT MODE: Draft the approach for review before implementing. Cover the key decisions with their reasons, the data model and the API contracts, and success criteria a test can check. A short signature or schema sketch is fine wherever an interpretation gap would otherwise remain; function bodies, control flow and test code are not - an implementer transcribes a plan faithfully, defects included.`,
   execute: `EXECUTE MODE: Implement this task completely. Write production-ready code following best practices. Include necessary tests and documentation.`,
 };
 

package/src/server.ts

@@ -1299,6 +1299,25 @@ export const TOOLS = {
       required: ["cardId", "url"],
     },
   },
+  harmony_remove_external_link: {
+    description:
+      "Remove an external reference URL from a card — the counterpart to harmony_add_external_link. Takes the link id from harmony_get_card_external_links, not the URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: {
+          type: "string",
+          description: "Card UUID",
+        },
+        linkId: {
+          type: "string",
+          description:
+            "External link UUID, as returned by harmony_get_card_external_links",
+        },
+      },
+      required: ["cardId", "linkId"],
+    },
+  },
 
   // Subtask operations
   harmony_create_subtask: {
@@ -2263,7 +2282,7 @@ export const TOOLS = {
 
   harmony_create_plan: {
     description:
-      "Create a new project plan. Use this to upload implementation plans created during planning. Returns a URL where the plan can be viewed and edited in Harmony.",
+      "Create a new project plan. Use this to upload a plan written during planning. Returns a URL where the plan can be viewed and edited in Harmony.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2287,7 +2306,11 @@ export const TOOLS = {
           items: {
             type: "object",
             properties: {
-              content: { type: "string", description: "Task description" },
+              content: {
+                type: "string",
+                description:
+                  'One success criterion, as a statement about the finished product that a test can check ("the mirror matches the migration chain"), never a work package ("write the mirror script"). One criterion may take several cards.',
+              },
               priority: {
                 type: "string",
                 enum: ["high", "medium", "low"],
@@ -2301,7 +2324,8 @@ export const TOOLS = {
             },
             required: ["content"],
           },
-          description: "Optional list of tasks to create with the plan",
+          description:
+            "The plan's success criteria, one entry each - what must be true when the plan is done, not a breakdown of the work to do it.",
         },
       },
       required: ["title"],
@@ -2324,7 +2348,11 @@ export const TOOLS = {
   },
   harmony_update_plan: {
     description:
-      "Update an existing plan. Can update title, content, or status.",
+      "Update an existing plan: its title, content, status, or the timeline dates its bar spans. " +
+      "`startDate`/`endDate` are the plan's OWN schedule, the same pair a person sets by dragging the bar in the timeline view. " +
+      "A plan is pinned on both or on neither: send both to schedule it, or both as null to return it to the span derived from its linked cards. " +
+      "Sending one alone is refused unless the plan is already pinned. " +
+      "They are never adjusted automatically — a card running past `endDate` is drawn as an overrun, and only a person extends the plan.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2339,6 +2367,22 @@ export const TOOLS = {
           enum: ["draft", "active", "archived"],
           description: "New status",
         },
+        // `nullable: true` rather than a union `type`, matching every other
+        // nullable argument in this file. A client that does not accept an
+        // array-valued `type` would otherwise drop the argument entirely — and
+        // reaching agents is the whole point of this half of the card.
+        startDate: {
+          type: "string",
+          nullable: true,
+          description:
+            "Timeline start as YYYY-MM-DD, or null to unpin (send endDate null too).",
+        },
+        endDate: {
+          type: "string",
+          nullable: true,
+          description:
+            "Timeline end as YYYY-MM-DD, or null to unpin (send startDate null too). Must not precede startDate.",
+        },
       },
       required: ["planId"],
     },
@@ -3775,6 +3819,14 @@ export async function handleToolCall(
       return { success: true, ...result };
     }
 
+    case "harmony_remove_external_link": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const linkId = z.string().uuid().parse(args.linkId);
+      // The route already answers `{ success: true }`, so this returns it
+      // as-is rather than re-spreading a second `success` over it.
+      return await client.removeExternalLink(cardId, linkId);
+    }
+
     // Removed — dropped from the advertised TOOLS list; the case remains so an
     // older `hmy-new` install that still calls it gets a legible notice rather
     // than an unknown-tool error.
@@ -5585,6 +5637,8 @@ export async function handleToolCall(
         title?: string;
         content?: string;
         status?: "draft" | "active" | "archived";
+        startDate?: string | null;
+        endDate?: string | null;
       } = {};
 
       if (args.title !== undefined)
@@ -5595,6 +5649,18 @@ export async function handleToolCall(
           .enum(["draft", "active", "archived"])
           .parse(args.status);
       }
+      // The plan's own timeline dates (card #1119). Shape only: whether the
+      // RESULTING pair is legal depends on what the plan already carries, so the
+      // both-or-neither and ordering rules are decided server-side in
+      // `_shared/plan-timeline-dates.ts` — the one place that can see the row.
+      // `null` is meaningful here (it unpins), so it must survive the parse.
+      const planDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: "expected a date as YYYY-MM-DD",
+      });
+      if (args.startDate !== undefined)
+        updates.startDate = planDate.nullable().parse(args.startDate);
+      if (args.endDate !== undefined)
+        updates.endDate = planDate.nullable().parse(args.endDate);
 
       const result = await client.updatePlan(planId, updates);
       return { success: true, plan: result.plan };