omp-conductor 0.15.10 → 0.15.12

package/src/commands/status.ts

@@ -0,0 +1,48 @@
+/**
+ * `status` — layered fleet report: dispatch, ticks, pane, herdr, Telegram target, daemon, caps and active runs.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "../config.ts";
+import { renderStatus } from "../fleet.ts";
+import { STALL_MARKER_FILE } from "../orchestrator-tick.ts";
+
+/**
+ * The orchestrator half, and the one thing `status` has ever known about the
+ * supervising session: the stall marker its heartbeat writes when its own
+ * prompts stop being consumed (see {@link STALL_MARKER_FILE}).
+ *
+ * The marker is written in the *session's* cwd, which this process has no way
+ * to discover — so this reads the state directory, on the reference deploy's
+ * convention that the orchestrator session runs from exactly there. That makes
+ * the reading one-directional: a line printed here is proof of a wedge, and no
+ * line is proof of nothing at all. On a fleet whose session lives elsewhere the
+ * check is simply inert, which is why it never prints a reassuring "healthy".
+ */
+function stallLine(): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(join(stateDir(), STALL_MARKER_FILE), "utf8").trim();
+  } catch {
+    return undefined;
+  }
+  // "<ISO timestamp> <one-line diagnosis>". A file truncated by something else
+  // still gets reported: that the marker exists at all is the news.
+  const cut = raw.indexOf(" ");
+  const since = cut < 0 ? raw : raw.slice(0, cut);
+  const diagnosis = cut < 0 ? "" : ` — ${raw.slice(cut + 1)}`;
+  return `orchestrator   STALLED since ${since === "" ? "an unrecorded time" : since}${diagnosis}`;
+}
+
+export async function statusCommand(ctx: CommandContext): Promise<void> {
+const project = ctx.projectFlag;
+const text = await renderStatus(project);
+const stalled = stallLine();
+process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
+}

package/src/commands/stop.ts

