commonswarm 0.1.51 → 0.1.53

package/cswarm.cjs

@@ -13530,6 +13530,188 @@ var import_node_os10 = require("node:os");
 var import_node_path21 = require("node:path");
 var import_promises13 = require("node:readline/promises");
 
+// src/protocol/events.ts
+var SCHEMA_VERSION = 1;
+var EVENT_TYPES = [
+  "TaskCreated",
+  "LeaseAcquired",
+  "LeaseRenewed",
+  "LeaseHandedOff",
+  "LeaseTakenOver",
+  "TaskSubmitted",
+  "TaskClosed",
+  "TaskReopened",
+  "CommandRejected"
+];
+
+// src/protocol/reducer.ts
+function req(payload, keys, type, seq) {
+  if (!payload || typeof payload !== "object") throw new StreamIntegrityError(`event "${type}" at seq ${seq} has a non-object payload`);
+  for (const k of keys) {
+    if (payload[k] === void 0) {
+      throw new StreamIntegrityError(`event "${type}" at seq ${seq} is missing payload field "${String(k)}"`);
+    }
+  }
+  return payload;
+}
+var UnknownEventTypeError = class extends Error {
+  constructor(type, seq) {
+    super(`unknown authoritative event type "${type}" at seq ${seq}; halting`);
+    this.type = type;
+    this.seq = seq;
+    this.name = "UnknownEventTypeError";
+  }
+  type;
+  seq;
+};
+var StreamIntegrityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StreamIntegrityError";
+  }
+};
+function reduceTask(prev, env) {
+  if (!EVENT_TYPES.includes(env.type)) {
+    throw new UnknownEventTypeError(env.type, env.seq);
+  }
+  if (env.schema_version !== SCHEMA_VERSION) {
+    throw new StreamIntegrityError(`event "${env.type}" at seq ${env.seq} is schema v${env.schema_version}, expected v${SCHEMA_VERSION} (upcast before reduce)`);
+  }
+  if (env.type === "CommandRejected") {
+    if (!prev) throw new StreamIntegrityError(`CommandRejected before task exists (seq ${env.seq})`);
+    req(env.payload, ["task_id", "command", "reason", "detail"], env.type, env.seq);
+    return prev;
+  }
+  if (env.type === "TaskCreated") {
+    if (prev) throw new StreamIntegrityError(`TaskCreated for an already-existing task (seq ${env.seq})`);
+    const p = req(env.payload, ["task_id", "slug"], env.type, env.seq);
+    return {
+      task_id: p.task_id,
+      slug: p.slug,
+      lifecycle: "open",
+      version: 1,
+      epoch: 0,
+      owner: null,
+      lease_expiry: null,
+      submission: null,
+      closed_disposition: null
+    };
+  }
+  if (!prev) throw new StreamIntegrityError(`event "${env.type}" before TaskCreated (seq ${env.seq})`);
+  const s = prev;
+  function assertEpochIncrease(ep) {
+    if (typeof ep !== "number" || ep <= s.epoch) {
+      throw new StreamIntegrityError(`${env.type} at seq ${env.seq} has non-increasing epoch ${ep} (current ${s.epoch})`);
+    }
+  }
+  const leaseLifecycle = s.submission ? "awaiting_review" : "active";
+  switch (env.type) {
+    case "LeaseAcquired": {
+      const p = req(env.payload, ["task_id", "epoch", "owner", "lease_expiry"], env.type, env.seq);
+      assertEpochIncrease(p.epoch);
+      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.owner, lease_expiry: p.lease_expiry };
+    }
+    case "LeaseRenewed": {
+      const p = req(env.payload, ["task_id", "epoch", "lease_expiry"], env.type, env.seq);
+      if (p.epoch !== s.epoch) throw new StreamIntegrityError(`LeaseRenewed at seq ${env.seq} epoch ${p.epoch} != current ${s.epoch}`);
+      return { ...s, lease_expiry: p.lease_expiry };
+    }
+    case "LeaseHandedOff": {
+      const p = req(env.payload, ["task_id", "epoch", "from_owner", "to_owner", "lease_expiry"], env.type, env.seq);
+      assertEpochIncrease(p.epoch);
+      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.to_owner, lease_expiry: p.lease_expiry };
+    }
+    case "LeaseTakenOver": {
+      const p = req(env.payload, ["task_id", "epoch", "owner", "lease_expiry", "grant_id"], env.type, env.seq);
+      assertEpochIncrease(p.epoch);
+      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.owner, lease_expiry: p.lease_expiry };
+    }
+    case "TaskSubmitted": {
+      const p = req(env.payload, ["task_id", "epoch", "branch", "head_sha", "evidence_set"], env.type, env.seq);
+      return {
+        ...s,
+        lifecycle: "awaiting_review",
+        submission: { epoch: p.epoch, branch: p.branch, head_sha: p.head_sha, evidence_set: [...p.evidence_set] }
+      };
+    }
+    case "TaskClosed": {
+      const p = req(env.payload, ["task_id", "epoch", "disposition", "grant_id"], env.type, env.seq);
+      return { ...s, lifecycle: "done", closed_disposition: p.disposition };
+    }
+    case "TaskReopened": {
+      const p = req(env.payload, ["task_id", "version"], env.type, env.seq);
+      if (p.version <= s.version) throw new StreamIntegrityError(`TaskReopened at seq ${env.seq} version ${p.version} not > current ${s.version}`);
+      return { ...s, lifecycle: "reopened", version: p.version, submission: null, owner: null, lease_expiry: null };
+    }
+    default: {
+      throw new UnknownEventTypeError(env.type, env.seq);
+    }
+  }
+}
+
+// src/protocol/idempotency.ts
+function canonicalJson(value) {
+  return JSON.stringify(sortValue(value));
+}
+function sortValue(v) {
+  if (Array.isArray(v)) return v.map(sortValue);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      out[k] = sortValue(v[k]);
+    }
+    return out;
+  }
+  return v;
+}
+
+// src/protocol/upcasters.ts
+var registry = /* @__PURE__ */ new Map();
+function key(type, fromVersion) {
+  return `${type}:${fromVersion}`;
+}
+function registerUpcaster(type, fromVersion, fn) {
+  registry.set(key(type, fromVersion), fn);
+}
+var UpcastError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UpcastError";
+  }
+};
+function upcastPayload(type, fromVersion, payload) {
+  let v = fromVersion;
+  let p = payload;
+  if (v > SCHEMA_VERSION) {
+    throw new UpcastError(`event "${type}" is schema v${v}, newer than supported v${SCHEMA_VERSION}; halting`);
+  }
+  while (v < SCHEMA_VERSION) {
+    const fn = registry.get(key(type, v));
+    if (!fn) throw new UpcastError(`no upcaster for "${type}" v${v}\u2192v${v + 1}`);
+    p = fn(p);
+    v += 1;
+  }
+  return { payload: p, schema_version: SCHEMA_VERSION };
+}
+function upcastEnvelope(raw) {
+  const { payload, schema_version } = upcastPayload(raw.type, raw.schema_version, raw.payload);
+  return { ...raw, payload, schema_version };
+}
+registerUpcaster("TaskCreated", 0, (p) => ({ task_id: p.id, slug: p.name }));
+
+// src/protocol/workspace-commands.ts
+var INVITATION_MAX_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var AGENT_TOKEN_DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var AGENT_TOKEN_MAX_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
+var RENEWAL_HORIZON_DEFAULT_MS = 30 * 24 * 60 * 60 * 1e3;
+var RENEWAL_HORIZON_MAX_MS = 90 * 24 * 60 * 60 * 1e3;
+
+// src/protocol/brain-version-window.ts
+var BRAIN_FILE_PREFIX = "brain--";
+var BRAIN_FILE_SUFFIX = ".md";
+var BRAIN_TOPIC_MAX_LENGTH = 255 - BRAIN_FILE_PREFIX.length - BRAIN_FILE_SUFFIX.length;
+var FILE_VERSION_PRECONDITION_FAILED = "file_version_precondition_failed";
+
 // src/cloud/auth.ts
 var import_node_crypto2 = require("node:crypto");
 var import_node_http = require("node:http");
