@gmickel/gno 1.37.1 → 1.39.0

package/src/cli/program.ts

@@ -21,6 +21,14 @@ import {
 import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import { resolveDepthPolicy } from "../core/depth-policy";
 import { parseAndValidateTagFilter } from "../core/tags";
+import {
+  formatWriteLeaseBusyJson,
+  formatWriteLeaseBusyMessage,
+  isWriteLeaseBusyResult,
+  parseLockWaitMs,
+  withCliWriteLease,
+  type WriteLeaseBusyFailure,
+} from "../core/write-lease";
 import { setColorsEnabled } from "./colors";
 import {
   applyGlobalOptions,
@@ -221,6 +229,49 @@ function parseCsvValues(raw: unknown): string[] | undefined {
   return values.length > 0 ? values : undefined;
 }
 
+function addWriteLeaseFlags(command: Command): Command {
+  return command
+    .option(
+      "--lock-wait <duration>",
+      "how long to wait for the index write lease (default: 120s)",
+      "120s"
+    )
+    .option("--no-wait", "fail immediately if the index write lease is held");
+}
+
+function parseWriteLeaseFlags(cmdOpts: Record<string, unknown>): {
+  lockWaitMs: number;
+  noWait: boolean;
+} {
+  const parsed = parseLockWaitMs(cmdOpts.lockWait);
+  if (parsed === null) {
+    throw new CliError(
+      "VALIDATION",
+      `Invalid --lock-wait duration: ${String(cmdOpts.lockWait)}. Use seconds ("120"), "120s", or "2m".`
+    );
+  }
+  return {
+    lockWaitMs: parsed,
+    noWait: cmdOpts.wait === false,
+  };
+}
+
+function throwIfWriteLeaseBusy<
+  T extends { success: boolean; error?: string; contention?: unknown },
+>(result: T | WriteLeaseBusyFailure, json: boolean): asserts result is T {
+  if (!isWriteLeaseBusyResult(result)) {
+    return;
+  }
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(formatWriteLeaseBusyJson(result.contention))}\n`
+    );
+  } else {
+    process.stderr.write(`${formatWriteLeaseBusyMessage(result.contention)}\n`);
+  }
+  throw new CliError("BUSY", result.error, { silent: true });
+}
+
 function parseContextInteger(
   name: string,
   value: unknown,
@@ -313,6 +364,7 @@ export function createProgram(): Command {
   wireKnowledgeDeltaCommands(program);
   wireMcpCommand(program);
   wireSkillCommands(program);
+  wireAgentsCommands(program);
   wireDaemonCommand(program);
   wireServeCommand(program);
   wireCompletionCommand(program);
@@ -1505,39 +1557,51 @@ function wireOnboardingCommands(program: Command): void {
     });
 
   // index - Index collections
-  program
-    .command("index [collection]")
-    .description("Index files from collections")
-    .option("--no-embed", "skip embedding after sync")
-    .option("--git-pull", "run git pull in git repositories")
-    .option("--models-pull", "download models if missing")
-    .option("--json", "JSON output")
-    .action(
-      async (
-        collection: string | undefined,
-        cmdOpts: Record<string, unknown>
-      ) => {
-        const globals = getGlobals();
-        const { index, formatIndex } = await import("./commands/index-cmd");
-        const opts = {
-          configPath: globals.config,
-          indexName: globals.index,
-          collection,
-          noEmbed: cmdOpts.embed === false,
-          gitPull: Boolean(cmdOpts.gitPull),
-          modelsPull: Boolean(cmdOpts.modelsPull),
-          yes: globals.yes,
-          verbose: globals.verbose,
-          json: getFormat(cmdOpts) === "json",
-        };
-        const result = await index(opts);
+  addWriteLeaseFlags(
+    program
+      .command("index [collection]")
+      .description("Index files from collections")
+      .option("--no-embed", "skip embedding after sync")
+      .option("--git-pull", "run git pull in git repositories")
+      .option("--models-pull", "download models if missing")
+      .option("--json", "JSON output")
+  ).action(
+    async (
+      collection: string | undefined,
+      cmdOpts: Record<string, unknown>
+    ) => {
+      const globals = getGlobals();
+      const { index, formatIndex } = await import("./commands/index-cmd");
+      const lease = parseWriteLeaseFlags(cmdOpts);
+      const opts = {
+        configPath: globals.config,
+        indexName: globals.index,
+        collection,
+        noEmbed: cmdOpts.embed === false,
+        gitPull: Boolean(cmdOpts.gitPull),
+        modelsPull: Boolean(cmdOpts.modelsPull),
+        yes: globals.yes,
+        verbose: globals.verbose,
+        json: getFormat(cmdOpts) === "json",
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      };
+      const result = await index(opts);
 
-        if (!result.success) {
-          throw new CliError("RUNTIME", result.error ?? "Index failed");
-        }
-        process.stdout.write(`${formatIndex(result, opts)}\n`);
+      if (!result.success) {
+        throwIfWriteLeaseBusy(result, opts.json);
+        throw new CliError("RUNTIME", result.error ?? "Index failed");
       }
-    );
+      process.stdout.write(`${formatIndex(result, opts)}\n`);
+      if ((result.embedResult?.contentionErrors ?? 0) > 0) {
+        throw new CliError(
+          "BUSY",
+          "Some chunks were deferred by index contention",
+          { silent: true }
+        );
+      }
+    }
+  );
 
   // audit - Read-only workspace integrity report
   program
@@ -2225,19 +2289,33 @@ function wireManagementCommands(program: Command): void {
       });
     });
 
-  collectionCmd
-    .command("clear-embeddings <name>")
-    .description("Clear stale or all embeddings for a collection")
-    .option("--all", "remove all embeddings for the collection")
-    .option("--json", "JSON output")
-    .action(async (name: string, cmdOpts: Record<string, unknown>) => {
-      const { collectionClearEmbeddings } =
-        await import("./commands/collection");
-      await collectionClearEmbeddings(name, {
-        all: Boolean(cmdOpts.all),
-        json: Boolean(cmdOpts.json),
-      });
-    });
+  addWriteLeaseFlags(
+    collectionCmd
+      .command("clear-embeddings <name>")
+      .description("Clear stale or all embeddings for a collection")
+      .option("--all", "remove all embeddings for the collection")
+      .option("--json", "JSON output")
+  ).action(async (name: string, cmdOpts: Record<string, unknown>) => {
+    const { collectionClearEmbeddings } = await import("./commands/collection");
+    const json = Boolean(cmdOpts.json);
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: getGlobals().index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      async () => {
+        await collectionClearEmbeddings(name, {
+          all: Boolean(cmdOpts.all),
+          indexName: getGlobals().index,
+          json,
+        });
+        return { success: true as const };
+      }
+    );
+    throwIfWriteLeaseBusy(result, json);
+  });
 
   const collectionPolicyCmd = collectionCmd
     .command("policy")
@@ -2771,85 +2849,110 @@ function wireManagementCommands(program: Command): void {
     });
 
   // update - Sync files from disk
-  program
-    .command("update")
-    .description("Sync files from disk into the index")
-    .option("--git-pull", "run git pull in git repositories")
-    .option("--json", "JSON output")
-    .action(async (cmdOpts: Record<string, unknown>) => {
+  addWriteLeaseFlags(
+    program
+      .command("update")
+      .description("Sync files from disk into the index")
+      .option("--git-pull", "run git pull in git repositories")
+      .option("--json", "JSON output")
+  ).action(async (cmdOpts: Record<string, unknown>) => {
+    const globals = getGlobals();
+    const { update, formatUpdate } = await import("./commands/update");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const opts = {
+      configPath: globals.config,
+      indexName: globals.index,
+      gitPull: Boolean(cmdOpts.gitPull),
+      verbose: globals.verbose,
+      json: getFormat(cmdOpts) === "json",
+      lockWaitMs: lease.lockWaitMs,
+      noWait: lease.noWait,
+    };
+    const result = await update(opts);
+
+    if (!result.success) {
+      throwIfWriteLeaseBusy(result, opts.json);
+      throw new CliError("RUNTIME", result.error ?? "Update failed");
+    }
+    process.stdout.write(`${formatUpdate(result, opts)}\n`);
+  });
+
+  // embed - Generate embeddings
+  addWriteLeaseFlags(
+    program
+      .command("embed [collection]")
+      .description("Generate embeddings for indexed documents")
+      .option("--collection <name>", "restrict to one collection")
+      .option("--model <uri>", "embedding model URI")
+      .option("--batch-size <num>", "batch size", "32")
+      .option("--force", "regenerate all embeddings")
+      .option("--dry-run", "show what would be done")
+      .option("--json", "JSON output")
+  ).action(
+    async (
+      collectionArg: string | undefined,
+      cmdOpts: Record<string, unknown>
+    ) => {
       const globals = getGlobals();
-      const { update, formatUpdate } = await import("./commands/update");
+      const format = getFormat(cmdOpts);
+
+      const { embed, formatEmbed } = await import("./commands/embed");
+      const collection =
+        collectionArg ?? (cmdOpts.collection as string | undefined);
+      const lease = parseWriteLeaseFlags(cmdOpts);
       const opts = {
         configPath: globals.config,
         indexName: globals.index,
-        gitPull: Boolean(cmdOpts.gitPull),
+        collection,
+        model: cmdOpts.model as string | undefined,
+        batchSize: parsePositiveInt("batch-size", cmdOpts.batchSize),
+        force: Boolean(cmdOpts.force),
+        dryRun: Boolean(cmdOpts.dryRun),
+        yes: globals.yes,
+        json: format === "json",
         verbose: globals.verbose,
-        json: getFormat(cmdOpts) === "json",
+        offline: globals.offline,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
       };
-      const result = await update(opts);
+      const result = await embed(opts);
 
       if (!result.success) {
-        throw new CliError("RUNTIME", result.error ?? "Update failed");
+        throwIfWriteLeaseBusy(result, opts.json);
+        throw new CliError("RUNTIME", result.error ?? "Embed failed");
       }
-      process.stdout.write(`${formatUpdate(result, opts)}\n`);
-    });
-
-  // embed - Generate embeddings
-  program
-    .command("embed [collection]")
-    .description("Generate embeddings for indexed documents")
-    .option("--collection <name>", "restrict to one collection")
-    .option("--model <uri>", "embedding model URI")
-    .option("--batch-size <num>", "batch size", "32")
-    .option("--force", "regenerate all embeddings")
-    .option("--dry-run", "show what would be done")
-    .option("--json", "JSON output")
-    .action(
-      async (
-        collectionArg: string | undefined,
-        cmdOpts: Record<string, unknown>
-      ) => {
-        const globals = getGlobals();
-        const format = getFormat(cmdOpts);
-
-        const { embed, formatEmbed } = await import("./commands/embed");
-        const collection =
-          collectionArg ?? (cmdOpts.collection as string | undefined);
-        const opts = {
-          configPath: globals.config,
-          indexName: globals.index,
-          collection,
-          model: cmdOpts.model as string | undefined,
-          batchSize: parsePositiveInt("batch-size", cmdOpts.batchSize),
-          force: Boolean(cmdOpts.force),
-          dryRun: Boolean(cmdOpts.dryRun),
-          yes: globals.yes,
-          json: format === "json",
-          verbose: globals.verbose,
-          offline: globals.offline,
-        };
-        const result = await embed(opts);
-
-        if (!result.success) {
-          throw new CliError("RUNTIME", result.error ?? "Embed failed");
-        }
-        process.stdout.write(`${formatEmbed(result, opts)}\n`);
+      process.stdout.write(`${formatEmbed(result, opts)}\n`);
+      if (result.contentionErrors > 0) {
+        throw new CliError(
+          "BUSY",
+          "Some chunks were deferred by index contention",
+          { silent: true }
+        );
       }
-    );
+    }
+  );
 
   // cleanup - Clean stale data
-  program
-    .command("cleanup")
-    .description("Clean orphaned data from index")
-    .action(async () => {
-      const { cleanup, formatCleanup } = await import("./commands/cleanup");
-      const result = await cleanup();
+  addWriteLeaseFlags(
+    program.command("cleanup").description("Clean orphaned data from index")
+  ).action(async (cmdOpts: Record<string, unknown>) => {
+    const { cleanup, formatCleanup } = await import("./commands/cleanup");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: getGlobals().index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      () => cleanup({ indexName: getGlobals().index })
+    );
+    throwIfWriteLeaseBusy(result, false);
 
-      if (!result.success) {
-        throw new CliError("RUNTIME", result.error ?? "Cleanup failed");
-      }
-      process.stdout.write(`${formatCleanup(result)}\n`);
-    });
+    if (!result.success) {
+      throw new CliError("RUNTIME", result.error ?? "Cleanup failed");
+    }
+    process.stdout.write(`${formatCleanup(result)}\n`);
+  });
 
   // reset - Reset GNO to fresh state
   program
@@ -2879,52 +2982,76 @@ function wireVecCommands(program: Command): void {
   const vecCmd = program.command("vec").description("Vector index maintenance");
 
   // vec sync
-  vecCmd
-    .command("sync")
-    .description("Sync vec0 index with content_vectors")
-    .option("--json", "JSON output")
-    .action(async (cmdOpts: Record<string, unknown>) => {
-      const format = getFormat(cmdOpts);
-      const globals = getGlobals();
+  addWriteLeaseFlags(
+    vecCmd
+      .command("sync")
+      .description("Sync vec0 index with content_vectors")
+      .option("--json", "JSON output")
+  ).action(async (cmdOpts: Record<string, unknown>) => {
+    const format = getFormat(cmdOpts);
+    const globals = getGlobals();
 
-      const { vecSync, formatVecSync } = await import("./commands/vec");
-      const result = await vecSync({
-        configPath: globals.config,
-        json: format === "json",
-      });
+    const { vecSync, formatVecSync } = await import("./commands/vec");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: globals.index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      () =>
+        vecSync({
+          configPath: globals.config,
+          indexName: globals.index,
+          json: format === "json",
+        })
+    );
+    throwIfWriteLeaseBusy(result, format === "json");
 
-      if (!result.success) {
-        throw new CliError("RUNTIME", result.error);
-      }
+    if (!result.success) {
+      throw new CliError("RUNTIME", result.error);
+    }
 
-      process.stdout.write(
-        `${formatVecSync(result, { json: format === "json" })}\n`
-      );
-    });
+    process.stdout.write(
+      `${formatVecSync(result, { json: format === "json" })}\n`
+    );
+  });
 
   // vec rebuild
-  vecCmd
-    .command("rebuild")
-    .description("Rebuild vec0 index from content_vectors")
-    .option("--json", "JSON output")
-    .action(async (cmdOpts: Record<string, unknown>) => {
-      const format = getFormat(cmdOpts);
-      const globals = getGlobals();
+  addWriteLeaseFlags(
+    vecCmd
+      .command("rebuild")
+      .description("Rebuild vec0 index from content_vectors")
+      .option("--json", "JSON output")
+  ).action(async (cmdOpts: Record<string, unknown>) => {
+    const format = getFormat(cmdOpts);
+    const globals = getGlobals();
 
-      const { vecRebuild, formatVecRebuild } = await import("./commands/vec");
-      const result = await vecRebuild({
-        configPath: globals.config,
-        json: format === "json",
-      });
+    const { vecRebuild, formatVecRebuild } = await import("./commands/vec");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: globals.index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      () =>
+        vecRebuild({
+          configPath: globals.config,
+          indexName: globals.index,
+          json: format === "json",
+        })
+    );
+    throwIfWriteLeaseBusy(result, format === "json");
 
-      if (!result.success) {
-        throw new CliError("RUNTIME", result.error);
-      }
+    if (!result.success) {
+      throw new CliError("RUNTIME", result.error);
+    }
 
-      process.stdout.write(
-        `${formatVecRebuild(result, { json: format === "json" })}\n`
-      );
-    });
+    process.stdout.write(
+      `${formatVecRebuild(result, { json: format === "json" })}\n`
+    );
+  });
 }
 
 function wirePublishCommand(program: Command): void {
@@ -3194,6 +3321,109 @@ function wireSkillCommands(program: Command): void {
     });
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Agents Commands (install, update, verify, uninstall)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function wireAgentsCommands(program: Command): void {
+  const agentsCmd = program
+    .command("agents")
+    .description(
+      "Manage the GNO protocol block in global harness instruction files"
+    );
+
+  const targetDescription =
+    "target harness (claude, codex, cursor, opencode, grok, hermes, openclaw, all)";
+
+  const collectExtraDir = (value: string, previous: string[]): string[] => [
+    ...previous,
+    value,
+  ];
+
+  const parseCommonOpts = async (cmdOpts: Record<string, unknown>) => {
+    const { parseTargetOption } = await import("./commands/agents/commands.js");
+    return {
+      target: parseTargetOption((cmdOpts.target as string) ?? "all"),
+      extraDirs: (cmdOpts.extraDir as string[] | undefined) ?? [],
+      dryRun: Boolean(cmdOpts.dryRun),
+      // The root program also defines a global --json and may consume the
+      // flag; leave undefined here so the runner falls back to globals.
+      json: cmdOpts.json ? true : undefined,
+    };
+  };
+
+  agentsCmd
+    .command("install")
+    .description(
+      "Install the GNO protocol block into detected harnesses' global instruction files"
+    )
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { installAgents } = await import("./commands/agents/commands.js");
+      await installAgents(await parseCommonOpts(cmdOpts), "install");
+    });
+
+  agentsCmd
+    .command("update")
+    .description("Refresh an installed GNO protocol block in place")
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { installAgents } = await import("./commands/agents/commands.js");
+      await installAgents(await parseCommonOpts(cmdOpts), "update");
+    });
+
+  agentsCmd
+    .command("verify")
+    .description(
+      "Verify installed GNO protocol blocks (one block, version + hash)"
+    )
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { verifyAgents } = await import("./commands/agents/commands.js");
+      await verifyAgents(await parseCommonOpts(cmdOpts));
+    });
+
+  agentsCmd
+    .command("uninstall")
+    .description("Remove the GNO protocol block and markers from harness files")
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { uninstallAgents } = await import("./commands/agents/commands.js");
+      await uninstallAgents(await parseCommonOpts(cmdOpts));
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tags Commands (list, add, rm)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -3217,6 +3447,7 @@ function wireTagsCommands(program: Command): void {
       const { tagsList, formatTagsList } = await import("./commands/tags");
       const result = await tagsList({
         configPath: globals.config,
+        indexName: globals.index,
         collection: cmdOpts.collection as string | undefined,
         prefix: cmdOpts.prefix as string | undefined,
         json: format === "json",
@@ -3238,62 +3469,86 @@ function wireTagsCommands(program: Command): void {
     });
 
   // tags add <doc> <tag>
-  tagsCmd
-    .command("add <doc> <tag>")
-    .description("Add a tag to a document")
-    .option("--json", "JSON output")
-    .action(
-      async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
-        const format = getFormat(cmdOpts);
-        const globals = getGlobals();
-
-        const { tagsAdd, formatTagsAdd } = await import("./commands/tags");
-        const result = await tagsAdd(doc, tag, {
-          configPath: globals.config,
-          json: format === "json",
-        });
+  addWriteLeaseFlags(
+    tagsCmd
+      .command("add <doc> <tag>")
+      .description("Add a tag to a document")
+      .option("--json", "JSON output")
+  ).action(
+    async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      const globals = getGlobals();
 
-        if (!result.success) {
-          throw new CliError(
-            result.isValidation ? "VALIDATION" : "RUNTIME",
-            result.error
-          );
-        }
+      const { tagsAdd, formatTagsAdd } = await import("./commands/tags");
+      const lease = parseWriteLeaseFlags(cmdOpts);
+      const result = await withCliWriteLease(
+        {
+          indexName: globals.index,
+          lockWaitMs: lease.lockWaitMs,
+          noWait: lease.noWait,
+        },
+        () =>
+          tagsAdd(doc, tag, {
+            configPath: globals.config,
+            indexName: globals.index,
+            json: format === "json",
+          })
+      );
+      throwIfWriteLeaseBusy(result, format === "json");
 
-        process.stdout.write(
-          `${formatTagsAdd(result, { json: format === "json" })}\n`
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
         );
       }
-    );
 
-  // tags rm <doc> <tag>
-  tagsCmd
-    .command("rm <doc> <tag>")
-    .description("Remove a tag from a document")
-    .option("--json", "JSON output")
-    .action(
-      async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
-        const format = getFormat(cmdOpts);
-        const globals = getGlobals();
+      process.stdout.write(
+        `${formatTagsAdd(result, { json: format === "json" })}\n`
+      );
+    }
+  );
 
-        const { tagsRm, formatTagsRm } = await import("./commands/tags");
-        const result = await tagsRm(doc, tag, {
-          configPath: globals.config,
-          json: format === "json",
-        });
+  // tags rm <doc> <tag>
+  addWriteLeaseFlags(
+    tagsCmd
+      .command("rm <doc> <tag>")
+      .description("Remove a tag from a document")
+      .option("--json", "JSON output")
+  ).action(
+    async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      const globals = getGlobals();
 
-        if (!result.success) {
-          throw new CliError(
-            result.isValidation ? "VALIDATION" : "RUNTIME",
-            result.error
-          );
-        }
+      const { tagsRm, formatTagsRm } = await import("./commands/tags");
+      const lease = parseWriteLeaseFlags(cmdOpts);
+      const result = await withCliWriteLease(
+        {
+          indexName: globals.index,
+          lockWaitMs: lease.lockWaitMs,
+          noWait: lease.noWait,
+        },
+        () =>
+          tagsRm(doc, tag, {
+            configPath: globals.config,
+            indexName: globals.index,
+            json: format === "json",
+          })
+      );
+      throwIfWriteLeaseBusy(result, format === "json");
 
-        process.stdout.write(
-          `${formatTagsRm(result, { json: format === "json" })}\n`
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
         );
       }
-    );
+
+      process.stdout.write(
+        `${formatTagsRm(result, { json: format === "json" })}\n`
+      );
+    }
+  );
 }
 
 // ─────────────────────────────────────────────────────────────────────────────