@@ -0,0 +1,51 @@
+/**
+ * `stop` — stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon. Pane stays up unless --pane is passed.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { hold, pinPaneHalt, stopConductorPane } from "../fleet.ts";
+import { stopDaemon } from "../lifecycle.ts";
+
+export async function stopCommand(ctx: CommandContext): Promise<void> {
+const withPane = ctx.argv.includes("--pane");
+const targets = ctx.targetProjects().map((project) => {
+  // `stop` takes the fleet down, so it always disarms — `--keep-ticks` is a
+  // `hold` affordance. Assert the invariant instead of printing a path that
+  // might not exist.
+  const held = hold(project.name, "halt");
+  if (held.disarmed === undefined) throw new Error("stop must disarm ticks");
+  return {
+    project,
+    hold: { ...held, disarmed: held.disarmed },
+    pin: withPane ? pinPaneHalt(project.name).path : undefined,
+  };
+});
+const stop = await stopDaemon();
+const stopLine =
+  stop.kind === "not-running"
+    ? "daemon was not running"
+    : `daemon stopped — pid ${stop.pid}${stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+for (const target of targets) {
+  if (target.pin !== undefined) {
+    const pane = await stopConductorPane(target.project.name);
+    process.stdout.write(
+      `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
+        `${stopLine}\n` +
+        `pane recovery pinned at ${target.pin}\n` +
+        `pane stop: ${pane.stopped} — ${pane.detail}\n` +
+        `  (conductor agent "${pane.agentName}" only — herdr-fleet.service was NOT stopped;\n` +
+        `   resume clears the pin when you want recovery again)\n`,
+    );
+  } else {
+    process.stdout.write(
+      `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
+        `${stopLine}\n` +
+        `pane left running (pass --pane to stop the conductor agent and pin recovery)\n`,
+    );
+  }
+}
+}

package/src/commands/tail.ts

@@ -0,0 +1,109 @@
+/**
+ * `tail` — follow the newest run for an issue the way `tail -f` follows a log, finishing once the run has left the live states.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, LIVE_STATES, openStore } from "../store.ts";
+import { formatTranscriptLine } from "../transcript.ts";
+
+/** How often `tail` re-stats the transcript it is following. */
+const TAIL_POLL_MS = 1_000;
+
+/**
+ * How long the transcript must stay unchanged, after its run has left the live
+ * states, before `tail` calls it over. The state flips from the daemon's thread
+ * while the harness may still be flushing its last message, so exiting on the
+ * state alone truncates the ending an operator ran this command to watch.
+ */
+const TAIL_QUIET_MS = 5_000;
+
+/**
+ * Follow one run's transcript the way `tail -f` follows a log.
+ *
+ * Reads from byte zero rather than from the end: attaching to a worker that is
+ * already ten turns in and then showing nothing until turn eleven is not
+ * watching the run. Polls `stat` instead of taking a file watcher because the
+ * transcript is a plain append-only file that may sit on a filesystem where
+ * change events are a polite fiction, and one stat a second costs nothing.
+ *
+ * SIGINT is deliberately left to its default, which is immediate exit. Nothing
+ * here is buffered, and a handler could only add a poll interval of latency to
+ * every Ctrl-C.
+ */
+async function tailRun(project: string, issue: number): Promise<void> {
+  // Read-only in practice: the store is opened WAL with a busy timeout, so this
+  // never contends with the daemon writing the same rows.
+  const store = openStore(dbPath());
+  try {
+    const run = store.latestRun(project, issue);
+    if (run === undefined) throw new Error(`no run recorded for #${issue}`);
+    const path = run.sessionFile;
+    // Claimed but not yet started, or an attempt whose session never opened one.
+    if (path === undefined) throw new Error(`no transcript yet (state: ${run.state})`);
+
+    const fd = openSync(path, "r");
+    try {
+      let offset = 0;
+      let pending = Buffer.alloc(0);
+      let lastChange = Date.now();
+
+      for (;;) {
+        let size = offset;
+        try {
+          size = statSync(path).size;
+        } catch {
+          // A transcript that vanishes mid-follow is not worth crashing over.
+          // The run's own state, below, is what decides when this command ends.
+        }
+        // Shorter than what we have already read means truncated or replaced;
+        // resuming from the old offset would read the middle of another file.
+        if (size < offset) {
+          offset = 0;
+          pending = Buffer.alloc(0);
+        }
+        if (size > offset) {
+          const chunk = Buffer.allocUnsafe(size - offset);
+          const read = readSync(fd, chunk, 0, chunk.length, offset);
+          offset += read;
+          // Split on newlines as bytes, not as text: a UTF-8 sequence straddling
+          // a read boundary would be mangled by decoding each chunk on its own.
+          pending = Buffer.concat([pending, chunk.subarray(0, read)]);
+          for (;;) {
+            const nl = pending.indexOf(0x0a);
+            if (nl < 0) break;
+            const rendered = formatTranscriptLine(pending.subarray(0, nl).toString("utf8"));
+            pending = pending.subarray(nl + 1);
+            if (rendered !== undefined) process.stdout.write(`${rendered}\n`);
+          }
+          if (read > 0) lastChange = Date.now();
+        }
+
+        // Re-read this exact run every poll — not `latestRun`, which would jump
+        // to a retry started meanwhile and report its state against the wrong
+        // transcript. The daemon writes the row from another process, so looking
+        // is the only way to notice the run finished.
+        const state = store.getRun(run.id)?.state ?? run.state;
+        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= TAIL_QUIET_MS) {
+          process.stdout.write(`run ended: ${state}\n`);
+          return;
+        }
+        await new Promise<void>((resolve) => setTimeout(resolve, TAIL_POLL_MS));
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } finally {
+    store.close();
+  }
+}
+
+export async function tailCommand(ctx: CommandContext): Promise<void> {
+const issue = ctx.issueArg("tail", ctx.argv[1]);
+await tailRun(findProject(loadConfig(), ctx.projectFlag).name, issue);
+}

package/src/commands/unblock.ts

@@ -0,0 +1,39 @@
+/**
+ * `unblock` — clear an issue's blocked and failed labels and restore its queue label so the next tick can claim it again.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig, resolveCaps } from "../config.ts";
+import { dbPath, openStore } from "../store.ts";
+import { makeTracker } from "../tracker/github.ts";
+import { formatUnblock, unblockIssue } from "../unblock.ts";
+
+export async function unblockCommand(ctx: CommandContext): Promise<void> {
+const issue = ctx.issueArg("unblock", ctx.argv[1]);
+const cfg = loadConfig();
+const project = findProject(cfg, ctx.projectFlag);
+const store = openStore(dbPath());
+try {
+  const caps = resolveCaps(project, cfg.defaults);
+  const outcome = await unblockIssue(
+    project,
+    makeTracker(project),
+    store,
+    issue,
+    {
+      force: ctx.argv.includes("--force"),
+      requeue: !ctx.argv.includes("--no-requeue"),
+    },
+    caps,
+  );
+  process.stdout.write(`${formatUnblock(issue, outcome, project, caps)}\n`);
+  // A refusal must not read as success to a script or a board keypress.
+  if (outcome.refused !== undefined) process.exitCode = 3;
+} finally {
+  store.close();
+}
+}

package/src/commands/upgrade-install.ts

@@ -0,0 +1,31 @@
+/**
+ * `upgrade-install` — run the upgrade transaction as the detached fleet
+ * installer (#486): the same engine as `upgrade`, with every surface journaled
+ * and the in-process verification and dispatch restore handed to the first
+ * tick of the post-restart daemon.
+ *
+ * This is the command the transient unit spawned by `conductor_install` runs —
+ * a process in the system manager, outside the pane's process tree and the
+ * daemon's cgroup, so the restarts the transaction performs pass it by. It is
+ * not for typing in a pane: like `upgrade`, it refuses to run inside the
+ * target Herdr session, because a process the restart kills cannot verify
+ * what it installed.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { runDetachedUpgrade } from "../upgrade.ts";
+
+export async function upgradeInstallCommand(ctx: CommandContext): Promise<void> {
+const result = await runDetachedUpgrade({
+  version: ctx.flag("to"),
+  project: ctx.projectFlag,
+});
+process.stdout.write(
+  `install complete — awaiting first-tick verification:\n` +
+    `  Bun-global CLI     omp-conductor@${result.version}\n` +
+    `  omp plugin         omp-conductor@${result.version}\n` +
+    `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
+    `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +
+    `  dispatch           paused — the first tick after the restart verifies and restores it\n`,
+);
+}

package/src/commands/upgrade-rollback.ts

@@ -0,0 +1,32 @@
+/**
+ * `upgrade-rollback` — the detached rollback unit (#486).
+ *
+ * Reads the state-dir upgrade journal, restores every surface the failed
+ * install touched from the durable pre-install snapshot, reloads the services
+ * the install reloaded, and writes the outcome back to the journal plus the
+ * durable outbox. Runs as its own transient unit so the restarts it performs
+ * pass it by — the same trust boundary as the install: the process that rolls
+ * back is not the process that failed.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { rollbackFromJournal } from "../upgrade.ts";
+
+export async function upgradeRollbackCommand(ctx: CommandContext): Promise<void> {
+  // Nothing here varies by project (#514): the rollback restores every
+  // surface the failed install touched, from the host-wide journal. The
+  // flag only ever misled, so refuse it with a reason.
+  if (ctx.projectFlag !== undefined) {
+    process.stderr.write(
+      `omp-conductor: upgrade-rollback does not take a project — it restores the whole host from the upgrade journal\n`,
+    );
+    process.exit(2);
+  }
+  const result = await rollbackFromJournal();
+  process.stdout.write(
+    `rolled back to omp-conductor@${result.restoredVersion} after the failed ` +
+      `upgrade to ${result.failedVersion}\n` +
+      `  surfaces   restored from the pre-install snapshot\n` +
+      `  dispatch   paused — the next tick verifies the old version and resumes\n`,
+  );
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,25 @@
+/**
+ * `upgrade` — update the Bun-global CLI, omp plugin, Herdr recovery plugin and brief as one pinned release.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { upgradeConductor } from "../upgrade.ts";
+
+export async function upgradeCommand(ctx: CommandContext): Promise<void> {
+const result = await upgradeConductor({
+  version: ctx.flag("to"),
+  project: ctx.projectFlag,
+});
+process.stdout.write(
+  `${result.alreadyCurrent ? "already current" : "upgrade complete"}:\n` +
+    `  Bun-global CLI     omp-conductor@${result.version}\n` +
+    `  omp plugin         omp-conductor@${result.version}\n` +
+    `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
+    `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +
+    `  dispatch           ${result.dispatch}${result.alreadyCurrent ? "" : " restored"}\n`,
+);
+}

package/src/commands/verb.ts

@@ -0,0 +1,83 @@
+/**
+ * `verb` — run one `conductor_*` verb as the orchestrator, from the CLI: through the daemon's own checks and ledger rows.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { isPaused, pausedAt } from "../daemon.ts";
+import { readBaseChain } from "../gitops.ts";
+import { dbPath, openStore } from "../store.ts";
+import { makeTracker } from "../tracker/github.ts";
+import { VERB_NAMES } from "../types.ts";
+import { githubVerbActions } from "../verbs/actions.ts";
+import { handleVerbCall, type VerbChannel } from "../verbs/server.ts";
+
+export async function verbCommand(ctx: CommandContext): Promise<void> {
+const name = ctx.argv[1];
+if (name === undefined || !VERB_NAMES.some((n) => n === name)) {
+  process.stderr.write(
+    `omp-conductor: unknown verb "${name ?? ""}". Known verbs: ${VERB_NAMES.join(", ")}\n`,
+  );
+  process.exit(2);
+}
+const cfg = loadConfig();
+const project = findProject(cfg, ctx.projectFlag);
+const args: Record<string, string> = {};
+for (let i = 2; i < ctx.argv.length; i++) {
+  const token = ctx.argv[i];
+  if (token === "--arg") {
+    const pair = ctx.argv[i + 1];
+    if (pair === undefined || !pair.includes("=")) {
+      process.stderr.write(`omp-conductor: verb --arg needs k=v, got "${pair ?? ""}"\n`);
+      process.exit(2);
+    }
+    const eq = pair.indexOf("=");
+    args[pair.slice(0, eq)] = pair.slice(eq + 1);
+    i++;
+  } else if (token === "--project" || token?.startsWith("--project=") === true) {
+    // Consumed by `ctx.projectFlag` above; both spellings skip here.
+    if (token === "--project") i++;
+  } else {
+    process.stderr.write(
+      `omp-conductor: verb: unexpected argument "${token ?? ""}" (pass verb arguments as --arg k=v)\n`,
+    );
+    process.exit(2);
+  }
+}
+const store = openStore(dbPath());
+try {
+  const channel: VerbChannel = {
+    kind: "orchestrator",
+    path: "cli",
+    project: project.name,
+    role: "orchestrator",
+  };
+  const reply = await handleVerbCall(
+    {
+      project: () => findProject(loadConfig(), project.name),
+      store,
+      tracker: makeTracker(project),
+      actions: githubVerbActions(project),
+      fleetStop: () =>
+        isPaused(project.name)
+          ? "claiming is paused for this fleet (omp-conductor hold or stop)"
+          : undefined,
+      pausedAt: () => pausedAt(project.name),
+      log: (m) => process.stderr.write(`${m}\n`),
+      now: () => Date.now(),
+      chain: { readBaseChain },
+    },
+    channel,
+    { verb: name, args },
+  );
+  process.stdout.write(`${reply.text}\n`);
+  // A refusal must not read as success to a script calling this.
+  if (!reply.ok) process.exitCode = 3;
+} finally {
+  store.close();
+}
+}

package/src/commands/version.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The installed package version, read from the package manifest once per run.
+ * The path is one level deeper than cli.ts's original — this module lives in
+ * src/commands/ — but resolves to the same omp/package.json.
+ */
+function packageVersion(): string {
+  const parsed = JSON.parse(
+    readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8"),
+  ) as {
+    version?: unknown;
+  };
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error("installed package.json has no version");
+  }
+  return parsed.version;
+}
+
+/**
+ * `--version`, `-V` and `version`: print the installed package version.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462); only the
+ * case wrapper and the imports changed from the original body.
+ */
+
+export async function versionCommand(): Promise<void> {
+  process.stdout.write(`${packageVersion()}\n`);
+}