@@ -21959,189 +22141,6 @@ async function logout(target2, store2, scope = "local", options = {}) {
 
 // src/cloud/command-client.ts
 var import_node_crypto3 = require("node:crypto");
-
-// src/protocol/events.ts
-var SCHEMA_VERSION = 1;
-var EVENT_TYPES = [
-  "TaskCreated",
-  "LeaseAcquired",
-  "LeaseRenewed",
-  "LeaseHandedOff",
-  "LeaseTakenOver",
-  "TaskSubmitted",
-  "TaskClosed",
-  "TaskReopened",
-  "CommandRejected"
-];
-
-// src/protocol/reducer.ts
-function req(payload, keys, type, seq) {
-  if (!payload || typeof payload !== "object") throw new StreamIntegrityError(`event "${type}" at seq ${seq} has a non-object payload`);
-  for (const k of keys) {
-    if (payload[k] === void 0) {
-      throw new StreamIntegrityError(`event "${type}" at seq ${seq} is missing payload field "${String(k)}"`);
-    }
-  }
-  return payload;
-}
-var UnknownEventTypeError = class extends Error {
-  constructor(type, seq) {
-    super(`unknown authoritative event type "${type}" at seq ${seq}; halting`);
-    this.type = type;
-    this.seq = seq;
-    this.name = "UnknownEventTypeError";
-  }
-  type;
-  seq;
-};
-var StreamIntegrityError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "StreamIntegrityError";
-  }
-};
-function reduceTask(prev, env) {
-  if (!EVENT_TYPES.includes(env.type)) {
-    throw new UnknownEventTypeError(env.type, env.seq);
-  }
-  if (env.schema_version !== SCHEMA_VERSION) {
-    throw new StreamIntegrityError(`event "${env.type}" at seq ${env.seq} is schema v${env.schema_version}, expected v${SCHEMA_VERSION} (upcast before reduce)`);
-  }
-  if (env.type === "CommandRejected") {
-    if (!prev) throw new StreamIntegrityError(`CommandRejected before task exists (seq ${env.seq})`);
-    req(env.payload, ["task_id", "command", "reason", "detail"], env.type, env.seq);
-    return prev;
-  }
-  if (env.type === "TaskCreated") {
-    if (prev) throw new StreamIntegrityError(`TaskCreated for an already-existing task (seq ${env.seq})`);
-    const p = req(env.payload, ["task_id", "slug"], env.type, env.seq);
-    return {
-      task_id: p.task_id,
-      slug: p.slug,
-      lifecycle: "open",
-      version: 1,
-      epoch: 0,
-      owner: null,
-      lease_expiry: null,
-      submission: null,
-      closed_disposition: null
-    };
-  }
-  if (!prev) throw new StreamIntegrityError(`event "${env.type}" before TaskCreated (seq ${env.seq})`);
-  const s = prev;
-  function assertEpochIncrease(ep) {
-    if (typeof ep !== "number" || ep <= s.epoch) {
-      throw new StreamIntegrityError(`${env.type} at seq ${env.seq} has non-increasing epoch ${ep} (current ${s.epoch})`);
-    }
-  }
-  const leaseLifecycle = s.submission ? "awaiting_review" : "active";
-  switch (env.type) {
-    case "LeaseAcquired": {
-      const p = req(env.payload, ["task_id", "epoch", "owner", "lease_expiry"], env.type, env.seq);
-      assertEpochIncrease(p.epoch);
-      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.owner, lease_expiry: p.lease_expiry };
-    }
-    case "LeaseRenewed": {
-      const p = req(env.payload, ["task_id", "epoch", "lease_expiry"], env.type, env.seq);
-      if (p.epoch !== s.epoch) throw new StreamIntegrityError(`LeaseRenewed at seq ${env.seq} epoch ${p.epoch} != current ${s.epoch}`);
-      return { ...s, lease_expiry: p.lease_expiry };
-    }
-    case "LeaseHandedOff": {
-      const p = req(env.payload, ["task_id", "epoch", "from_owner", "to_owner", "lease_expiry"], env.type, env.seq);
-      assertEpochIncrease(p.epoch);
-      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.to_owner, lease_expiry: p.lease_expiry };
-    }
-    case "LeaseTakenOver": {
-      const p = req(env.payload, ["task_id", "epoch", "owner", "lease_expiry", "grant_id"], env.type, env.seq);
-      assertEpochIncrease(p.epoch);
-      return { ...s, lifecycle: leaseLifecycle, epoch: p.epoch, owner: p.owner, lease_expiry: p.lease_expiry };
-    }
-    case "TaskSubmitted": {
-      const p = req(env.payload, ["task_id", "epoch", "branch", "head_sha", "evidence_set"], env.type, env.seq);
-      return {
-        ...s,
-        lifecycle: "awaiting_review",
-        submission: { epoch: p.epoch, branch: p.branch, head_sha: p.head_sha, evidence_set: [...p.evidence_set] }
-      };
-    }
-    case "TaskClosed": {
-      const p = req(env.payload, ["task_id", "epoch", "disposition", "grant_id"], env.type, env.seq);
-      return { ...s, lifecycle: "done", closed_disposition: p.disposition };
-    }
-    case "TaskReopened": {
-      const p = req(env.payload, ["task_id", "version"], env.type, env.seq);
-      if (p.version <= s.version) throw new StreamIntegrityError(`TaskReopened at seq ${env.seq} version ${p.version} not > current ${s.version}`);
-      return { ...s, lifecycle: "reopened", version: p.version, submission: null, owner: null, lease_expiry: null };
-    }
-    default: {
-      throw new UnknownEventTypeError(env.type, env.seq);
-    }
-  }
-}
-
-// src/protocol/idempotency.ts
-function canonicalJson(value) {
-  return JSON.stringify(sortValue(value));
-}
-function sortValue(v) {
-  if (Array.isArray(v)) return v.map(sortValue);
-  if (v && typeof v === "object") {
-    const out = {};
-    for (const k of Object.keys(v).sort()) {
-      out[k] = sortValue(v[k]);
-    }
-    return out;
-  }
-  return v;
-}
-
-// src/protocol/upcasters.ts
-var registry = /* @__PURE__ */ new Map();
-function key(type, fromVersion) {
-  return `${type}:${fromVersion}`;
-}
-function registerUpcaster(type, fromVersion, fn) {
-  registry.set(key(type, fromVersion), fn);
-}
-var UpcastError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UpcastError";
-  }
-};
-function upcastPayload(type, fromVersion, payload) {
-  let v = fromVersion;
-  let p = payload;
-  if (v > SCHEMA_VERSION) {
-    throw new UpcastError(`event "${type}" is schema v${v}, newer than supported v${SCHEMA_VERSION}; halting`);
-  }
-  while (v < SCHEMA_VERSION) {
-    const fn = registry.get(key(type, v));
-    if (!fn) throw new UpcastError(`no upcaster for "${type}" v${v}\u2192v${v + 1}`);
-    p = fn(p);
-    v += 1;
-  }
-  return { payload: p, schema_version: SCHEMA_VERSION };
-}
-function upcastEnvelope(raw) {
-  const { payload, schema_version } = upcastPayload(raw.type, raw.schema_version, raw.payload);
-  return { ...raw, payload, schema_version };
-}
-registerUpcaster("TaskCreated", 0, (p) => ({ task_id: p.id, slug: p.name }));
-
-// src/protocol/workspace-commands.ts
-var INVITATION_MAX_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
-var AGENT_TOKEN_DEFAULT_TTL_MS = 60 * 60 * 1e3;
-var AGENT_TOKEN_MAX_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
-var RENEWAL_HORIZON_DEFAULT_MS = 30 * 24 * 60 * 60 * 1e3;
-var RENEWAL_HORIZON_MAX_MS = 90 * 24 * 60 * 60 * 1e3;
-
-// src/protocol/brain-version-window.ts
-var BRAIN_FILE_PREFIX = "brain--";
-var BRAIN_FILE_SUFFIX = ".md";
-var BRAIN_TOPIC_MAX_LENGTH = 255 - BRAIN_FILE_PREFIX.length - BRAIN_FILE_SUFFIX.length;
-
-// src/cloud/command-client.ts
 var AGENT_TOKEN_RE = /^swm_agt_[A-Za-z0-9_-]{43}$/;
 var INVITATION_TOKEN_RE = /^swm_inv_[A-Za-z0-9_-]{43}$/;
 var CAPABILITY_TOKEN_RE = /^swm_cap_[A-Za-z0-9_-]{43}$/;
