@warmhub/cli 0.48.0 → 0.49.0

package/dist/wh.js

@@ -19527,7 +19527,7 @@ function findSystemComponent(componentId) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.47.0",
+  version: "0.48.0",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -19626,12 +19626,16 @@ var package_default = {
 
 // ../../packages/sdk-ts/src/operation-normalize.ts
 function toBackendStreamOperation(operation) {
+  if (operation.expectedVersion !== undefined && operation.operation !== "revise") {
+    throw new Error("expectedVersion is only valid on revise operations — set operation: 'revise'");
+  }
   if (operation.operation === "retract") {
     return {
       operation: "retract",
       name: operation.name,
       ...operation.kind ? { kind: operation.kind } : {},
-      ...operation.reason ? { reason: operation.reason } : {}
+      ...operation.reason ? { reason: operation.reason } : {},
+      ...operation.leaseId ? { leaseId: operation.leaseId } : {}
     };
   }
   if (operation.operation === "revise") {
@@ -19654,14 +19658,18 @@ function toBackendStreamOperation(operation) {
         operation: "revise",
         kind: "assertion",
         name,
-        data: operation.data
+        data: operation.data,
+        ...operation.expectedVersion !== undefined ? { expectedVersion: operation.expectedVersion } : {},
+        ...operation.leaseId ? { leaseId: operation.leaseId } : {}
       };
     }
     return {
       operation: "revise",
       kind: kind2,
       name,
-      data: operation.data
+      data: operation.data,
+      ...operation.expectedVersion !== undefined ? { expectedVersion: operation.expectedVersion } : {},
+      ...operation.leaseId ? { leaseId: operation.leaseId } : {}
     };
   }
   const kind = operation.kind ?? inferKind(operation.name, operation);
@@ -20155,7 +20163,8 @@ class WarmHubError extends Error {
   hint;
   retryAfter;
   backendCode;
-  constructor(code, message, status, hint, retryAfter, backendCode) {
+  details;
+  constructor(code, message, status, hint, retryAfter, backendCode, details) {
     super(message);
     this.name = "WarmHubError";
     this.code = code;
@@ -20163,6 +20172,7 @@ class WarmHubError extends Error {
     this.hint = hint;
     this.retryAfter = retryAfter;
     this.backendCode = backendCode;
+    this.details = details;
   }
   get kind() {
     return this.code;
@@ -20187,12 +20197,12 @@ function toWarmHubError(error) {
     const data = error.data;
     const wireCode = data?.warmhub?.code;
     const message = data?.warmhub?.message ?? sanitizeErrorMessage(error.message);
-    return new WarmHubError(wireCode ?? "BACKEND", message, data?.warmhub?.status, data?.warmhub?.hint, data?.warmhub?.retryAfter, wireCode);
+    return new WarmHubError(wireCode ?? "BACKEND", message, data?.warmhub?.status, data?.warmhub?.hint, data?.warmhub?.retryAfter, wireCode, data?.warmhub?.details);
   }
   if (error instanceof Error) {
     const warmhubLike = error;
     if (error.name === "WarmHubError" && typeof warmhubLike.code === "string") {
-      return new WarmHubError(warmhubLike.code, sanitizeErrorMessage(error.message), typeof warmhubLike.status === "number" ? warmhubLike.status : undefined, typeof warmhubLike.hint === "string" ? warmhubLike.hint : undefined, typeof warmhubLike.retryAfter === "number" ? warmhubLike.retryAfter : undefined, typeof warmhubLike.backendCode === "string" ? warmhubLike.backendCode : undefined);
+      return new WarmHubError(warmhubLike.code, sanitizeErrorMessage(error.message), typeof warmhubLike.status === "number" ? warmhubLike.status : undefined, typeof warmhubLike.hint === "string" ? warmhubLike.hint : undefined, typeof warmhubLike.retryAfter === "number" ? warmhubLike.retryAfter : undefined, typeof warmhubLike.backendCode === "string" ? warmhubLike.backendCode : undefined, warmhubLike.details);
     }
     if (error.name === "AbortError") {
       return new WarmHubError("CANCELLED", error.message);
@@ -21320,6 +21330,30 @@ class WarmHubClient {
         throw toWarmHubError(error);
       }
     },
+    getWithLease: async (orgName, repoName, wref, opts) => {
+      try {
+        return await this.trpc.thing.getWithLease.mutate({
+          orgName,
+          repoName,
+          wref,
+          ttlMs: opts?.ttlMs
+        });
+      } catch (error) {
+        throw toWarmHubError(error);
+      }
+    },
+    releaseLease: async (orgName, repoName, wref, leaseId) => {
+      try {
+        await this.trpc.thing.releaseLease.mutate({
+          orgName,
+          repoName,
+          wref,
+          leaseId
+        });
+      } catch (error) {
+        throw toWarmHubError(error);
+      }
+    },
     graph: async (orgName, repoName, wref, opts) => {
       try {
         return await this.trpc.thing.graph.query({
@@ -22057,6 +22091,10 @@ function classifyConflict(message, code) {
       return "archived";
     case "REPO_PENDING_DELETE":
       return "pending-delete";
+    case "LEASE_UNAVAILABLE":
+      return "lease-held";
+    default:
+      break;
   }
   const lower = message.toLowerCase();
   if (lower.includes("already exists") || lower.includes("already a member")) {
@@ -22086,6 +22124,8 @@ function conflictHint(message, code) {
       return "Other things reference this. Retract those assertions first, or use a tombstone.";
     case "pending-delete":
       return "Repo is being deleted. Wait for the delete to finish or cancel it before retrying.";
+    case "lease-held":
+      return "This thing is leased by another holder. Back off until the lease expires (see leaseExpiresAt / retryAfter), then retry.";
     case "other":
       return "Resolve the conflicting existing state and try again.";
   }
@@ -22109,7 +22149,8 @@ var CONFLICT_SHAPED_CODES = new Set([
   "ARCHIVED",
   "HAS_INBOUND_REFS",
   "REPO_PENDING_DELETE",
-  "ALREADY_RETRACTED"
+  "ALREADY_RETRACTED",
+  "LEASE_UNAVAILABLE"
 ]);
 function fromWh(exit, kind, err, hint = err.hint) {
   return new CliError(exit, kind, err.message, err, hint, undefined, err.backendCode);
@@ -22269,6 +22310,11 @@ function generateSuggestions(code, message, context, backendCode) {
           action: "Wait for the repo delete to finish or cancel it before retrying"
         });
         break;
+      case "lease-held":
+        suggestions.push({
+          action: "Another holder leased this thing. Back off until the lease expires (leaseExpiresAt / retryAfter), then retry"
+        });
+        break;
       case "other":
         suggestions.push({
           action: "Resolve the conflicting existing state and retry"
@@ -22480,6 +22526,21 @@ function safeParseJson(input, label, options) {
     throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid JSON for ${label}: ${input.length > 80 ? `${input.slice(0, 77)}...` : input}`, undefined, hint);
   }
 }
+function parsePositiveIntFlag(value, label, example) {
+  if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+    usageError(`${label} must be a positive integer`, example);
+  }
+  return value;
+}
+function requireLeaseIdFlag(raw, example = `wh thing revise Player/alice --data '{"score":2}' --lease-id <id>`) {
+  if (raw === undefined)
+    return;
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    usageError("--lease-id must be a non-empty lease token from `wh thing lease`", example);
+  }
+  return trimmed;
+}
 function parseArgs(argv) {
   const positionals = [];
   const flags = {};
@@ -23859,6 +23920,17 @@ function parseOrgRepo(ref, config) {
   }
   throw new CliError(3 /* Config */, "CONFIG", "No repo specified. Use --repo org/repo, set WARMHUB_REPO, or run: wh use org/repo");
 }
+function parseOrgRepoOptional(ref, config) {
+  try {
+    return parseOrgRepo(ref, config);
+  } catch (error) {
+    const suppliedRepoInfo = ref !== undefined && ref !== "" || Boolean(config.defaultRepo);
+    if (suppliedRepoInfo) {
+      throw error;
+    }
+    return {};
+  }
+}
 
 // ../../packages/warmhub-cli/src/domain-registry.ts
 class DomainRegistry {
@@ -24276,9 +24348,15 @@ function renderWarningLine(out, c, chars, op) {
   const moreSuffix = remaining > 0 ? ` ${c.dim}(+${remaining} more)${c.reset}` : "";
   out(`    ${c.yellow}${chars.warn}${c.reset} ${total} ${noun} not declared in shape${shapeLabel}: ${c.dim}${fieldsList}${c.reset}${moreSuffix}`);
 }
+function renderCommitterEcho(out, c, committer) {
+  if (!committer)
+    return;
+  out(`  ${c.dim}committer:${c.reset} ${pinnedWref(c, committer)}`);
+}
 function renderSingleOpSuccess(out, c, chars, op, opts) {
   const name = op.name ?? opts.fallbackName;
   const suffix = opts.suffix ?? "";
+  renderCommitterEcho(out, c, opts.committer);
   out(`${opts.color}${opts.marker}${c.reset} ${displayName(c, name)}${suffix}`);
   renderWarningLine(out, c, chars, op);
 }
@@ -24357,6 +24435,10 @@ async function readContentInput(filePath, inline, stdinStream) {
 }
 
 // ../../packages/warmhub-cli/src/domains/thing.ts
+var DURABLE_ID_PATTERN_RE = /^[0-9a-zA-HJ-NP-Tv-z]{60}(@(v\d+|HEAD|ALL))?$/i;
+function looksLikeDurableId(wref) {
+  return DURABLE_ID_PATTERN_RE.test(wref);
+}
 function usageError2(usage, example) {
   throw new CliError(2 /* UserInput */, "USER_INPUT", usage, undefined, `Example: ${example}`);
 }
@@ -24453,6 +24535,10 @@ function renderHead(out, c, chars, result, org, repo, shape, kind) {
       const truncated = preview.length > 80 ? `${preview.slice(0, 77)}...` : preview;
       out(`    ${c.dim}${truncated}${c.reset}`);
     }
+    const itemMeta = item.metadata;
+    if (itemMeta?.durableId) {
+      out(`    ${c.dim}durableId:${c.reset} ${itemMeta.durableId}`);
+    }
   }
   out(`${c.dim}${items.length} item(s)${c.reset}`);
 }
@@ -24472,6 +24558,19 @@ function renderThing(out, c, result) {
   if (aboutWref) {
     out(`  ${c.dim}about:${c.reset}     ${String(aboutWref)}`);
   }
+  const meta = result.metadata;
+  if (meta?.durableId || meta?.thingCreatedAt || meta?.versionCreatedAt) {
+    const now = Date.now();
+    if (meta.durableId) {
+      out(`  ${c.dim}durableId:${c.reset} ${meta.durableId}`);
+    }
+    if (meta.thingCreatedAt) {
+      out(`  ${c.dim}thingCreated:${c.reset}  ${formatTime(meta.thingCreatedAt, now)}`);
+    }
+    if (meta.versionCreatedAt) {
+      out(`  ${c.dim}versionCreated:${c.reset}${formatTime(meta.versionCreatedAt, now)}`);
+    }
+  }
   const fields = shapeName && result.data ? collectionFields(shapeName, result.data) : null;
   if (fields) {
     for (const field of fields) {
@@ -24562,6 +24661,10 @@ function renderHistory(out, c, result) {
     const wref = result.thing.wref ?? result.thing.name ?? "(unknown)";
     out(`${c.bold}History: ${pinnedWref(c, wref)}${c.reset}  ${kindLabel(c, result.thing.kind ?? "thing")}`);
   }
+  const firstMeta = result.versions?.[0]?.metadata;
+  if (firstMeta?.durableId) {
+    out(`  ${c.dim}durableId:${c.reset} ${firstMeta.durableId}`);
+  }
   const versions = result.versions ?? [];
   const now = Date.now();
   for (const ver of versions) {
@@ -24578,7 +24681,9 @@ function renderHistory(out, c, result) {
     const wref = ver.wref ?? ver.thingName;
     const wrefStr = wref ? pinnedWref(c, wref, ver.version) : "";
     const by = ver.committerWref ? `  ${c.dim}by${c.reset} ${pinnedWref(c, ver.committerWref)}` : "";
-    out(`  ${wrefStr}  ${op}  ${c.dim}${time}${c.reset}${by}`);
+    const thingCreatedAt = ver.metadata?.thingCreatedAt;
+    const thingCreatedStr = thingCreatedAt ? `  ${c.dim}born:${formatTime(thingCreatedAt, now)}${c.reset}` : "";
+    out(`  ${wrefStr}  ${op}  ${c.dim}${time}${c.reset}${by}${thingCreatedStr}`);
   }
 }
 function renderRefs(out, c, result, wref, direction) {
@@ -24846,9 +24951,9 @@ async function collectWrefs(opts) {
   ]));
 }
 async function runSingleView(ctx, wref, flags) {
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const version = flags.version;
   const depth = flags.depth;
+  const { org, repo } = looksLikeDurableId(wref) && depth === undefined ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const includeRetracted = flags["include-retracted"] || version !== undefined;
   if (depth !== undefined && (depth < 1 || depth > 5)) {
     usageError2("Usage: wh thing view <wref> --depth <1-5>", "wh thing view Game/base --depth 2");
@@ -24892,7 +24997,8 @@ async function runSingleView(ctx, wref, flags) {
   writeOutput(ctx, result, () => renderThing(ctx.out, ctx.colors, result));
 }
 async function runBatchView(ctx, wrefs, flags) {
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const allDurable = wrefs.length > 0 && wrefs.every(looksLikeDurableId);
+  const { org, repo } = allDurable ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const includeRetracted = flags["include-retracted"] || flags.version !== undefined;
   const result = await ctx.client.thing.getMany(org, repo, wrefs, flags.version, { includeRetracted });
   if (ctx.format === "jsonl") {
@@ -24944,6 +25050,53 @@ var handleView = async (ctx, { flags, args, terminator }) => {
   const singleWref = wrefs[0];
   return runSingleView(ctx, singleWref, flags);
 };
+var LEASE_MIN_TTL_MS = 1000;
+var leaseFlags = {
+  ttl: flag.number({
+    description: `Lease duration in ms (default 5000, min ${LEASE_MIN_TTL_MS}; max is operator-configured)`
+  })
+};
+function renderLease(out, c, result) {
+  renderThing(out, c, result);
+  out("");
+  out(`  ${c.dim}lease id:${c.reset}   ${result.lease.id}`);
+  out(`  ${c.dim}expires at:${c.reset} ${result.lease.expiresAt}`);
+}
+var handleLease = async (ctx, { flags, args }) => {
+  const wref = args[0];
+  if (!wref) {
+    usageError2("Usage: wh thing lease <wref> [--ttl <ms>]", "wh thing lease Player/alice --ttl 5000");
+  }
+  const ttl = flags.ttl;
+  if (ttl !== undefined && (!Number.isInteger(ttl) || ttl < LEASE_MIN_TTL_MS)) {
+    usageError2(`--ttl must be an integer >= ${LEASE_MIN_TTL_MS} (ms)`, "wh thing lease Player/alice --ttl 5000");
+  }
+  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const result = await ctx.client.thing.getWithLease(org, repo, wref, {
+    ttlMs: ttl
+  });
+  writeOutput(ctx, result, () => renderLease(ctx.out, ctx.colors, result));
+};
+var releaseLeaseFlags = {
+  "lease-id": flag.string({
+    description: "Lease token from `wh thing lease` to release early"
+  })
+};
+var handleReleaseLease = async (ctx, { flags, args }) => {
+  const wref = args[0];
+  if (!wref) {
+    usageError2("Usage: wh thing release-lease <wref> --lease-id <id>", "wh thing release-lease Player/alice --lease-id <id>");
+  }
+  const leaseId = requireLeaseIdFlag(flags["lease-id"], "wh thing release-lease Player/alice --lease-id <id>");
+  if (leaseId === undefined) {
+    usageError2("--lease-id is required for release-lease", "wh thing release-lease Player/alice --lease-id <id>");
+  }
+  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  await ctx.client.thing.releaseLease(org, repo, wref, leaseId);
+  writeOutput(ctx, { released: true, wref, leaseId }, () => {
+    ctx.out(`Released lease ${leaseId} on ${wref}`);
+  });
+};
 var graphFlags = {
   depth: flag.number({
     description: "Resolve embedded graph to this depth (default: 2, max: 5)"
@@ -24983,7 +25136,7 @@ var historyFlags = {
 };
 var handleHistory = async (ctx, { flags, args }) => {
   const wref = args[0];
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const { org, repo } = wref !== undefined && looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const shape = flags.shape;
   const about = flags.about;
   const limit = flags.limit;
@@ -25082,7 +25235,7 @@ var handleResolve = async (ctx, { args }) => {
   if (!wref) {
     usageError2("Usage: wh thing resolve <wref>", "wh thing resolve player");
   }
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const { org, repo } = looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const c = ctx.colors;
   const result = await ctx.client.thing.resolve(org, repo, wref);
   writeOutput(ctx, result, () => {
@@ -25098,6 +25251,12 @@ var reviseFlags = {
   message: flag.string({ short: "m", description: "Commit message" }),
   committer: flag.string({
     description: "Committer thing wref (e.g. Agent/bot-1)"
+  }),
+  "expected-version": flag.number({
+    description: "Only apply if the target is still at this version (optimistic concurrency)"
+  }),
+  "lease-id": flag.string({
+    description: "Read-lease token from `wh thing lease` (auto-released on success)"
   })
 };
 var createFlags = {
@@ -25138,7 +25297,8 @@ var handleCreate = async (ctx, { flags, args }) => {
   writeOutput(ctx, result, () => renderSingleOpSuccess(ctx.out, c, ctx.chars, result.operations[0] ?? {}, {
     marker: "+",
     color: c.green,
-    fallbackName: name
+    fallbackName: name,
+    committer
   }));
 };
 var handleRevise = async (ctx, { flags, args }) => {
@@ -25149,8 +25309,10 @@ var handleRevise = async (ctx, { flags, args }) => {
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const committer = flags.committer;
   const message = flags.message;
+  const leaseId = requireLeaseIdFlag(flags["lease-id"]);
   const data = flags.data ? safeParseJson(flags.data, "--data") : undefined;
   const c = ctx.colors;
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh thing revise Player/alice --data '{...}' --expected-version 3");
   if (!data) {
     usageError2("--data is required for revise", `wh thing revise Location/player --data '{"x":1}'`);
   }
@@ -25159,13 +25321,16 @@ var handleRevise = async (ctx, { flags, args }) => {
       operation: "revise",
       kind: "thing",
       name,
-      data
+      data,
+      ...expectedVersion !== undefined ? { expectedVersion } : {},
+      ...leaseId ? { leaseId } : {}
     }
   ], { committer });
   assertSingleOpSuccess(result);
   writeOutput(ctx, result, () => renderSingleOpSuccess(ctx.out, c, ctx.chars, result.operations[0] ?? {}, {
     marker: "~",
-    color: c.yellow
+    color: c.yellow,
+    committer
   }));
 };
 var retractFlags = {
@@ -25176,6 +25341,9 @@ var retractFlags = {
   message: flag.string({ short: "m", description: "Commit message" }),
   committer: flag.string({
     description: "Committer thing wref (e.g. Agent/bot-1)"
+  }),
+  "lease-id": flag.string({
+    description: "Read-lease token from `wh thing lease` (auto-released on success)"
   })
 };
 var handleThingRetract = async (ctx, { flags, args }) => {
@@ -25188,18 +25356,21 @@ var handleThingRetract = async (ctx, { flags, args }) => {
   const message = flags.message;
   const kind = flags.kind;
   const reason = flags.reason;
+  const leaseId = requireLeaseIdFlag(flags["lease-id"], "wh thing retract Player/alice --lease-id <id>");
   const c = ctx.colors;
   const result = await ctx.client.commit.apply(org, repo, message ?? `retract ${name}`, [
     {
       operation: "retract",
       name,
       ...kind ? { kind } : {},
-      ...reason ? { reason } : {}
+      ...reason ? { reason } : {},
+      ...leaseId ? { leaseId } : {}
     }
   ], { committer });
   assertSingleOpSuccess(result);
   writeOutput(ctx, result, () => {
     const op = result.operations[0];
+    renderCommitterEcho(ctx.out, c, committer);
     ctx.out(`${c.red}-${c.reset} ${displayName(c, op?.name ?? name)}`);
   });
 };
@@ -25542,7 +25713,7 @@ var handleAbout = async (ctx, { flags, args }) => {
   if (!wref) {
     usageError2("Usage: wh thing about <wref> [--shape] [--match] [--limit] [--include-retracted]", "wh thing about Location/cave");
   }
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const { org, repo } = looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   const includeRetracted = flags["include-retracted"];
   const limit = flags.limit;
   const cursor = flags.cursor;
@@ -25662,7 +25833,7 @@ var handleRefs = async (ctx, { flags, args }) => {
   if (!wref) {
     usageError2("Usage: wh thing refs <wref> [--inbound|--outbound] [--field FIELD] [--limit N]", "wh thing refs Loc/player");
   }
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
+  const { org, repo } = looksLikeDurableId(wref) ? parseOrgRepoOptional(getRepoRef(ctx), ctx.config) : parseOrgRepo(getRepoRef(ctx), ctx.config);
   if (flags.inbound && flags.outbound) {
     usageError2("Cannot specify both --inbound and --outbound", "wh thing refs Loc/player --outbound");
   }
@@ -25743,6 +25914,25 @@ var THING_DOMAIN = defineDomain({
       ],
       handler: handleView
     },
+    lease: {
+      prime: true,
+      summary: "Acquire a short, exclusive read lease on a thing (read + lease in one call)",
+      args: "<wref>",
+      flags: leaseFlags,
+      examples: [
+        "wh thing lease Player/alice",
+        "wh thing lease Player/alice --ttl 5000"
+      ],
+      handler: handleLease
+    },
+    "release-lease": {
+      prime: true,
+      summary: "Release a read lease early (idempotent)",
+      args: "<wref>",
+      flags: releaseLeaseFlags,
+      examples: ["wh thing release-lease Player/alice --lease-id <id>"],
+      handler: handleReleaseLease
+    },
     history: {
       prime: true,
       summary: "Show version history",
@@ -26056,7 +26246,8 @@ var handleRevise2 = async (ctx, { flags, args }) => {
   assertSingleOpSuccess(result);
   writeOutput(ctx, result, () => renderSingleOpSuccess(ctx.out, c, ctx.chars, result.operations[0] ?? {}, {
     marker: "~",
-    color: c.yellow
+    color: c.yellow,
+    committer: flags.committer
   }));
 };
 var retractFlags2 = {
@@ -26085,6 +26276,7 @@ var handleRetract = async (ctx, { flags, args }) => {
   assertSingleOpSuccess(result);
   writeOutput(ctx, result, () => {
     const op = result.operations[0];
+    renderCommitterEcho(ctx.out, ctx.colors, flags.committer);
     ctx.out(`${ctx.colors.red}-${ctx.colors.reset} ${displayName(ctx.colors, op?.name ?? name)}`);
   });
 };
@@ -26181,7 +26373,8 @@ var handleCreate2 = async (ctx, { flags, args }) => {
   writeOutput(ctx, result, () => renderSingleOpSuccess(ctx.out, c, ctx.chars, result.operations[0] ?? {}, {
     marker: "+",
     color: c.green,
-    suffix: ` ${c.dim}(${shape})${c.reset}`
+    suffix: ` ${c.dim}(${shape})${c.reset}`,
+    committer
   }));
 };
 var listFlags = {
@@ -27613,6 +27806,59 @@ import { createReadStream as createReadStream2 } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { createInterface as createInterface2 } from "node:readline";
 
+// ../../packages/warmhub-cli/src/commit-payload-validate.ts
+var NUL = String.fromCharCode(0);
+function findInvalidControlByte(data, rootLabel = "data") {
+  const segs = [];
+  const pos = visit(data, segs);
+  return pos === -1 ? null : { path: buildPath(rootLabel, segs), position: pos };
+}
+function visit(value, segs) {
+  if (typeof value === "string")
+    return value.indexOf(NUL);
+  if (value === null || typeof value !== "object")
+    return -1;
+  if (Array.isArray(value)) {
+    for (let i = 0;i < value.length; i++) {
+      segs.push(i);
+      const p = visit(value[i], segs);
+      if (p !== -1)
+        return p;
+      segs.pop();
+    }
+    return -1;
+  }
+  const keys = Object.keys(value);
+  for (let i = 0;i < keys.length; i++) {
+    const k = keys[i];
+    segs.push(k);
+    const p = visit(value[k], segs);
+    if (p !== -1)
+      return p;
+    segs.pop();
+  }
+  return -1;
+}
+function buildPath(root, segs) {
+  let out = root;
+  for (const s of segs)
+    out += typeof s === "number" ? `[${s}]` : `.${s}`;
+  return out;
+}
+function formatInvalidControlByteMessage(hit, locator) {
+  return {
+    message: `${locator}: ${hit.path} contains literal U+0000 byte at position ${hit.position}, ` + "which PostgreSQL `text` cannot store (SQLSTATE 22P05).",
+    hint: "Strip NUL bytes before submit, e.g. `.replace(/\\u0000/g, '')`, or pass --allow-nul-bytes to send anyway."
+  };
+}
+function assertNoNulBytes(data, locator) {
+  const hit = findInvalidControlByte(data);
+  if (!hit)
+    return;
+  const { message, hint } = formatInvalidControlByteMessage(hit, locator);
+  throw new CliError(2 /* UserInput */, "USER_INPUT", message, undefined, hint);
+}
+
 // ../../packages/warmhub-cli/src/domains/stream-progress.ts
 import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
@@ -27914,7 +28160,9 @@ async function applyJsonlCommit(ctx, args) {
       } catch (cause) {
         const completed = operationOffset + opCount;
         if (opCount > 0 || firstJsonlAppendErrorMayHaveCommitted(cause)) {
-          throw new CliError(4 /* Backend */, "BACKEND", `Stream append failed after ${completed} acknowledged operation(s).`, cause, "The failed append may also have landed; inspect repository state before submitting any remaining JSONL operations.");
+          const backendCode = toWarmHubError(cause).backendCode;
+          const suffix = backendCode ? ` (backend: ${backendCode})` : "";
+          throw new CliError(4 /* Backend */, "BACKEND", `Stream append failed after ${completed} acknowledged operation(s).${suffix}`, cause, "The failed append may also have landed; inspect repository state before submitting any remaining JSONL operations.", undefined, backendCode);
         }
         throw cause;
       }
@@ -27972,6 +28220,24 @@ async function applyJsonlCommit(ctx, args) {
           continue;
         assertWithinStreamOpLimit(parsedOpCount + 1);
         const operation = safeParseJson(trimmed, `${args.lineLabel} JSONL line ${lineNumber}`);
+        if (args.allowNulBytes !== true) {
+          try {
+            assertNoNulBytes("data" in operation ? operation.data : undefined, `${args.lineLabel} JSONL line ${lineNumber}`);
+          } catch (cause) {
+            if (cause instanceof CliError) {
+              if (opCount > 0) {
+                const completed = operationOffset + opCount;
+                const baseHint = cause.hint && cause.hint.length > 0 ? `${cause.hint} ` : "";
+                throw new CliError(4 /* Backend */, "BACKEND", `${cause.message} (${completed} earlier operation(s) already acknowledged by the server before this NUL-byte rejection).`, undefined, `${baseHint}The earlier chunks have landed; inspect repository state before submitting any remaining JSONL operations.`);
+              }
+              if (operationOffset > 0) {
+                const baseHint = cause.hint && cause.hint.length > 0 ? `${cause.hint} ` : "";
+                throw new CliError(cause.code, cause.kind, `${cause.message} (${operationOffset} earlier operation(s) already acknowledged by the server in a prior run; this run made no backend writes before the NUL-byte rejection).`, undefined, `${baseHint}Fix the offending input; the prior-run chunks remain landed and unaffected by this local validation failure.`);
+              }
+            }
+            throw cause;
+          }
+        }
         parsedOpCount += 1;
         chunk.push(withSkipExisting(operation, args.skipExisting === true));
         if (chunk.length < chunkSize)
@@ -28189,7 +28455,7 @@ function buildAddOperations(input) {
   });
 }
 function buildRetractOperations(input) {
-  const { retractNames, kinds, reasons } = input;
+  const { retractNames, kinds, reasons, leaseId } = input;
   const assertCardinality = (flagName, values) => {
     if (values.length === 0)
       return;
@@ -28215,7 +28481,8 @@ function buildRetractOperations(input) {
       operation: "retract",
       name,
       ...kind ? { kind } : {},
-      ...reason ? { reason } : {}
+      ...reason ? { reason } : {},
+      ...leaseId ? { leaseId } : {}
     };
   });
 }
@@ -28272,6 +28539,9 @@ var createFlags3 = {
   "chunk-size": flag.number({
     description: `Streamed ops per append chunk for --stream or .jsonl --file (default: ${DEFAULT_STREAM_APPEND_CHUNK_SIZE}, max: ${MAX_STREAM_APPEND_OPERATION_COUNT})`
   }),
+  "allow-nul-bytes": flag.boolean({
+    description: "Skip the client-side pre-check that rejects literal U+0000 bytes in op data. PostgreSQL `text` columns still cannot store these — use only when the backend storage type is known to tolerate them."
+  }),
   "timing-out": flag.string({
     description: "Write per-append timing sidecar JSON to this path (debug/bench instrumentation)"
   }),
@@ -28322,6 +28592,12 @@ var createFlags3 = {
   }),
   members: flag.string({
     description: "Collection members (comma-separated wrefs)"
+  }),
+  "expected-version": flag.number({
+    description: "Only apply if the --revise target is still at this version (optimistic concurrency). Requires --revise."
+  }),
+  "lease-id": flag.string({
+    description: "Read-lease token from `wh thing lease`, bound to --revise/--retract (auto-released on success)"
   })
 };
 var handleSubmit = async (ctx, { flags, args }) => {
@@ -28334,6 +28610,7 @@ var handleSubmit = async (ctx, { flags, args }) => {
   const progressRequested = flags.progress === true;
   const skipExisting = flags["skip-existing"] === true;
   const chunkSize = flags["chunk-size"];
+  const allowNulBytes = flags["allow-nul-bytes"] === true;
   const timingOut = flags["timing-out"];
   const resumeStreamId = flags["stream-id"];
   const resumeAllocatedTokens = parseAllocatedTokensFlag(flags["allocated-tokens"]);
@@ -28347,6 +28624,14 @@ var handleSubmit = async (ctx, { flags, args }) => {
   const abouts = flags.about ?? [];
   const reasons = flags.reason ?? [];
   const kinds = flags.kind ?? [];
+  const expectedVersion = parsePositiveIntFlag(flags["expected-version"], "--expected-version", "wh commit submit --revise Player/alice --data '{...}' --expected-version 3");
+  if (expectedVersion !== undefined && !reviseName) {
+    usageError4("--expected-version requires --revise", "wh commit submit --revise Player/alice --data '{...}' --expected-version 3");
+  }
+  const leaseIdFlag = requireLeaseIdFlag(flags["lease-id"], `wh commit submit --revise Player/alice --data '{"score":2}' --lease-id <id>`);
+  if (leaseIdFlag !== undefined && reviseName === undefined && retractNames.length === 0) {
+    throw new CliError(2 /* UserInput */, "USER_INPUT", "--lease-id requires --revise or --retract.", undefined, 'For --ops/--file/--stream writes, carry "leaseId" inline on the revise/retract op.');
+  }
   const validKinds = [
     "thing",
     "assertion",
@@ -28438,7 +28723,8 @@ var handleSubmit = async (ctx, { flags, args }) => {
     operations = buildRetractOperations({
       retractNames,
       kinds,
-      reasons
+      reasons,
+      leaseId: leaseIdFlag
     });
   } else if (reviseName) {
     if (dataJsons.length > 1) {
@@ -28451,13 +28737,30 @@ var handleSubmit = async (ctx, { flags, args }) => {
     const data = rawData ? safeParseJson(rawData, "--data") : undefined;
     const kindFlag = kinds[0];
     const kind = kindFlag ?? "thing";
-    operations = [{ operation: "revise", kind, name: reviseName, data }];
+    operations = [
+      {
+        operation: "revise",
+        kind,
+        name: reviseName,
+        data,
+        ...expectedVersion !== undefined ? { expectedVersion } : {},
+        ...leaseIdFlag ? { leaseId: leaseIdFlag } : {}
+      }
+    ];
   } else {
     usageError4("Usage: wh commit submit --ops '<json>' or --add <name> [--data <json>]", `wh commit submit --add player --shape location --data '{"x":0,"y":0}'`);
   }
   if (!streamInput && operations.length > 0) {
     rejectLegacyLifecycleOperations(operations);
     assertWithinStreamOpLimit(operations.length);
+    if (!allowNulBytes) {
+      const source = opsJson ? "--ops" : opsFile ? opsFile : addNames.length > 0 ? "--add" : reviseName !== undefined ? "--revise" : collectionType ? "--type" : "op";
+      for (let i = 0;i < operations.length; i++) {
+        const op = operations[i];
+        const namePart = op.name ? ` (${op.name})` : "";
+        assertNoNulBytes("data" in op ? op.data : undefined, `${source} op ${i}${namePart}`);
+      }
+    }
   }
   const message = streamInput || jsonlFile ? messageFlag : messageFlag ?? synthesizeCommitMessage(operations);
   let result;
@@ -28472,7 +28775,8 @@ var handleSubmit = async (ctx, { flags, args }) => {
       skipExisting,
       streamId: resumeStreamId,
       allocatedTokens: resumeAllocatedTokens,
-      operationOffset: resumeOperationOffset
+      operationOffset: resumeOperationOffset,
+      allowNulBytes
     }) : jsonlFile ? await applyJsonlFileCommit(ctx, {
       org,
       repo,
@@ -28485,7 +28789,8 @@ var handleSubmit = async (ctx, { flags, args }) => {
       skipExisting,
       streamId: resumeStreamId,
       allocatedTokens: resumeAllocatedTokens,
-      operationOffset: resumeOperationOffset
+      operationOffset: resumeOperationOffset,
+      allowNulBytes
     }) : await ctx.client.commit.apply(org, repo, message, operations, {
       committer,
       skipExisting
@@ -28502,6 +28807,7 @@ var handleSubmit = async (ctx, { flags, args }) => {
     writeOutput(ctx, result, () => {
       const failureSuffix = failedCount > 0 ? `, ${failedCount} failed` : "";
       ctx.out(`${message ?? "(no message)"}  ${c.dim}(${result.operationCount} ops${failureSuffix})${c.reset}`);
+      renderCommitterEcho(ctx.out, c, committer);
       for (const op of result.operations) {
         const failed = isFailedOpStatus(op.status);
         const marker = failed ? "!" : op.operation === "add" ? "+" : op.operation === "revise" ? "~" : "-";
@@ -31064,12 +31370,28 @@ var updateFlags = {
   })
 };
 var validateFlags = {};
-var listFlags2 = {};
+var listFlags2 = {
+  limit: flag.number({
+    description: "Maximum components per page (default: 50, max: 500)"
+  }),
+  cursor: flag.string({ description: "Opaque pagination cursor" }),
+  all: flag.boolean({
+    description: "Fetch all pages (auto-paginate until exhausted)"
+  })
+};
 var viewFlags3 = {};
 var teardownFlags = {};
 var doctorFlags = {};
 var initFlags = {};
-var searchFlags2 = {};
+var searchFlags2 = {
+  limit: flag.number({
+    description: "Maximum components per page (default: 50, max: 500)"
+  }),
+  cursor: flag.string({ description: "Opaque pagination cursor" }),
+  all: flag.boolean({
+    description: "Fetch all pages before filtering (auto-paginate until exhausted)"
+  })
+};
 var registerFlags = {
   org: flag.string({ description: "Owner org for the registered component" }),
   "source-url": flag.string({ description: "Source GitHub URL for installs" }),
@@ -31449,12 +31771,33 @@ function normalizeGithubRemote(remote) {
   }
   return;
 }
-var handleList2 = async (ctx) => {
+async function fetchComponentPages(client, org, repo, opts) {
+  const firstPage = await client.component.list(org, repo, {
+    limit: opts.limit,
+    cursor: opts.cursor
+  });
+  const items = [...firstPage.items ?? []];
+  let nextCursor = firstPage.nextCursor;
+  if (opts.all) {
+    while (nextCursor) {
+      const page = await client.component.list(org, repo, {
+        limit: opts.limit,
+        cursor: nextCursor
+      });
+      items.push(...page.items ?? []);
+      nextCursor = page.nextCursor;
+    }
+  }
+  return { items, nextCursor };
+}
+var handleList2 = async (ctx, { flags }) => {
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
-  const result = await ctx.client.component.list(org, repo);
-  const items = result.items ?? [];
+  const c = ctx.colors;
+  const { items, nextCursor } = await fetchComponentPages(ctx.client, org, repo, { all: flags.all, limit: flags.limit, cursor: flags.cursor });
+  if (!flags.all && nextCursor) {
+    ctx.status(`${c.yellow}${items.length} shown, more available${c.reset} — use ${c.cyan}--all${c.reset} to fetch every page, ` + `or re-run the same command plus ${c.cyan}--cursor=${nextCursor}${c.reset} to resume from here.`);
+  }
   writeOutput(ctx, items, () => {
-    const c = ctx.colors;
     if (!items.length) {
       ctx.status(`${c.dim}No components installed${c.reset}`);
       return;
@@ -31470,17 +31813,20 @@ var handleList2 = async (ctx) => {
     }
   });
 };
-var handleSearch2 = async (ctx, { args }) => {
+var handleSearch2 = async (ctx, { flags, args }) => {
   const query = args[0]?.trim();
   if (!query) {
     usageError("Usage: wh component search <query> --repo org/repo", "wh component search research --repo myorg/myrepo");
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
-  const result = await ctx.client.component.list(org, repo);
+  const c = ctx.colors;
+  const { items: allItems, nextCursor } = await fetchComponentPages(ctx.client, org, repo, { all: flags.all, limit: flags.limit, cursor: flags.cursor });
   const needle = query.toLowerCase();
-  const items = (result.items ?? []).filter((item) => [item.componentId, item.componentName, item.source].filter((value) => typeof value === "string").some((value) => value.toLowerCase().includes(needle)));
+  const items = allItems.filter((item) => [item.componentId, item.componentName, item.source].filter((value) => typeof value === "string").some((value) => value.toLowerCase().includes(needle)));
+  if (!flags.all && nextCursor) {
+    ctx.status(`${c.yellow}${allItems.length} component(s) searched, more pages available${c.reset} — matches beyond this page were not searched. ` + `Use ${c.cyan}--all${c.reset} to search every page, ` + `or re-run the same command plus ${c.cyan}--cursor=${nextCursor}${c.reset} to continue from here.`);
+  }
   writeOutput(ctx, items, () => {
-    const c = ctx.colors;
     if (!items.length) {
       ctx.status(`${c.dim}No components matching "${query}" in ${org}/${repo}${c.reset}`);
       return;
@@ -33610,7 +33956,7 @@ cat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped
 - \`wh thing history [wref] [--shape] [--about] [--include-retracted]\` — Version history
 - \`wh thing resolve <wref>\` — Resolve wref
 - \`wh thing create <name|Shape/name> --data <json> [--shape] [--message] [--committer]\` — Create
-- \`wh thing revise <name> [--data] [--message] [--committer]\` — Revise
+- \`wh thing revise <name> [--data] [--message] [--committer] [--expected-version]\` — Revise (CONFLICT if HEAD≠n)
 - \`wh thing retract <wref> -m <message> [--reason] [--kind]\` — Retract
 - \`wh thing query [--shape] [--kind] [--about] [--match]\` — Query by filters
 - \`wh thing search <query> [--shape] [--kind] [--about] [--mode]\` — Search text
@@ -33619,7 +33965,7 @@ cat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped
 - \`wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--limit] [--include-retracted]\` — Show assertions about the target identity; \`--resolve-collections\` expands collection members for bare/@HEAD/@ALL inputs, not pinned @vN
 
 ### commit — Write operations
-- \`wh commit submit [--ops|--file|--add|--revise|--retract] [--kind] [--data] [--reason] [--chunk-size] [--skip-existing] [--progress] [--stream-id] [--allocated-tokens] [--operation-offset]\` — Submit operations (bare \`wh commit\` is equivalent). Use \`--file ops.jsonl --chunk-size 5000 --skip-existing\` for bulk ingest.
+- \`wh commit submit [--ops|--file|--add|--revise|--retract] [--kind] [--data] [--reason] [--expected-version] [--chunk-size] [--skip-existing] [--progress] [--stream-id] [--allocated-tokens] [--operation-offset]\` — Submit operations (bare \`wh commit\` is equivalent). Use \`--file ops.jsonl --chunk-size 5000 --skip-existing\` for bulk ingest.
 - \`wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]\` — Generate sample ops
 
 ### assertion — Assertion operations
@@ -33941,6 +34287,13 @@ var handleCreate5 = async (ctx, { flags, args }) => {
 var repoListFlags = {
   "include-archived": flag.boolean({
     description: "Include archived repositories"
+  }),
+  limit: flag.number({
+    description: "Maximum repos per page (default: 50, max: 200)"
+  }),
+  cursor: flag.string({ description: "Opaque pagination cursor" }),
+  all: flag.boolean({
+    description: "Fetch all pages (auto-paginate until exhausted)"
   })
 };
 var handleList5 = async (ctx, { flags, args }) => {
@@ -33949,16 +34302,36 @@ var handleList5 = async (ctx, { flags, args }) => {
     usageError8("Usage: wh repo list <org> (or set WARMHUB_ORG)", "wh repo list myorg");
   }
   const c = ctx.colors;
-  const repos = await ctx.client.repo.list(orgName, {
-    includeArchived: flags["include-archived"]
+  const all = flags.all;
+  const includeArchived = flags["include-archived"];
+  const firstPage = await ctx.client.repo.list(orgName, {
+    includeArchived,
+    limit: flags.limit,
+    cursor: flags.cursor
   });
-  writeOutput(ctx, repos.items, () => {
-    if (!repos.items.length) {
+  const items = [...firstPage.items];
+  let nextCursor = firstPage.nextCursor;
+  if (all) {
+    while (nextCursor) {
+      const page = await ctx.client.repo.list(orgName, {
+        includeArchived,
+        limit: flags.limit,
+        cursor: nextCursor
+      });
+      items.push(...page.items);
+      nextCursor = page.nextCursor;
+    }
+  }
+  if (!all && nextCursor) {
+    ctx.status(`${c.yellow}${items.length} shown, more available${c.reset} — use ${c.cyan}--all${c.reset} to fetch every page, ` + `or re-run the same command plus ${c.cyan}--cursor=${nextCursor}${c.reset} to resume from here.`);
+  }
+  writeOutput(ctx, items, () => {
+    if (!items.length) {
       ctx.status(`${c.dim}No repos in ${orgName}${c.reset}`);
       return;
     }
     ctx.out(`${c.bold}Repos in ${orgName}:${c.reset}`);
-    for (const r of repos.items) {
+    for (const r of items) {
       const display = r.displayName && r.displayName !== r.name ? `  ${c.dim}${r.displayName}${c.reset}` : "";
       const desc = r.description ? `  ${c.dim}${r.description}${c.reset}` : "";
       const archived = r.archivedAt ? `  ${c.yellow}[archived]${c.reset}` : "";
@@ -34388,6 +34761,8 @@ var handleContentSet = async (ctx, { args, flags }) => {
       });
       break;
     }
+    default:
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `--kind ${kind} does not support \`set\`.`);
   }
 };
 var handleContentGenerate = async (ctx, { args, flags }) => {
@@ -34417,6 +34792,8 @@ var handleContentGenerate = async (ctx, { args, flags }) => {
       });
       break;
     }
+    default:
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `--kind ${kind} does not support \`generate\`.`);
   }
 };
 var CONTENT_SUBDOMAIN = defineDomain({
@@ -34774,6 +35151,7 @@ var handleRetract2 = async (ctx, { flags, args }) => {
   ], { committer: flags.committer });
   assertSingleOpSuccess(result);
   writeOutput(ctx, result, () => {
+    renderCommitterEcho(ctx.out, c, flags.committer);
     ctx.out(`${c.red}Retracted${c.reset} ${c.magenta}${shapeName}${c.reset}`);
   });
 };
@@ -37203,7 +37581,7 @@ async function runCli(argv, opts) {
       return exitCode;
     }
     if (globalHelpAllRequested) {
-      printDomainHelp(out, { allFlags: true, allDomains: true });
+      await printDomainHelp(out, { allFlags: true, allDomains: true });
       exitCode = 0 /* Ok */;
       return exitCode;
     }
@@ -37355,7 +37733,7 @@ function resolveLogLevel(flags, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.48.0",
+  version: "0.49.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -38382,4 +38760,4 @@ if (!updateCheckSuppressedByArgv && shouldRunUpdateCheck(updateEligibility)) {
 var interceptedExitCode = await maybeHandleComponentShellBoundary(dispatchArgv);
 process.exitCode = interceptedExitCode === undefined ? await runCli(dispatchArgv, { version: package_default3.version }) : interceptedExitCode;
 
-//# debugId=4217C1CF64E0C7F164756E2164756E21
+//# debugId=7BEE2CF049FB035564756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",