package/src/commands/worker.ts

@@ -0,0 +1,100 @@
+/**
+ * `worker` — pause/resume/stop one live worker session through the daemon's run-control HTTP endpoints.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { livingDaemon } from "../lifecycle.ts";
+
+export async function workerCommand(ctx: CommandContext): Promise<void> {
+const sub = ctx.argv[1];
+if (sub !== "pause" && sub !== "resume" && sub !== "stop") {
+  process.stderr.write(
+    "omp-conductor: worker needs pause, resume, or stop, then an issue number\n",
+  );
+  process.exit(2);
+}
+const issue = ctx.issueArg("worker", ctx.argv[2]);
+const rawReason = sub === "stop" ? ctx.flag("reason") : undefined;
+const reason = rawReason?.trim().replace(/\s+/g, " ");
+if (sub === "stop" && (reason === undefined || reason === "" || reason.length > 500)) {
+  process.stderr.write(
+    "omp-conductor: worker stop needs --reason with 1-500 characters\n",
+  );
+  process.exit(2);
+}
+const project = findProject(loadConfig(), ctx.projectFlag);
+const daemon = livingDaemon();
+if (daemon === undefined) throw new Error("daemon is not running");
+if (daemon.project !== undefined && daemon.project !== project.name) {
+  throw new Error(
+    `daemon serves project "${daemon.project}", not requested project "${project.name}"`,
+  );
+}
+const response = await fetch(
+  `http://127.0.0.1:${daemon.port}/runs/${issue}/${sub}`,
+  {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      project: project.name,
+      ...(reason === undefined ? {} : { reason }),
+    }),
+  },
+);
+const payload = (await response.json()) as {
+  error?: unknown;
+  runId?: unknown;
+  phase?: unknown;
+  outcome?: unknown;
+  state?: unknown;
+  reason?: unknown;
+  salvageSha?: unknown;
+  salvageError?: unknown;
+  worktree?: unknown;
+};
+if (!response.ok) {
+  throw new Error(
+    typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
+  );
+}
+if (sub === "stop") {
+  if (
+    typeof payload.runId !== "string" ||
+    typeof payload.state !== "string" ||
+    (payload.outcome !== "stopped" && payload.outcome !== "already-terminal")
+  ) {
+    throw new Error("daemon returned an invalid worker-stop response");
+  }
+  if (payload.outcome === "already-terminal") {
+    process.stdout.write(
+      `#${issue} worker already terminal: ${payload.state} (run ${payload.runId})\n`,
+    );
+    return;
+  }
+  if (typeof payload.reason !== "string") {
+    throw new Error("daemon returned an invalid worker-stop response");
+  }
+  process.stdout.write(
+    `#${issue} worker stopped (run ${payload.runId}): ${payload.reason}\n`,
+  );
+  if (typeof payload.salvageSha === "string") {
+    process.stdout.write(`work preserved: ${payload.salvageSha}\n`);
+  }
+  if (typeof payload.salvageError === "string") {
+    process.stdout.write(
+      `WIP SALVAGE FAILED: ${payload.salvageError}\n` +
+      `worktree kept: ${typeof payload.worktree === "string" ? payload.worktree : "(path unavailable)"}\n`,
+    );
+  }
+  return;
+}
+if (typeof payload.runId !== "string" || typeof payload.phase !== "string") {
+  throw new Error("daemon returned an invalid worker-control response");
+}
+process.stdout.write(`#${issue} worker ${payload.phase} (run ${payload.runId})\n`);
+}

package/src/config-schema.ts

@@ -226,6 +226,7 @@ const authoritySchema = z
   .object({
     merge: authorityHolderEnum.default(DEFAULT_AUTHORITY.merge),
     release: authorityHolderEnum.default(DEFAULT_AUTHORITY.release),
+    promotion: authorityHolderEnum.default(DEFAULT_AUTHORITY.promotion),
   })
   .strict();
 
@@ -315,12 +316,21 @@ const projectSchema = z
     routing: routingSchema.optional(),
     caps: capsSchema.optional(),
     workerModel: z.unknown().optional(),
+    // The loader normalises both of these (trimmed entries / positive integer),
+    // so the schema admits any shape and lets the normaliser decide what is
+    // usable, exactly like `workerModel`.
+    modelFallbacks: z.unknown().optional(),
+    modelFallbackThreshold: z.unknown().optional(),
     escalation: escalationSchema.optional(),
     authority: authoritySchema.optional(),
     releasePolicy: releasePolicySchema.optional(),
     policy: projectPolicySchema.optional(),
     recoveryMerges: recoveryMergesSchema.optional(),
     reporting: reportingSchema.optional(),
+    // Hand-edited safety markers (commit SHAs or refs) a preserved continuation
+    // branch must contain before it may be reattached; the loader normalises
+    // them like `modelFallbacks`.
+    criticalBase: z.unknown().optional(),
     // Roots silently fall back to the default when unusable, so the schema
     // admits any shape and the normaliser picks the usable path.
     workspaceRoot: z.unknown().optional(),
@@ -352,7 +362,43 @@ export const ConfigSchema = configSchema;
  * validate a hand-written config against the same vocabulary the loader enforces.
  */
 export function configJsonSchema(): object {
-  return z.toJSONSchema(ConfigSchema) as object;
+  return unrequireDefaultedKeys(z.toJSONSchema(ConfigSchema) as object);
+}
+
+/** True for a JSON object value (null and arrays excluded). */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * zod's JSON-Schema renderer lists a field carrying `.default(...)` as
+ * `required` anyway — its required computation keys off optionality, while
+ * the only trace a default leaves in the output is the `default` annotation.
+ * The loader accepts a config that omits any defaulted key, so a schema that
+ * demands one rejects a file the daemon reads cleanly (the pre-#469
+ * back-compat promise). Walk the rendered schema and drop every `required`
+ * key whose property schema declares a `default`; a key with no default is
+ * untouched. Works in place on the tree `z.toJSONSchema` just built.
+ */
+function unrequireDefaultedKeys(schema: object): object {
+  if (Array.isArray(schema)) {
+    for (const item of schema) if (isObject(item)) unrequireDefaultedKeys(item);
+    return schema;
+  }
+  const node = schema as Record<string, unknown>;
+  const properties = node.properties;
+  if (isObject(properties) && Array.isArray(node.required)) {
+    const kept = (node.required as unknown[]).filter((key) => {
+      const property = properties[String(key)];
+      return !isObject(property) || !("default" in property);
+    });
+    if (kept.length === 0) delete node.required;
+    else node.required = kept;
+  }
+  for (const value of Object.values(node)) {
+    if (isObject(value)) unrequireDefaultedKeys(value);
+  }
+  return schema;
 }
 
 // Re-exports the renderer consumes without duplicating the lists.