@@ -22978,13 +22977,18 @@ async function sendFileCommand(options, command2) {
   return body;
 }
 function fileVersionCreate(options, input) {
+  const ifVersion = input.ifVersion ?? null;
   return sendFileCommand(options, {
     kind: "file_version_create",
     file_id: input.fileId,
     version_id: input.versionId,
     name: input.name,
     declared_size_bytes: input.declaredSizeBytes,
-    content_type: input.contentType
+    content_type: input.contentType,
+    /* The server validates an exact key set, so the key is sent only when a
+     * precondition was asked for. An unconditional write is byte-identical to
+     * what every earlier client sent. */
+    ...ifVersion === null ? {} : { if_version: ifVersion }
   });
 }
 function fileVersionCommit(options, input) {
@@ -26624,6 +26628,138 @@ function parseAgentCredentialInput(value, source) {
 
 // src/cloud/renewal.ts
 var import_node_crypto9 = require("node:crypto");
+
+// src/cloud/renewal-grants.ts
+var UUID_RE5 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function nullableString(value, field) {
+  if (value === null) return null;
+  if (typeof value !== "string") {
+    throw new Error(`renewal grant read returned malformed ${field}`);
+  }
+  return value;
+}
+function nullableTimestamp(value, field) {
+  const text = nullableString(value, field);
+  if (text !== null && !Number.isFinite(Date.parse(text))) {
+    throw new Error(`renewal grant read returned malformed ${field}`);
+  }
+  return text;
+}
+function uuid2(value, field) {
+  if (typeof value !== "string" || !UUID_RE5.test(value)) {
+    throw new Error(`renewal grant read returned malformed ${field}`);
+  }
+  return value.toLowerCase();
+}
+function nullableUuid(value, field) {
+  return value === null ? null : uuid2(value, field);
+}
+function parseGrant(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("renewal grant read returned a malformed row");
+  }
+  const row = value;
+  if (row.kind !== "timeboxed" && row.kind !== "standing") {
+    throw new Error("renewal grant read returned malformed kind");
+  }
+  const horizon = nullableTimestamp(
+    row.horizon_expires_at,
+    "horizon_expires_at"
+  );
+  if (row.kind === "standing" && horizon !== null || row.kind === "timeboxed" && horizon === null) {
+    throw new Error("renewal grant read returned an invalid kind/horizon pair");
+  }
+  return {
+    renewal_grant_id: uuid2(row.renewal_grant_id, "renewal_grant_id"),
+    principal_id: uuid2(row.principal_id, "principal_id"),
+    kind: row.kind,
+    horizon_expires_at: horizon,
+    bound_device_id: nullableUuid(row.bound_device_id, "bound_device_id"),
+    last_used_at: nullableTimestamp(row.last_used_at, "last_used_at"),
+    last_used_device_id: nullableUuid(
+      row.last_used_device_id,
+      "last_used_device_id"
+    ),
+    last_used_from: nullableString(row.last_used_from, "last_used_from"),
+    new_host_at: nullableTimestamp(row.new_host_at, "new_host_at"),
+    suspended_at: nullableTimestamp(row.suspended_at, "suspended_at"),
+    revoked_at: nullableTimestamp(row.revoked_at, "revoked_at"),
+    token_id: nullableUuid(row.token_id, "token_id"),
+    issued_at: nullableTimestamp(row.issued_at, "issued_at"),
+    token_expires_at: nullableTimestamp(
+      row.token_expires_at,
+      "token_expires_at"
+    ),
+    token_revoked_at: nullableTimestamp(
+      row.token_revoked_at,
+      "token_revoked_at"
+    )
+  };
+}
+async function readRenewalGrants(target2, credential, workspaceId2, fetcher = fetch) {
+  const response = await fetcher(readEndpoint(target2), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${credential}`,
+      apikey: target2.anonKey,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      resource: "renewal_grants",
+      workspace_id: workspaceId2
+    }),
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!response.ok) {
+    throw new Error(`renewal grant read failed (HTTP ${response.status})`);
+  }
+  const body = await response.json().catch(() => null);
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error("renewal grant read returned malformed JSON");
+  }
+  const grants = body.grants;
+  if (!Array.isArray(grants)) {
+    throw new Error("renewal grant read returned no grants array");
+  }
+  return grants.map(parseGrant);
+}
+var STANDING_IDLE_PAUSE_DAYS = 14;
+var STANDING_RESUME_ACTORS = [
+  "a workspace owner",
+  "an admin",
+  "the member who added the agent"
+];
+function orList(items) {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0];
+  return `${items.slice(0, -1).join(", ")}, or ${items[items.length - 1]}`;
+}
+var STANDING_RESUME_ACTORS_SENTENCE = orList(STANDING_RESUME_ACTORS);
+var STANDING_GRANT_RULES = [
+  "Access does not expire.",
+  `${STANDING_IDLE_PAUSE_DAYS} days with no use pauses it; ${STANDING_RESUME_ACTORS_SENTENCE} can resume it.`,
+  "Revoking it is the only permanent stop."
+];
+function standingPausedRenewalMessage(idle) {
+  const cause = idle ? `This standing grant went ${STANDING_IDLE_PAUSE_DAYS} days with no use, so CommonSwarm paused it and refused renewal.` : "This renewal grant is paused, so CommonSwarm refused renewal.";
+  return `${cause} It is not revoked and this agent is not gone. Next step: ${STANDING_RESUME_ACTORS_SENTENCE} runs cswarm grant resume, then this agent continues.`;
+}
+function describeRenewalGrant(grant) {
+  const lines = grant.kind === "standing" ? [`Grant: standing \u2014 ${STANDING_GRANT_RULES.join(" ")}`] : [`Grant: timeboxed \u2014 renewal horizon ${grant.horizon_expires_at}.`];
+  if (grant.suspended_at !== null) {
+    lines.push(
+      `PAUSED since ${grant.suspended_at} after ${STANDING_IDLE_PAUSE_DAYS} days with no use. This is not revoked and the agent is not gone. Next step: ${orList(STANDING_RESUME_ACTORS)} runs cswarm grant resume --renewal-grant-id ${grant.renewal_grant_id}`
+    );
+  }
+  if (grant.revoked_at !== null) {
+    lines.push(
+      `REVOKED since ${grant.revoked_at}. This is permanent and cannot be resumed. Next step: mint a new grant if this agent should continue.`
+    );
+  }
+  return lines;
+}
+
+// src/cloud/renewal.ts
 var AGENT_TOKEN_DEFAULT_TTL_MS2 = 60 * 60 * 1e3;
 var AGENT_TOKEN_MAX_TTL_MS2 = 8 * 60 * 60 * 1e3;
 var RENEWAL_HORIZON_DEFAULT_MS2 = 30 * 24 * 60 * 60 * 1e3;
@@ -26633,7 +26769,8 @@ function describeMintRenewal(hasExpiry, horizonDays, kind = "timeboxed") {
     return "This credential does not renew itself; re-issue one by hand when it expires.\n";
   }
   if (kind === "standing") {
-    return "Standing grant created. This does not expire. Revoke is the only kill switch. The bearer credential still rotates before expiry while a cswarm process remains running and secure local state is available.\n";
+    return `Standing grant created. ${STANDING_GRANT_RULES.join(" ")} The bearer credential still rotates before expiry while a cswarm process remains running and secure local state is available.
+`;
   }
   const days = Number.isFinite(horizonDays) && horizonDays > 0 ? Math.round(horizonDays) : Math.round(RENEWAL_HORIZON_DEFAULT_MS2 / 864e5);
   return `While a cswarm process remains running and secure local state is available, this credential rotates before expiry. A person is asked to authorise it again in ${days} days. A stopped or idle CLI cannot renew it.
@@ -26644,7 +26781,7 @@ var RENEWAL_LEAD_FLOOR_MS = 5 * 6e4;
 var RENEWAL_LEAD_CEILING_MS = 15 * 6e4;
 var RENEWAL_PENDING_RECOVERY_MS = 60 * 6e4;
 var RENEW_TIMEOUT_MS = 3e4;
-var UUID_RE5 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var UUID_RE6 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var AGENT_TOKEN_RE4 = /^swm_agt_[A-Za-z0-9_-]{43}$/;
 function renewalDueAt(issuedAt, expiresAt) {
   const lifetime = Math.max(0, expiresAt - issuedAt);
@@ -26803,7 +26940,7 @@ async function requestSuccessor(options) {
   } catch {
     body = {};
   }
-  const principalId = typeof body.principal_id === "string" && UUID_RE5.test(body.principal_id) ? body.principal_id.toLowerCase() : null;
+  const principalId = typeof body.principal_id === "string" && UUID_RE6.test(body.principal_id) ? body.principal_id.toLowerCase() : null;
   if (response.status === 400 || response.status === 404) {
     throw new RenewalUnsupported(
       "this deployment does not offer credential renewal yet, so a credential here still has to be re-issued by hand when it expires"
@@ -26838,7 +26975,7 @@ async function requestSuccessor(options) {
     if (reason === "renewal_idle_suspended" || reason === "renewal_grant_suspended") {
       throw new RenewalSuspended(
         reason,
-        reason === "renewal_idle_suspended" ? "This standing grant was idle for more than 14 days, so CommonSwarm suspended it and refused renewal. Ask a workspace owner to revoke this grant and mint a new credential before this agent continues." : "This renewal grant is suspended, so CommonSwarm refused renewal. Ask a workspace owner to revoke this grant and mint a new credential before this agent continues."
+        standingPausedRenewalMessage(reason === "renewal_idle_suspended")
       );
     }
     if (reason === "renewal_horizon_reached") {
@@ -26900,7 +27037,7 @@ async function requestSuccessor(options) {
   }
   const tokenId = typeof body.token_id === "string" ? body.token_id : "";
   const runId = typeof body.run_id === "string" ? body.run_id : "";
-  if (!UUID_RE5.test(tokenId) || !UUID_RE5.test(runId) || principalId === null) {
+  if (!UUID_RE6.test(tokenId) || !UUID_RE6.test(runId) || principalId === null) {
     throw new RenewalRefused(
       response.status,
       "incomplete_successor",
@@ -27409,7 +27546,7 @@ var MAX_LINK_PAYLOAD_BYTES = 8 * 1024;
 var MAX_LABEL_INPUT_LENGTH = 1024;
 var CONTROL_GLOBAL_RE = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g;
 var ANSI_ESCAPE_GLOBAL_RE = /\u001b\[[0-?]*[ -/]*[@-~]/g;
-var UUID_RE6 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var UUID_RE7 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var STRICT_BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
 var RAW_BASE64_PAYLOAD_CANDIDATE_RE = /^[A-Za-z0-9+/_=-]+$/;
 var CURRENT_INVITE_SCHEME = "cswarm://accept/";
@@ -27460,7 +27597,7 @@ function validatedPayload(value) {
     throw new Error("invite link target is malformed");
   }
   cloudTarget(value.url, value.anon_key);
-  if (typeof value.workspace_id !== "string" || !UUID_RE6.test(value.workspace_id)) {
+  if (typeof value.workspace_id !== "string" || !UUID_RE7.test(value.workspace_id)) {
     throw new Error("invite link workspace_id must be a UUID");
   }
   if (typeof value.invitation_token !== "string") {
@@ -27470,7 +27607,7 @@ function validatedPayload(value) {
   if (typeof value.workspace_name !== "string" || typeof value.inviter_display_name !== "string" || value.workspace_name.length > MAX_LABEL_INPUT_LENGTH || value.inviter_display_name.length > MAX_LABEL_INPUT_LENGTH) {
     throw new Error("invite link display labels are malformed");
   }
-  if (value.inviter_user_id !== void 0 && (typeof value.inviter_user_id !== "string" || !UUID_RE6.test(value.inviter_user_id))) {
+  if (value.inviter_user_id !== void 0 && (typeof value.inviter_user_id !== "string" || !UUID_RE7.test(value.inviter_user_id))) {
     throw new Error("invite link inviter_user_id must be a UUID");
   }
   return value;
@@ -27670,7 +27807,7 @@ function acceptedResponse(result) {
   }
   return result.response;
 }
-function uuid2(value, field) {
+function uuid3(value, field) {
   if (typeof value !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
     throw new Error(`server returned a malformed ${field}`);
   }
@@ -28014,7 +28151,7 @@ function cloudAcceptOperations(target2, store2, fetcher = fetch) {
         );
         return {
           status: "accepted",
-          workspaceId: uuid2(response.workspace_id, "workspace_id")
+          workspaceId: uuid3(response.workspace_id, "workspace_id")
         };
       } catch (error) {
         if (error instanceof CommandHttpError && error.status === 403) {
@@ -28033,7 +28170,7 @@ function cloudAcceptOperations(target2, store2, fetcher = fetch) {
       if (result.response.status === "accepted") {
         return {
           status: "accepted",
-          principalId: uuid2(result.response.principal_id, "principal_id")
+          principalId: uuid3(result.response.principal_id, "principal_id")
         };
       }
       if (String(result.response.reason) === "principal_name_taken") {
@@ -28127,113 +28264,6 @@ function renderCapabilityRevoke(capabilityId, revokedAt) {
   return `Capability link ${capabilityId} was revoked at ${revokedAt}. Anyone who still holds it now gets the same answer as someone holding a link that never existed. Links you have not revoked are unaffected.`;
 }
 
-// src/cloud/renewal-grants.ts
-var UUID_RE7 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-function nullableString(value, field) {
-  if (value === null) return null;
-  if (typeof value !== "string") {
-    throw new Error(`renewal grant read returned malformed ${field}`);
-  }
-  return value;
-}
-function nullableTimestamp(value, field) {
-  const text = nullableString(value, field);
-  if (text !== null && !Number.isFinite(Date.parse(text))) {
-    throw new Error(`renewal grant read returned malformed ${field}`);
-  }
-  return text;
-}
-function uuid3(value, field) {
-  if (typeof value !== "string" || !UUID_RE7.test(value)) {
-    throw new Error(`renewal grant read returned malformed ${field}`);
-  }
-  return value.toLowerCase();
-}
-function nullableUuid(value, field) {
-  return value === null ? null : uuid3(value, field);
-}
-function parseGrant(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("renewal grant read returned a malformed row");
-  }
-  const row = value;
-  if (row.kind !== "timeboxed" && row.kind !== "standing") {
-    throw new Error("renewal grant read returned malformed kind");
-  }
-  const horizon = nullableTimestamp(
-    row.horizon_expires_at,
-    "horizon_expires_at"
-  );
-  if (row.kind === "standing" && horizon !== null || row.kind === "timeboxed" && horizon === null) {
-    throw new Error("renewal grant read returned an invalid kind/horizon pair");
-  }
-  return {
-    renewal_grant_id: uuid3(row.renewal_grant_id, "renewal_grant_id"),
-    principal_id: uuid3(row.principal_id, "principal_id"),
-    kind: row.kind,
-    horizon_expires_at: horizon,
-    bound_device_id: nullableUuid(row.bound_device_id, "bound_device_id"),
-    last_used_at: nullableTimestamp(row.last_used_at, "last_used_at"),
-    last_used_device_id: nullableUuid(
-      row.last_used_device_id,
-      "last_used_device_id"
-    ),
-    last_used_from: nullableString(row.last_used_from, "last_used_from"),
-    new_host_at: nullableTimestamp(row.new_host_at, "new_host_at"),
-    suspended_at: nullableTimestamp(row.suspended_at, "suspended_at"),
-    revoked_at: nullableTimestamp(row.revoked_at, "revoked_at"),
-    token_id: nullableUuid(row.token_id, "token_id"),
-    issued_at: nullableTimestamp(row.issued_at, "issued_at"),
-    token_expires_at: nullableTimestamp(
-      row.token_expires_at,
-      "token_expires_at"
-    ),
-    token_revoked_at: nullableTimestamp(
-      row.token_revoked_at,
-      "token_revoked_at"
-    )
-  };
-}
-async function readRenewalGrants(target2, credential, workspaceId2, fetcher = fetch) {
-  const response = await fetcher(readEndpoint(target2), {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${credential}`,
-      apikey: target2.anonKey,
-      "content-type": "application/json"
-    },
-    body: JSON.stringify({
-      resource: "renewal_grants",
-      workspace_id: workspaceId2
-    }),
-    signal: AbortSignal.timeout(15e3)
-  });
-  if (!response.ok) {
-    throw new Error(`renewal grant read failed (HTTP ${response.status})`);
-  }
-  const body = await response.json().catch(() => null);
-  if (!body || typeof body !== "object" || Array.isArray(body)) {
-    throw new Error("renewal grant read returned malformed JSON");
-  }
-  const grants = body.grants;
-  if (!Array.isArray(grants)) {
-    throw new Error("renewal grant read returned no grants array");
-  }
-  return grants.map(parseGrant);
-}
-function describeRenewalGrant(grant) {
-  const lines = grant.kind === "standing" ? ["Grant: standing \u2014 does not expire; revoke is the only kill switch."] : [`Grant: timeboxed \u2014 renewal horizon ${grant.horizon_expires_at}.`];
-  if (grant.suspended_at !== null) {
-    lines.push(
-      `SUSPENDED since ${grant.suspended_at}. Next step: ask a workspace owner to revoke this grant and mint a new credential.`
-    );
-  }
-  if (grant.revoked_at !== null) {
-    lines.push(`REVOKED since ${grant.revoked_at}. Next step: mint a new grant if this agent should continue.`);
-  }
-  return lines;
-}
-
 // src/cloud/workspaces.ts
 var UUID_RE8 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var ROLES = /* @__PURE__ */ new Set(["owner", "admin", "member"]);
@@ -31102,7 +31132,7 @@ var DELIVERY_HANDLED_OUTCOMES = new Set(
 var DELIVERY_PROVIDER_PROVEN_OUTCOMES = new Set(
   [...DELIVERY_ACK_OUTCOMES].filter((outcome) => outcome === "replied")
 );
-function orList(values2) {
+function orList2(values2) {
   return values2.length <= 1 ? values2.join("") : `${values2.slice(0, -1).join(", ")}, or ${values2[values2.length - 1]}`;
 }
 var DELIVERY_REQUEST_TIMEOUT_MS = 3e4;
@@ -31448,13 +31478,13 @@ function assertAckRequest(request) {
   checkedUuidRequest(request.listenerInstanceId, "listenerInstanceId");
   if (!DELIVERY_ACK_OUTCOMES.has(request.outcome)) {
     throw new Error(
-      `a delivery outcome must be ${orList([...DELIVERY_ACK_OUTCOMES])}`
+      `a delivery outcome must be ${orList2([...DELIVERY_ACK_OUTCOMES])}`
     );
   }
   if (request.outcome === "failed_terminal") {
     if (typeof request.lastErrorCode !== "string" || !FAILED_TERMINAL_CODES_SET.has(request.lastErrorCode)) {
       throw new Error(
-        `a failed_terminal acknowledgement requires one of ${orList([...FAILED_TERMINAL_CODES_SET])}`
+        `a failed_terminal acknowledgement requires one of ${orList2([...FAILED_TERMINAL_CODES_SET])}`
       );
     }
   } else if (request.lastErrorCode !== null) {
@@ -41622,6 +41652,23 @@ var ListenerHttpClient = class {
 
 // src/resume.ts
 var import_node_child_process8 = require("node:child_process");
+var DEFAULT_PROCESS_TABLE_COMMAND = {
+  file: "ps",
+  args: ["-axo", "pid=,command="]
+};
+var ProcessTableError = class extends Error {
+  constructor(command2, detail) {
+    super(
+      `could not read the host process table with ${command2.file}: ${detail}`
+    );
+    this.command = command2;
+    this.detail = detail;
+    this.name = "ProcessTableError";
+  }
+  command;
+  detail;
+  code = "process_table_unavailable";
+};
 function execFileText(file, args) {
   return new Promise((resolve3, reject) => {
     (0, import_node_child_process8.execFile)(file, [...args], {
@@ -41633,15 +41680,76 @@ function execFileText(file, args) {
     });
   });
 }
-function systemProcessTable() {
+function parseProcessRow(line) {
+  const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  return { pid, command: match[2] };
+}
+var PROCESS_TABLE_STDERR_MAX_CHARS = 2e3;
+function systemProcessTable(options = {}) {
+  const command2 = options.command ?? DEFAULT_PROCESS_TABLE_COMMAND;
+  const retain = options.retain ?? (() => true);
   return {
-    async list() {
-      const output = await execFileText("ps", ["-axo", "pid=,command="]);
-      return output.split("\n").flatMap((line) => {
-        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
-        if (!match) return [];
-        const pid = Number(match[1]);
-        return Number.isSafeInteger(pid) && pid > 0 ? [{ pid, command: match[2] }] : [];
+    list() {
+      return new Promise((resolve3, reject) => {
+        const child = (0, import_node_child_process8.spawn)(command2.file, [...command2.args], {
+          stdio: ["ignore", "pipe", "pipe"]
+        });
+        const rows3 = [];
+        let pending = "";
+        let stderr = "";
+        let settled = false;
+        const fail = (detail) => {
+          if (settled) return;
+          settled = true;
+          child.stdout.destroy();
+          reject(new ProcessTableError(command2, detail));
+        };
+        const take = (line) => {
+          const row = parseProcessRow(line);
+          if (row === null) return true;
+          try {
+            if (retain(row.command)) rows3.push(row);
+          } catch {
+            fail("its row filter threw");
+            return false;
+          }
+          return true;
+        };
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+          if (settled) return;
+          const lines = (pending + chunk).split("\n");
+          pending = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!take(line)) return;
+          }
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+          const room = PROCESS_TABLE_STDERR_MAX_CHARS - stderr.length;
+          if (room > 0) stderr += chunk.slice(0, room);
+        });
+        child.stdout.on("error", () => fail("its output stream failed"));
+        child.stderr.on("error", () => fail("its error stream failed"));
+        child.on("error", (error) => fail(error.name));
+        child.on("close", (code, signal) => {
+          if (settled) return;
+          if (pending.length > 0 && !take(pending)) return;
+          if (signal !== null) {
+            fail(`it was stopped by ${signal}`);
+            return;
+          }
+          if (code !== 0) {
+            const trailer = stderr.trim().length > 0 ? `: ${stderr.trim().slice(0, PROCESS_TABLE_STDERR_MAX_CHARS)}` : "";
+            fail(`it exited ${code}${trailer}`);
+            return;
+          }
+          settled = true;
+          resolve3(rows3);
+        });
       });
     }
   };
@@ -41691,7 +41799,10 @@ function isNotifyCommand(command2) {
   return /(?:^|\s)inbox(?:\s|$)/.test(command2) && /(?:^|\s)--notify(?:\s|$)/.test(command2);
 }
 async function findNotifyWatchers(options) {
-  const processTable = options.processTable ?? systemProcessTable();
+  const processTable = options.processTable ?? systemProcessTable({
+    retain: isNotifyCommand,
+    ...options.processTableCommand ? { command: options.processTableCommand } : {}
+  });
   const stdoutConsumer = options.stdoutConsumer ?? lsofStdoutConsumer();
   const rows3 = await processTable.list();
   const matches = rows3.flatMap((row) => {
@@ -41959,6 +42070,7 @@ var KNOWN_FLAGS = /* @__PURE__ */ new Set([
   "grok-executable",
   "head-sha",
   "help",
+  "if-version",
   "include-stale",
   "include-tombstoned",
   "invitation-id",
@@ -41978,6 +42090,7 @@ var KNOWN_FLAGS = /* @__PURE__ */ new Set([
   "permissions",
   "principal-id",
   "provider",
+  "renewal-grant-id",
   "repo",
   "reveal-anon-key",
   "route",
@@ -42029,8 +42142,8 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
 ]);
 var UUID_RE23 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function packageVersion() {
-  if ("0.1.51".length > 0) {
-    return "0.1.51";
+  if ("0.1.53".length > 0) {
+    return "0.1.53";
   }
   try {
     const value = JSON.parse(
@@ -42165,7 +42278,7 @@ Usage:
   cswarm file restore <name|file-id> [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--json]
   cswarm brain ls [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--json]
   cswarm brain get <topic>[@<version>] [--version <n>] [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--json]
-  cswarm brain put <topic> [<markdown-path>] [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--json]  # without a path, reads Markdown from stdin
+  cswarm brain put <topic> [<markdown-path>] [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--if-version <n>] [--json]  # without a path, reads Markdown from stdin; --if-version refuses the write unless the live version is still <n>
   cswarm feedback "<text>" --kind bug|idea|friction [--about <ref>] [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [--json]
   cswarm listen start ${requiredAgentCredential} [--url <url> --anon-key <key>] --workspace-id <uuid> --provider grok|opencode|claude|codex [--cwd <absolute-path>] [--model <model>] [--effort <level>] [--permissions deny|allow] [--grok-executable <path>] [--opencode-executable <path>] [--claude-executable <path>] [--codex-executable <path>] [--turn-budget <duration>] [--route worker|main|split] [--defer-over <chars>] [--allow-unattended] [--foreground] [--json]
   cswarm listen canary ${requiredAgentCredential} [--url <url> --anon-key <key>] --workspace-id <uuid> [--state-dir <path>] [--wait <seconds>] [--json]
@@ -42191,6 +42304,7 @@ Usage:
   cswarm token mint [--url <url> --anon-key <key>] [--workspace-id <uuid>] --principal-id <uuid> --run-id <uuid> --task-id <uuid> --epoch <n> [--ttl-ms <ms>] [--renewal-horizon-days <1..90> | --standing --confirm-standing]
   cswarm token revoke [--url <url> --anon-key <key>] [--workspace-id <uuid>] --token-id <uuid>
   cswarm token revoke ${requiredAgentCredential} [--url <url> --anon-key <key>] --workspace-id <uuid> [--token-id <uuid>]
+  cswarm grant resume [--url <url> --anon-key <key>] [--workspace-id <uuid>] --renewal-grant-id <uuid> [--json]  # lifts an idle pause; a REVOKED grant is refused
   cswarm link new [--url <url> --anon-key <key>] [--workspace-id <uuid>] --task-id <uuid> [--ttl-ms <ms>] [--site <origin>] [--json]
   cswarm link revoke [--url <url> --anon-key <key>] [--workspace-id <uuid>] --capability-id <uuid> [--json]
   cswarm command <kind> [--url <url> --anon-key <key>] [--workspace-id <uuid>] ${agentCredential2} [command fields]
@@ -43333,6 +43447,43 @@ async function runToken(args) {
     expiresAt
   }));
 }
+async function runGrant(args) {
+  const action = args.positionals[1];
+  args.assertShape(
+    [
+      ...TARGET_FLAGS,
+      "workspace-id",
+      "renewal-grant-id",
+      /* `--json` accepted, no effect — see the note on `runInvite`. D-064. */
+      "json"
+    ],
+    2
+  );
+  if (action !== "resume") {
+    throw new UsageError(`unknown grant command: ${action ?? "(missing)"}`);
+  }
+  const renewalGrantId = args.required("renewal-grant-id");
+  const cloud = await target(args);
+  const human = await humanCredential(args, cloud);
+  const workspace = await workspaceId(args, cloud, human);
+  const response = acceptedConnect(
+    "grant resume",
+    await sendConnectWithPending(
+      new ThinCommandClient(cloud),
+      human,
+      workspace,
+      { kind: "resume_renewal_grant", renewal_grant_id: renewalGrantId }
+    )
+  );
+  const resumedAt = response.resumed_at ?? null;
+  process.stdout.write(
+    `Grant resumed${resumedAt === null ? "" : ` at ${resumedAt}`}.
+Renewal is allowed again. Nothing has reached the agent yet: it starts renewing when its own cswarm process next tries, so start that process if it is not running.
+The idle clock restarts now \u2014 another ${STANDING_IDLE_PAUSE_DAYS} days with no use pauses it again.
+Confirm with: cswarm whoami --agent-token-file <path>
+`
+  );
+}
 async function runTokenRevoke(args) {
   if (hasAgentCredential(args)) {
     args.assertShape(
@@ -46731,7 +46882,7 @@ async function resolveFileSelector(context, selector) {
   }
   return match.file_id;
 }
-async function uploadNamedFile(context, name, bytes) {
+async function uploadNamedFile(context, name, bytes, options = {}) {
   if (bytes.byteLength > FILE_MAX_VERSION_BYTES) {
     throw new Error(
       `this file is ${formatFileSize(bytes.byteLength)}; the per-file limit is ${formatFileSize(FILE_MAX_VERSION_BYTES)}, so the upload was not started`
@@ -46758,7 +46909,8 @@ async function uploadNamedFile(context, name, bytes) {
       versionId,
       name,
       declaredSizeBytes: bytes.byteLength,
-      contentType
+      contentType,
+      ...options.ifVersion === void 0 ? {} : { ifVersion: options.ifVersion }
     })
   );
   await onceRetried(
@@ -47052,7 +47204,8 @@ async function runBrainPut(args) {
       "cswarm brain put cannot read both the credential and Markdown from stdin; use --agent-token-file or pass a Markdown path"
     );
   }
-  const context = await fileContext(args, [], args.positionals.length);
+  const context = await fileContext(args, ["if-version"], args.positionals.length);
+  const ifVersion = args.optional("if-version") === void 0 ? void 0 : integer2(args, "if-version", { minimum: 0 });
   let bytes;
   if (localPath) {
     try {
@@ -47067,7 +47220,19 @@ async function runBrainPut(args) {
     bytes = await readBrainMarkdownFromStdin();
   }
   decodeBrainMarkdown(bytes);
-  const committed = await uploadNamedFile(context, brainFileName(topic), bytes);
+  const committed = await uploadNamedFile(
+    context,
+    brainFileName(topic),
+    bytes,
+    ifVersion === void 0 ? {} : { ifVersion }
+  ).catch((error) => {
+    if (error instanceof FileCommandRefused && error.code === FILE_VERSION_PRECONDITION_FAILED) {
+      throw new Error(
+        `${error.message}. Someone saved a new version after you read this topic. Re-read it, apply your change to that copy, then put it again: cswarm brain get ${topic}`
+      );
+    }
+    throw error;
+  });
   if (args.has("json")) {
     process.stdout.write(`${JSON.stringify({ topic, ...committed }, null, 2)}
 `);
@@ -47463,6 +47628,10 @@ async function main() {
     await runToken(args);
     return;
   }
+  if (verb === "grant") {
+    await runGrant(args);
+    return;
+  }
   if (verb === "link") {
     await runLink(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commonswarm",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "CommonSwarm CLI — coordination for teams where people and AI agents work side by side.",
   "bin": {
     "cswarm": "cswarm.cjs"