@tonbo/cli 0.8.0 → 0.10.0

package/dist/bin/tonbo.js

@@ -202,6 +202,7 @@ var agentNameContract = {
           "artifacts",
           "auth",
           "inference",
+          "lb-check",
           "network-health",
           "sandbox-control",
           "status",
@@ -221,6 +222,7 @@ var agentNameContract = {
           "artifacts.tonbo.sh",
           "auth.tonbo.sh",
           "inference.tonbo.sh",
+          "lb-check.tonbo.sh",
           "network-health.tonbo.sh",
           "sandbox-control.tonbo.sh",
           "status.tonbo.sh",
@@ -621,6 +623,19 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo machine sleep"
   },
+  "listMachineActivations": {
+    "method": "GET",
+    "path": "/machines/{name}/activations",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo machine activations"
+  },
   "listMachineShapes": {
     "method": "GET",
     "path": "/machine-shapes",
@@ -709,7 +724,7 @@ var apiKeyExpirations = [
 ];
 var credentialsContract = {
   "version": 1,
-  "description": "The login `tonbo login` (and `yield login`) saves: a personal key of one account. @tonbo/cli-core writes and reads it; other readers, such as @tonbo/sqlite-ursula/tonbo, follow `reader`.",
+  "description": "The login `tonbo login` (and `yield login`) saves: a personal key of one account at the top level, the login made last, and, beside it, every account's login of this device in `accounts` with the device's `login_secret` (ADR-0016, \"Credentials\", PR 4b-ii). @tonbo/cli-core writes and reads it; the Tonbo SDK (@tonbo/sdk and tonbo-sdk, contracts/sdk/v1.json) reads it as its last key source, and every other reader follows `reader` and reads the top level alone.",
   "path": {
     "description": "`${XDG_CONFIG_HOME}/tonbo/credentials.json` when XDG_CONFIG_HOME is set and not empty, else `${HOME}/.config/tonbo/credentials.json`.",
     "base_env": "XDG_CONFIG_HOME",
@@ -747,6 +762,13 @@ var credentialsContract = {
     "expired": "A login whose `expires_at` is at or before now is expired: ask the person to run `tonbo login`. `expires_at: null` never expires.",
     "login_hint": "tonbo login"
   },
+  "accounts": {
+    "description": "One CLI login key per account (ADR-0016 R7 (a)): a daemon that publishes into an organization holds that organization's key beside the personal account's, since a key reaches only its own account. The fields are additive and optional, so a version 1 reader that knows only the top level keeps working, and the format stays version 1.",
+    "top_level": "The login made last, by `tonbo login` or `yield login`: the account `tonbo` acts in. A login made only to publish into an organization (`yield connect --account`) is added to `accounts` and leaves the top level alone.",
+    "entries": "`accounts` maps an account id to that account's login on this device, the top level's account included. `kind` and `name` are the redemption's answer; a file written before them, or by a server that does not answer them, has the top level alone, whose kind a client asks the API for.",
+    "personal": "The entry whose kind is `user` is the person's personal account's login: it alone captures raw sessions and registers the device (ADR-0016 W-10, W-14).",
+    "login_secret": "One random per-device secret, 32 bytes base64url, made at the first login and kept: it is sent only in the redeem POST, beside the PKCE verifier, never in the /cli/login URL, and User Center keeps only the suffix it derives from it, in an organization key's name `Yield CLI \xB7 <8 hex>`. `tonbo` and `yield` share it through this file, and so share one key per account. A lost file sends a new secret and gets a new suffix; the old key stays until it is revoked or idles out."
+  },
   "current_version": 1,
   "schema": {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -787,6 +809,59 @@ var credentialsContract = {
         ],
         "format": "date-time",
         "description": "When the key expires, ISO 8601; null for a key that never expires."
+      },
+      "login_secret": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_-]{43}$",
+        "description": "This device's login secret (`accounts.login_secret`)."
+      },
+      "accounts": {
+        "type": "object",
+        "description": "Every account's login of this device, keyed by the account id (`accounts.entries`).",
+        "additionalProperties": {
+          "type": "object",
+          "required": [
+            "key_id",
+            "key",
+            "expires_at"
+          ],
+          "properties": {
+            "key_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The key's id."
+            },
+            "key": {
+              "type": "string",
+              "pattern": "^tbo_",
+              "description": "The personal key's secret."
+            },
+            "expires_at": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date-time",
+              "description": "When the key expires; null for never."
+            },
+            "kind": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^(user|organization)$",
+              "description": "The account's kind, `user` for the personal account; null when unknown."
+            },
+            "name": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "minLength": 1,
+              "description": "The account's name, which `--account` takes; null when unknown."
+            }
+          }
+        }
       }
     }
   },
@@ -805,6 +880,30 @@ var credentialsContract = {
         "key_id": "20000000-0000-4000-8000-000000000002",
         "key": "tbo_secret",
         "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null,
+        "login_secret": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        "accounts": {
+          "10000000-0000-4000-8000-000000000001": {
+            "key_id": "20000000-0000-4000-8000-000000000002",
+            "key": "tbo_secret",
+            "expires_at": null,
+            "kind": "user",
+            "name": "sam"
+          },
+          "10000000-0000-4000-8000-0000000000a1": {
+            "key_id": "20000000-0000-4000-8000-0000000000a2",
+            "key": "tbo_org",
+            "expires_at": "2027-04-24T00:00:00.000Z",
+            "kind": "organization",
+            "name": "acme"
+          }
+        }
       }
     ],
     "unusable": [
@@ -846,6 +945,51 @@ var credentialsContract = {
         "account_id": "10000000-0000-4000-8000-000000000001",
         "key_id": "20000000-0000-4000-8000-000000000002",
         "key": "tbo_secret"
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null,
+        "accounts": {
+          "10000000-0000-4000-8000-0000000000a1": {
+            "key_id": "k",
+            "key": "not-a-personal-key",
+            "expires_at": null
+          }
+        }
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null,
+        "accounts": {
+          "10000000-0000-4000-8000-0000000000a1": {
+            "key_id": "k",
+            "key": "tbo_org",
+            "expires_at": null,
+            "kind": "team"
+          }
+        }
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null,
+        "accounts": []
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null,
+        "login_secret": "in-a-url"
       }
     ]
   }
@@ -858,6 +1002,12 @@ var machinePortAccess = [
   "private",
   "public"
 ];
+var machineTimings = {
+  "pollAfterSeconds": 2,
+  "sleepPollAfterSeconds": 5,
+  "wakeHoldSeconds": 25,
+  "earlyReclaimSeconds": 120
+};
 
 // ../../packages/tonbo-cli-core/dist/src/credentials.js
 var DIRECTORY_MODE = Number.parseInt(credentialsContract.permissions.directory_mode, 8);
@@ -924,13 +1074,37 @@ var FileCredentialStore = class {
     await rm(this.filename, { force: true });
   }
 };
-var RULE_KEYWORDS = /* @__PURE__ */ new Set(["const", "type", "minLength", "pattern", "format", "description"]);
+var RULE_KEYWORDS = /* @__PURE__ */ new Set([
+  "const",
+  "type",
+  "minLength",
+  "pattern",
+  "format",
+  "description",
+  "additionalProperties"
+]);
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function matchesObject(value, rule) {
+  if (rule.type !== "object" || !isPlainObject(value))
+    return false;
+  if (!rule.required.every((name) => Object.hasOwn(value, name)))
+    return false;
+  return Object.entries(rule.properties).every(([name, inner]) => !Object.hasOwn(value, name) || matchesRule(value[name], inner));
+}
 function matchesRule(value, rule) {
   if (Object.keys(rule).some((keyword) => !RULE_KEYWORDS.has(keyword)))
     return false;
   if ("const" in rule)
     return value === rule.const;
   const types = typeof rule.type === "string" ? [rule.type] : rule.type ?? [];
+  if (types.includes("object")) {
+    if (!isPlainObject(value) || !rule.additionalProperties)
+      return false;
+    const entries = rule.additionalProperties;
+    return Object.entries(value).every(([key, entry]) => key.length > 0 && matchesObject(entry, entries));
+  }
   if (value === null)
     return types.includes("null");
   if (typeof value !== "string" || !types.includes("string"))
@@ -944,7 +1118,7 @@ function matchesRule(value, rule) {
   return true;
 }
 function isStoredLogin(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value))
+  if (!isPlainObject(value))
     return false;
   const login = value;
   const schema = credentialsContract.schema;
@@ -955,6 +1129,44 @@ function isStoredLogin(value) {
   const properties = schema.properties;
   return Object.entries(properties).every(([name, rule]) => !Object.hasOwn(login, name) || matchesRule(login[name], rule));
 }
+function accountLogins(login) {
+  const entries = Object.entries(login.accounts ?? {}).map(([account_id, entry]) => ({
+    ...entry,
+    account_id,
+    kind: entry.kind ?? null,
+    name: entry.name ?? null
+  }));
+  if (!entries.some((entry) => entry.account_id === login.account_id))
+    entries.unshift({
+      account_id: login.account_id,
+      key_id: login.key_id,
+      key: login.key,
+      expires_at: login.expires_at,
+      kind: null,
+      name: null
+    });
+  return entries;
+}
+function withAccountLogin(file, entry, options) {
+  const accounts = {};
+  if (file)
+    for (const known of accountLogins(file)) {
+      const { account_id: account_id2, ...rest2 } = known;
+      accounts[account_id2] = rest2;
+    }
+  const { account_id, ...rest } = entry;
+  accounts[account_id] = rest;
+  const top = options.current || !file ? entry : file;
+  return {
+    version: 1,
+    account_id: top.account_id,
+    key_id: top.key_id,
+    key: top.key,
+    expires_at: top.expires_at,
+    login_secret: options.loginSecret,
+    accounts
+  };
+}
 async function preparePrivateDirectory(directory) {
   const stat = await lstat(directory);
   if (stat.isSymbolicLink() || !stat.isDirectory())
@@ -984,6 +1196,9 @@ async function assertPrivateRegularFile(filename) {
 var exec = promisify(execFile);
 var DEFAULT_LOGIN_HINT = credentialsContract.reader.login_hint;
 var LOOPBACK_HOST = "127.0.0.1";
+function newLoginSecret() {
+  return randomBytes(32).toString("base64url");
+}
 function loginHostname(hostname = os2.hostname()) {
   const cleaned = hostname.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64);
   return cleaned || "computer";
@@ -1018,11 +1233,21 @@ var AuthClient = class {
   }
   /**
    * The browser handoff of /cli/login: PKCE S256 with a loopback redirect on
-   * a free port, then the one-time code is redeemed for a personal key named
-   * "CLI on <hostname>", which replaces that host's earlier login key.
+   * a free port, then the one-time code is redeemed, with this device's login
+   * secret, for the account's login key, which replaces this device's earlier
+   * login key there ("CLI on <hostname>" in a personal account, `Yield CLI ·
+   * <8 hex>` in any other). The key joins the file's `accounts`; it becomes
+   * the top level too unless `current` is false (a login made only to publish
+   * into an organization). Answers that account's login.
    */
   async login(progress = () => {
-  }, account) {
+  }, account, { current = true } = {}) {
+    const existing = await this.credentials.load().catch((error) => {
+      if (error instanceof UnusableLoginError)
+        return null;
+      throw error;
+    });
+    const loginSecret = existing?.login_secret ?? newLoginSecret();
     const verifier = randomBytes(48).toString("base64url");
     const challenge = createHash("sha256").update(verifier).digest("base64url");
     const state = randomBytes(24).toString("base64url");
@@ -1042,18 +1267,24 @@ var AuthClient = class {
     const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/token", this.loginOrigin).toString(), {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ code, code_verifier: verifier })
+      // The secret goes only here, in the POST body, never in the URL.
+      body: JSON.stringify({ code, code_verifier: verifier, login_secret: loginSecret })
     });
     progress({ status: "completed", step: "key-redemption" });
     const login = {
-      version: 1,
       account_id: redeemed.account_id,
       key_id: redeemed.api_key.id,
       key: redeemed.key,
-      expires_at: redeemed.api_key.expires_at
+      expires_at: redeemed.api_key.expires_at,
+      kind: redeemed.account_kind ?? null,
+      name: redeemed.account_name ?? null
     };
     progress({ status: "started", step: "credential-store" });
-    await this.credentials.save(login);
+    const latest = await this.credentials.load().catch(() => existing);
+    await this.credentials.save(withAccountLogin(latest, login, {
+      current,
+      loginSecret: latest?.login_secret ?? loginSecret
+    }));
     progress({ status: "completed", step: "credential-store" });
     return login;
   }
@@ -1185,10 +1416,12 @@ var ManagementApi = class {
   fetcher;
   apiOrigin;
   loginHint;
-  constructor(fetcher, apiOrigin2 = DEFAULT_API_ORIGIN, loginHint = DEFAULT_LOGIN_HINT) {
+  pause;
+  constructor(fetcher, apiOrigin2 = DEFAULT_API_ORIGIN, loginHint = DEFAULT_LOGIN_HINT, pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))) {
     this.fetcher = fetcher;
     this.apiOrigin = apiOrigin2;
     this.loginHint = loginHint;
+    this.pause = pause;
   }
   /** The answer's `data`. A refusal throws an HttpError naming the request id. */
   async call(operationId, key, request = {}) {
@@ -1356,47 +1589,140 @@ var ManagementApi = class {
   listMachines(key, page) {
     return this.page("listMachines", key, page);
   }
-  /** A replay with the same idempotency key returns the Machine the first
-   * request created. */
-  createMachine(key, request, idempotencyKey) {
-    return this.call("createMachine", key, {
-      body: withoutUndefined(request),
-      idempotencyKey
-    }).catch(unconfirmed("Machine creation", idempotencyKey, "the same arguments"));
+  /**
+   * A replay with the same idempotency key returns the Machine the first
+   * request created, so a transport failure or a 5xx answer is retried here
+   * with the same key, at most `CREATE_ATTEMPTS` times, after the answer's
+   * Retry-After (bounded) or a short backoff. A refusal is final; a create
+   * still unconfirmed after the last attempt names the key to retry with.
+   * The answer carries the Machine's `Location` and, while it is creating,
+   * the `Retry-After` to read it again after (machine-v2.json
+   * `creation.create_status`).
+   */
+  async createMachine(key, request, idempotencyKey) {
+    let last;
+    for (let attempt = 1; attempt <= CREATE_ATTEMPTS; attempt++) {
+      const headers = {
+        location: null,
+        retryAfter: null
+      };
+      try {
+        const answer = await this.request("createMachine", key, { body: withoutUndefined(request), idempotencyKey }, (response) => {
+          headers.location = response.headers.get("location");
+          headers.retryAfter = response.headers.get("retry-after");
+        });
+        return {
+          machine: answer.data,
+          location: headers.location,
+          retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+        };
+      } catch (error) {
+        if (error instanceof HttpError && error.status < 500)
+          throw error;
+        last = error;
+        if (attempt === CREATE_ATTEMPTS)
+          break;
+        const wait = retryAfterSeconds(headers.retryAfter) ?? attempt;
+        await this.pause(Math.min(wait, CREATE_RETRY_MAX_WAIT_SECONDS) * 1e3);
+      }
+    }
+    return unconfirmed("Machine creation", idempotencyKey, "the same arguments")(last);
+  }
+  /** The name of the Machine a create's `Location` names, when it is this
+   * client's origin and `getMachine`'s path; null otherwise, so the key is
+   * never sent to another origin and the caller reads the Machine by the
+   * name it created. */
+  machineNameAt(location) {
+    if (!location)
+      return null;
+    let url;
+    try {
+      url = new URL(location, this.apiOrigin);
+    } catch {
+      return null;
+    }
+    if (url.origin !== new URL(this.apiOrigin).origin || url.search || url.hash)
+      return null;
+    const prefix = `${managementApiBasePath}${managementOperations.getMachine.path.replace("{name}", "")}`;
+    if (!url.pathname.startsWith(prefix))
+      return null;
+    const segment = url.pathname.slice(prefix.length);
+    if (!segment || segment.includes("/"))
+      return null;
+    try {
+      return decodeURIComponent(segment);
+    } catch {
+      return null;
+    }
   }
   getMachine(key, name) {
     return this.call("getMachine", key, { params: { name } });
   }
-  /** Written only at `revision` (machine-v2 requires If-Match, the Machine's
-   * ETag); a stale one is refused with `revision_mismatch`. */
-  updateMachine(key, name, revision, change) {
+  /** The Machine with its ETag, which is opaque (machine-v2.json `etag`)
+   * and is sent back as it was read. */
+  async getMachineWithEtag(key, name) {
+    const headers = { etag: null };
+    const answer = await this.request("getMachine", key, { params: { name } }, (response) => {
+      headers.etag = response.headers.get("etag");
+    });
+    return { machine: answer.data, etag: headers.etag };
+  }
+  /** Written only to the Machine and revision `etag` names, the ETag as read
+   * (machine-v2 requires If-Match on update); a stale one is refused with
+   * `precondition_failed`. */
+  updateMachine(key, name, etag, change) {
     return this.call("updateMachine", key, {
       params: { name },
       body: withoutUndefined(change),
-      ifMatch: `"${revision}"`
+      ifMatch: etag
     });
   }
-  sleepMachine(key, name) {
-    return this.call("sleepMachine", key, { params: { name } });
+  /** With `etag`, only the Machine that ETag names, at that revision, is put
+   * to sleep (machine-v2.json `etag.if_match.sleep` is optional). A 202
+   * carries the `Retry-After` to read the Machine again after
+   * (machine-v2.json `sleep.poll_after_seconds`); a 200 carries none. */
+  async sleepMachine(key, name, etag) {
+    const headers = { retryAfter: null };
+    const answer = await this.request("sleepMachine", key, { params: { name }, ...etag ? { ifMatch: etag } : {} }, (response) => {
+      headers.retryAfter = response.headers.get("retry-after");
+    });
+    return { machine: answer.data, retryAfterSeconds: retryAfterSeconds(headers.retryAfter) };
   }
   /** The Machine being deleted or the device forgotten, with its kind; the
    * Machine is null when the API answered 204, whose `X-Tonbo-Machine-Kind`
    * says whether a name was released (`managed`: its create never reached its
-   * region) or a device was forgotten (`byoc`: its region held no row). */
-  async deleteMachine(key, name) {
+   * region) or a device was forgotten (`byoc`: its region held no row). With
+   * `etag`, only the Machine that ETag names is deleted
+   * (machine-v2.json `etag.if_match.delete` is optional). */
+  async deleteMachine(key, name, etag) {
     const headers = { kind: null };
-    const answer = await this.request("deleteMachine", key, { params: { name } }, (response) => {
+    const answer = await this.request("deleteMachine", key, { params: { name }, ...etag ? { ifMatch: etag } : {} }, (response) => {
       headers.kind = response.headers.get("x-tonbo-machine-kind");
     });
     if (answer?.data)
       return { machine: answer.data, kind: answer.data.kind };
     return { machine: null, kind: headers.kind === "byoc" ? "byoc" : "managed" };
   }
+  /** One page of a managed Machine's activations, newest first; the cursor
+   * pages that Machine only. */
+  listMachineActivations(key, name, { limit, cursor } = {}) {
+    return this.request("listMachineActivations", key, {
+      params: { name },
+      query: { limit, cursor }
+    });
+  }
   /** The whole answer: the shapes and the default one. */
   listMachineShapes(key) {
     return this.request("listMachineShapes", key, {});
   }
 };
+var CREATE_ATTEMPTS = 3;
+var CREATE_RETRY_MAX_WAIT_SECONDS = 30;
+function retryAfterSeconds(value) {
+  if (value === null || !/^[0-9]+$/.test(value.trim()))
+    return null;
+  return Number(value.trim());
+}
 function withoutUndefined(value) {
   return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
 }
@@ -1449,8 +1775,9 @@ function when(timestamp, absent = "never") {
 // ../../packages/tonbo-cli-core/dist/src/login.js
 async function loginCommand(deps, options = {}) {
   try {
-    const login = await deps.auth.login((event) => reportLoginProgress(deps.progress, event), options.account);
-    deps.output(`Logged in to account ${login.account_id}.${login.expires_at ? ` The login expires ${login.expires_at}.` : ""}`);
+    const login = await deps.auth.login((event) => reportLoginProgress(deps.progress, event), options.account, { current: options.current });
+    deps.output(`Logged in to account ${login.name ?? login.account_id}.${login.expires_at ? ` The login expires ${login.expires_at}.` : ""}`);
+    return login;
   } catch (error) {
     deps.progress.fail();
     throw error;
@@ -1514,17 +1841,23 @@ async function logoutCommand(deps) {
     deps.output("Not logged in.");
     return;
   }
-  let failure;
-  try {
-    await deps.api.revokeApiKey(login.key, login.key_id);
-  } catch (error) {
-    if (!(error instanceof HttpError && (error.status === 401 || error.status === 404)))
-      failure = error instanceof Error ? error : new Error("The revocation failed.");
+  const failures = [];
+  let first;
+  for (const entry of accountLogins(login)) {
+    try {
+      await deps.api.revokeApiKey(entry.key, entry.key_id);
+    } catch (error) {
+      if (error instanceof HttpError && (error.status === 401 || error.status === 404))
+        continue;
+      const failure = error instanceof Error ? error : new Error("The revocation failed.");
+      first ??= failure;
+      failures.push(`${entry.key_id}: ${failure.message}`);
+    }
   }
   await deps.credentials.remove();
-  if (failure)
-    throw new Error(`Removed the saved login, but could not revoke its key ${login.key_id}: ${failure.message} Revoke it under API keys in the Tonbo console.`, { cause: failure });
-  deps.output("Logged out. The CLI key is revoked.");
+  if (failures.length)
+    throw new Error(`Removed the saved login, but could not revoke ${failures.length === 1 ? "its key" : "these keys"} ${failures.join("; ")} Revoke ${failures.length === 1 ? "it" : "them"} under API keys in the Tonbo console.`, { cause: first });
+  deps.output(login.accounts && Object.keys(login.accounts).length > 1 ? "Logged out. Every account's CLI key on this computer is revoked." : "Logged out. The CLI key is revoked.");
 }
 
 // ../../packages/tonbo-cli-core/dist/src/origin.js
@@ -2330,16 +2663,19 @@ async function usageShowCommand(deps, options = {}) {
 // src/machine.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 var MACHINE_ERROR_HINTS = {
-  region_unavailable: "Machines are not open there yet, or that region cannot be reached from here; nothing was created or changed.",
+  region_not_offered: "Machines are not offered in that region yet; nothing was created or changed. Name a region where they are offered.",
+  region_unavailable: "That region cannot be reached right now; nothing was created or changed. Try again shortly.",
   name_taken: "Choose another name; `tonbo machine list` shows the account's Machines.",
   hostname_taken: "The hostname <name>-<account> is held by another Machine or account; choose another name.",
   hostname_too_long: "<name>-<account> must fit one hostname label; choose a shorter name.",
   account_name_unclaimed: "Claim a Tonbo ID for the account on the console's Profile page, then run the command again.",
   image_platform_unsupported: "Machines run linux/arm64: publish the image for that platform (for example `docker buildx build --platform linux/arm64`).",
   image_not_offered: "Only the platform image runs until image pulls ship: create or update the Machine with `--image tonbo.dev/platform`.",
-  shape_unavailable: "`tonbo machine shapes` lists the shapes a Machine may name now.",
+  shape_not_offered: "`tonbo machine shapes` lists the shapes a Machine may name now.",
   port_reserved: "Serve the application on another port.",
-  revision_mismatch: "The Machine changed since it was read; `tonbo machine show` it and run the update again.",
+  precondition_required: "The API needs the Machine's ETag for this change; `tonbo machine show` prints it, and the command sends the ETag it reads unless --if-match names one.",
+  precondition_failed: "The Machine changed since it was read, or another Machine now has its name; `tonbo machine show` it and run the command again.",
+  machine_failed: "A Machine whose creation failed does not change: `tonbo machine show` says why; delete it with `tonbo machine delete` and create it again.",
   snapshot_would_be_discarded: "Pass --discard-snapshot to apply the change at the next boot, which then starts fresh.",
   database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`) first.",
   idempotency_conflict: "That idempotency key belongs to another request: leave out --idempotency-key to create a new Machine.",
@@ -2354,6 +2690,28 @@ var MACHINE_IMAGE_FAILURE_HINTS = {
   image_too_large: "Make the image smaller (fewer or smaller layers)",
   image_unsupported: "Rebuild the image without the entry the message names"
 };
+var MACHINE_CREATION_FAILURE_HINTS = {
+  database_creation_failed: "The Machine's database could not be created; the message names the stream and the code. If the code is payment_required, add credit to the account first; then delete the Machine and create it again.",
+  database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`), then delete this Machine and create it again.",
+  payment_required: "The account's credit is exhausted: add credit to the account, then delete the Machine and create it again.",
+  ...Object.fromEntries(
+    Object.entries(MACHINE_IMAGE_FAILURE_HINTS).map(([code, hint]) => [
+      code,
+      `${hint}, then delete the Machine and create it again naming the fixed image.`
+    ])
+  )
+};
+function creationFailureText(machine) {
+  const { failure } = machine;
+  if (!failure) return { reason: "", hint: "" };
+  const hint = MACHINE_CREATION_FAILURE_HINTS[failure.code];
+  return { reason: ` (${failure.code}: ${failure.message})`, hint: hint ? `
+${hint}` : "" };
+}
+function ifMatchHeader(value) {
+  if (value === void 0) return void 0;
+  return value.startsWith('"') || value.startsWith('W/"') ? value : `"${value}"`;
+}
 function explainMachineError(error) {
   if (!(error instanceof HttpError) || error.code === null) return error;
   const hint = MACHINE_ERROR_HINTS[error.code];
@@ -2374,20 +2732,98 @@ function portText(port) {
 function machinePortsText(machine) {
   return machine.ports.length ? machine.ports.map(portText).join(", ") : "none";
 }
-function idleActionText(machine) {
+var { earlyReclaimSeconds, pollAfterSeconds, sleepPollAfterSeconds, wakeHoldSeconds } = machineTimings;
+function machineState(machine) {
+  if (machine.failure)
+    return `${machine.state}: ${machine.failure.code}: ${machine.failure.message}`;
+  if (machine.state === "creating")
+    return `creating: not ready for requests yet; read it again in ${pollAfterSeconds} s, or create with --wait`;
+  return machine.state;
+}
+function powerText(machine) {
+  const { power } = machine.status;
+  if (machine.state !== "active") return power;
+  if (power === "asleep")
+    return `asleep: the first request boots it, and the edge holds that request for up to ${wakeHoldSeconds} s`;
+  if (power === "awake") return "awake: serving requests";
+  return power;
+}
+function duration(seconds) {
+  return seconds % 60 === 0 && seconds >= 120 ? `${seconds / 60} min` : `${seconds} s`;
+}
+function sleepText(machine) {
   const { action, reason } = machine.status.sleep;
-  if (action === machine.idle_action) return action;
-  return `${action} (${machine.idle_action} requested; ${reason.replaceAll("_", " ")})`;
+  const when2 = `after about ${duration(earlyReclaimSeconds)} idle (early) or at most ${machine.sleep_after_seconds} s without a connection`;
+  if (action !== "release") return `${when2}; it then ${action}s`;
+  return `${when2}; the disk resets at every sleep${reason === "suspend_unavailable" ? " until suspend ships" : ""}`;
+}
+function activationFields(machine) {
+  const { activation } = machine;
+  if (!activation) return [];
+  const fields2 = [
+    [
+      "Activation",
+      `${activation.state} since ${activation.started_at} (wake ${activation.wake_gen}, from ${activation.source})`
+    ]
+  ];
+  if (typeof activation.revision === "number" && activation.revision !== machine.revision)
+    fields2.push([
+      "Pending",
+      `Spec ${machine.revision}, admitted at ${activation.revision}: ports and sleep-after already apply; if the image, command, shape or env changed, run \`tonbo machine sleep ${machine.name}\` to apply it`
+    ]);
+  return fields2;
+}
+var MACHINE_WAKE_BLOCKED_HINTS = {
+  payment_required: "The account's credit does not cover a wake: add credit, and the next request wakes it.",
+  standing: "The account's Streams standing is not solvent: settle the account, and the next request wakes it.",
+  meter_lag: "Tonbo could not confirm the account's usage in time; the next request tries again.",
+  crash_backoff: "Its recent wakes failed; see `tonbo machine activations <name>`.",
+  capacity: "No host had room for its shape; the next request tries again.",
+  region_closed: "Machines are closed in its region for now; the next request after they reopen wakes it."
+};
+function conditionText(name, condition) {
+  switch (condition.type) {
+    case "wake_blocked": {
+      const retry = condition.retry_at ? `, retry after ${condition.retry_at}` : "";
+      const hint = MACHINE_WAKE_BLOCKED_HINTS[condition.reason]?.replaceAll("<name>", name);
+      return `wake blocked (${condition.reason.replaceAll("_", " ")}) since ${condition.since}${retry}.${hint ? ` ${hint}` : ""}`;
+    }
+    case "creation_delayed":
+      return `still creating since ${condition.since}, longer than usual; Tonbo's operators are alerted, and creation goes on until it is active or failed.`;
+    case "node_unreachable":
+      return `its host is unreachable since ${condition.since}`;
+    case "egress_blocked":
+      return `outbound access blocked for the ${condition.scope} since ${condition.since}${condition.until ? ` until ${condition.until}` : ""}`;
+    default:
+      return JSON.stringify(condition);
+  }
+}
+function conditionFields(machine) {
+  return (machine.status.conditions ?? []).map((condition) => [
+    "Condition",
+    conditionText(machine.name, condition)
+  ]);
 }
-function machineState(machine) {
-  return machine.failure ? `${machine.state}: ${machine.failure.code}: ${machine.failure.message}` : machine.state;
+function endText(end) {
+  const status = end.exit_code !== null ? `, exit code ${end.exit_code}` : end.signal !== null ? `, signal ${end.signal}` : "";
+  return `${end.state} (${end.reason.replaceAll("_", " ")}${status}) at ${end.at}`;
+}
+var DURABILITY_LINK = "https://tonbo.dev/docs/machines/guarantees#sleep";
+var PRIVATE_PORTS_LINK = "https://tonbo.dev/docs/machines/requests#private-ports";
+function privatePortLines(machine) {
+  const port = machine.ports.find((entry) => entry.default);
+  if (!port || port.access !== "private") return [];
+  return [
+    `Port ${port.port} is private: call it with a personal key from \`tonbo api-key create\` (see ${PRIVATE_PORTS_LINK}):`,
+    `  curl -H "Authorization: Bearer $TONBO_KEY" ${machine.hostnames.https}/`,
+    "On a private port Tonbo authenticates the caller, and the app sees neither Authorization nor who called; an app with its own users serves a public port and does its own auth."
+  ];
 }
 function imageText(machine) {
   const { reference, repository, digest, state } = machine.image;
   if (digest === null) return `${reference} (platform image)`;
   const pulled = repository === null ? digest : `${repository}@${digest}`;
-  const pulling = state === "resolved" && (machine.state === "creating" || machine.state === "active");
-  return `${reference} (${pulled}, ${pulling ? "pulling" : state})`;
+  return `${reference} (${pulled}, ${state})`;
 }
 function imageNextStep(machine, hint) {
   if (machine.state === "deleting") return null;
@@ -2405,30 +2841,41 @@ function imageFailureFields(machine) {
     ...next ? [["Next step", next]] : []
   ];
 }
-function machineFields(machine) {
+function machineFields(machine, etag = null, lastEnd = null) {
   return fields([
     ["Name", machine.name],
     ["ID", machine.id],
     ["Region", machine.region],
     ["State", machineState(machine)],
-    ["Power", machine.status.power],
+    ["Power", powerText(machine)],
+    ...activationFields(machine),
+    ...lastEnd ? [["Last end", endText(lastEnd)]] : [],
+    ...conditionFields(machine),
+    ["Sleeps", sleepText(machine)],
     ["Shape", machine.shape],
     ["Image", imageText(machine)],
     ...imageFailureFields(machine),
     ["Command", machine.command ? machine.command.join(" ") : "the image's own"],
     ["Ports", machinePortsText(machine)],
     ["HTTPS", machine.hostnames.https],
-    ["SSH", machine.hostnames.ssh],
+    // The resource keeps the SSH destination as a receipt; SSH is not served
+    // before tier P3.
+    ["SSH", `${machine.hostnames.ssh} (not served yet)`],
     ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
-    ["Sleep after", `${machine.sleep_after_seconds}s without a connection`],
-    ["Idle action", idleActionText(machine)],
-    ["Stop grace", `${machine.stop_grace_seconds}s`],
-    ["Database", machine.database.name],
+    ["Stop grace", `${machine.stop_grace_seconds} s`],
+    ["Database", `${machine.database.name} (${machine.database.url})`],
+    ["Logs", machine.logs.url],
+    ["Durability", DURABILITY_LINK],
     ["Revision", String(machine.revision)],
+    ...etag ? [["ETag", etag]] : [],
+    ...machine.created_by ? [["Created by", machine.created_by]] : [],
     ["Created", machine.created_at],
     ["Updated", machine.updated_at]
   ]);
 }
+function machineText(machine, etag = null, lastEnd = null) {
+  return [machineFields(machine, etag, lastEnd), ...privatePortLines(machine)].join("\n");
+}
 function keyStateText(machine) {
   const state = machine.byoc.key_state;
   if (state === "active") return state;
@@ -2452,10 +2899,10 @@ function deviceFields(machine) {
     ["Updated", machine.updated_at]
   ]);
 }
-function anyMachineFields(machine) {
-  return machine.kind === "byoc" ? deviceFields(machine) : machineFields(machine);
+function anyMachineText(machine, etag = null, lastEnd = null) {
+  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, etag, lastEnd);
 }
-function parsePorts(specs, current) {
+function parsePorts(specs) {
   const accesses = machinePortAccess;
   return specs.map((spec) => {
     const match = /^([0-9]{1,5})(?::([a-z]+))?$/.exec(spec);
@@ -2464,14 +2911,7 @@ function parsePorts(specs, current) {
       throw new Error(
         `--port ${spec}: give <port> or <port>:<access>, access ${accesses.join(" or ")}.`
       );
-    const port = Number(match[1]);
-    const before = current.find((entry) => entry.port === port && entry.access === access);
-    return {
-      port,
-      access,
-      default: false,
-      ...before?.public_limits === void 0 ? {} : { public_limits: before.public_limits }
-    };
+    return { port: Number(match[1]), access, default: false };
   });
 }
 function withDefault(ports, defaultPort) {
@@ -2493,6 +2933,42 @@ function parseEnv(pairs) {
   }
   return env;
 }
+var SECRET_LOOKING = /(_KEY|_TOKEN)$|SECRET|PASSWORD/i;
+function specWarnings(deps, ports, envKeys) {
+  if (ports.length === 0)
+    deps.notice(
+      "This Machine has no port: until exec and SSH arrive, nothing can wake it. Add --port <port>."
+    );
+  const secret = envKeys.filter((key) => SECRET_LOOKING.test(key)).sort();
+  if (secret.length)
+    deps.notice(
+      `${secret.join(", ")} ${secret.length === 1 ? "looks" : "look"} secret: env values are readable by every member through the API; Machine secrets come later.`
+    );
+}
+function waitTimeout(options) {
+  if (options.timeout !== void 0 && !options.wait) throw new Error("--timeout needs --wait.");
+  return options.timeout ?? DEFAULT_WAIT_SECONDS;
+}
+var DEFAULT_WAIT_SECONDS = 300;
+async function waitForMachine(deps, key, name, firstWait, every, timeout, settled) {
+  const now = deps.now ?? Date.now;
+  const pause = deps.pause ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const start = now();
+  let wait = firstWait;
+  let last = null;
+  for (; ; ) {
+    const elapsed = (now() - start) / 1e3;
+    if (elapsed + wait > timeout) return { machine: null, last, waited: Math.round(elapsed) };
+    await pause(wait * 1e3);
+    const machine = await deps.api.getMachine(key, name);
+    if (machine.kind === "byoc")
+      throw new Error(`${name} is one of your computers, not a Machine.`);
+    if (settled(machine))
+      return { machine, last: machine, waited: Math.round((now() - start) / 1e3) };
+    last = machine;
+    wait = every;
+  }
+}
 async function machineListCommand(deps, options = {}) {
   await machineCommand(async () => {
     const page = await deps.api.listMachines(await deps.auth.apiKey(), {
@@ -2506,7 +2982,7 @@ async function machineListCommand(deps, options = {}) {
       if (managed.length)
         tables.push(
           table(
-            ["NAME", "REGION", "STATE", "POWER", "SHAPE", "IMAGE", "HTTPS"],
+            ["NAME", "REGION", "STATE", "POWER", "SHAPE", "IMAGE", "HTTPS", "CONDITIONS"],
             managed.map((machine) => [
               machine.name,
               machine.region,
@@ -2514,7 +2990,8 @@ async function machineListCommand(deps, options = {}) {
               machine.status.power,
               machine.shape,
               machine.image.reference,
-              machine.hostnames.https
+              machine.hostnames.https,
+              conditionsCell(machine)
             ])
           )
         );
@@ -2540,49 +3017,194 @@ async function machineListCommand(deps, options = {}) {
       );
   });
 }
+function conditionsCell(machine) {
+  const conditions = machine.status.conditions ?? [];
+  if (!conditions.length) return "-";
+  return conditions.map(
+    (condition) => condition.type === "wake_blocked" ? `wake_blocked:${condition.reason}` : condition.type
+  ).join(",");
+}
 function createdText(machine) {
   if (machine.state === "creating")
-    return `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready.`;
+    return `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready, or create with --wait.`;
   return `Created Machine ${machine.name}.`;
 }
+function ago(deps, timestamp) {
+  const seconds = Math.max(
+    0,
+    Math.round(((deps.now ?? Date.now)() - Date.parse(timestamp)) / 1e3)
+  );
+  if (seconds < 120) return `${seconds} s`;
+  if (seconds < 7200) return `${Math.round(seconds / 60)} min`;
+  if (seconds < 172800) return `${Math.round(seconds / 3600)} h`;
+  return `${Math.round(seconds / 86400)} days`;
+}
+async function nameTaken(deps, key, name, error) {
+  let holder;
+  try {
+    holder = await deps.api.getMachine(key, name);
+  } catch {
+    return error;
+  }
+  const what = holder.kind === "byoc" ? `${name} is one of your computers; choose another name.` : `A Machine named ${name} already exists (created ${ago(deps, holder.created_at)} ago, ${holder.state}); if it is yours from a lost reply, \`tonbo machine show ${name}\`.`;
+  return new HttpError(`${error.message}
+${what}`, error.status, error.body, error.requestId);
+}
+async function waitForCreate(deps, key, machine, name, firstWait, timeout, json) {
+  const {
+    machine: settled,
+    last,
+    waited
+  } = await waitForMachine(
+    deps,
+    key,
+    name,
+    firstWait,
+    pollAfterSeconds,
+    timeout,
+    (read) => read.state !== "creating"
+  );
+  if (!settled) {
+    const known = last ?? machine;
+    print(deps, json, known, machineFields(known));
+    throw new Error(
+      `Machine ${machine.name} is still creating after ${waited} s; nothing was undone. \`tonbo machine show ${machine.name}\` reports it active when it is ready.`
+    );
+  }
+  if (settled.state === "active") {
+    const pulled = settled.image.digest === null ? "" : `, image ${settled.image.state}`;
+    print(
+      deps,
+      json,
+      settled,
+      [
+        `Created ${settled.name} in ${settled.region} (active after ${waited} s${pulled}).`,
+        machineText(settled)
+      ].join("\n")
+    );
+    return;
+  }
+  print(deps, json, settled, machineFields(settled));
+  if (settled.state === "failed") {
+    const { reason, hint } = creationFailureText(settled);
+    throw new Error(
+      `Machine ${settled.name} failed to be created${reason}; delete it with \`tonbo machine delete ${settled.name}\` and create it again.${hint}`
+    );
+  }
+  throw new Error(`Machine ${settled.name} is ${settled.state}; it was not created.`);
+}
 async function machineCreateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (!options.image) throw new Error("Pass --image <reference>.");
+    const timeout = waitTimeout(options);
     const env = parseEnv(options.env ?? []);
-    const ports = withDefault(parsePorts(options.port ?? [], []), options.defaultPort);
+    const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
     const shape = options.shape ?? (await deps.api.listMachineShapes(key)).default;
-    const machine = await deps.api.createMachine(
-      key,
-      {
-        name,
-        image: options.image,
-        shape,
-        region: options.region,
-        command: command.length ? command : void 0,
-        ports: ports.length ? ports : void 0,
-        env: Object.keys(env).length ? env : void 0,
-        sleep_after_seconds: options.sleepAfter,
-        idle_action: options.idleAction,
-        stop_grace_seconds: options.stopGrace
-      },
-      options.idempotencyKey ?? randomUUID3()
-    );
+    let created;
+    try {
+      created = await deps.api.createMachine(
+        key,
+        {
+          name,
+          image: options.image,
+          shape,
+          region: options.region,
+          command: command.length ? command : void 0,
+          ports: ports.length ? ports : void 0,
+          env: Object.keys(env).length ? env : void 0,
+          sleep_after_seconds: options.sleepAfter,
+          idle_action: options.idleAction,
+          stop_grace_seconds: options.stopGrace
+        },
+        options.idempotencyKey ?? randomUUID3()
+      );
+    } catch (error) {
+      if (error instanceof HttpError && error.code === "name_taken")
+        throw await nameTaken(deps, key, name, error);
+      throw error;
+    }
+    const { machine } = created;
+    specWarnings(deps, machine.ports, Object.keys(env));
     if (machine.state === "failed") {
       print(deps, options.json, machine, machineFields(machine));
+      const { reason, hint } = creationFailureText(machine);
       throw new Error(
-        `Machine ${machine.name} failed to be created; delete it with \`tonbo machine delete ${machine.name}\` and create it again.`
+        `Machine ${machine.name} failed to be created${reason}; delete it with \`tonbo machine delete ${machine.name}\` and create it again.${hint}`
       );
     }
-    print(deps, options.json, machine, [createdText(machine), machineFields(machine)].join("\n"));
+    if (options.wait && machine.state === "creating")
+      return waitForCreate(
+        deps,
+        key,
+        machine,
+        deps.api.machineNameAt(created.location) ?? machine.name,
+        created.retryAfterSeconds ?? pollAfterSeconds,
+        timeout,
+        options.json
+      );
+    print(deps, options.json, machine, [createdText(machine), machineText(machine)].join("\n"));
   });
 }
 async function machineShowCommand(deps, name, options = {}) {
   await machineCommand(async () => {
-    const machine = await deps.api.getMachine(await deps.auth.apiKey(), name);
-    print(deps, options.json, machine, anyMachineFields(machine));
+    const key = await deps.auth.apiKey();
+    const { machine, etag } = await deps.api.getMachineWithEtag(key, name);
+    const lastEnd = options.json || machine.kind === "byoc" || machine.state !== "active" ? null : await lastActivationEnd(deps, key, machine.name);
+    print(deps, options.json, machine, anyMachineText(machine, etag, lastEnd));
   });
 }
+async function lastActivationEnd(deps, key, name) {
+  try {
+    const page = await deps.api.listMachineActivations(key, name, { limit: 2 });
+    return page.data.find((entry) => entry.end !== null)?.end ?? null;
+  } catch (error) {
+    if (!(error instanceof HttpError)) throw error;
+    deps.notice(
+      `Could not read how its last activation ended (${error.status}); \`tonbo machine activations ${name}\` lists them.`
+    );
+    return null;
+  }
+}
+async function machineActivationsCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    const page = await deps.api.listMachineActivations(await deps.auth.apiKey(), name, {
+      limit: options.limit,
+      cursor: options.cursor
+    });
+    printPage(
+      deps,
+      options.json,
+      page,
+      (activations) => activations.length ? table(
+        ["WAKE", "SOURCE", "REVISION", "SHAPE", "STARTED", "END"],
+        activations.map((entry) => [
+          String(entry.wake_gen),
+          entry.source,
+          String(entry.revision),
+          entry.shape,
+          entry.started_at,
+          entry.end ? endText(entry.end) : "live"
+        ])
+      ) : `Machine ${name} has not been woken yet.`
+    );
+  });
+}
+function appliesText(name, change) {
+  const lines = [];
+  if (change.ports !== void 0 || change.sleep_after_seconds !== void 0)
+    lines.push("Ports and sleep-after apply now.");
+  const later = [change.image, change.command, change.shape, change.env].some(
+    (field) => field !== void 0
+  );
+  if (later) {
+    lines.push(
+      `The change applies at the next activation. To apply it now, run \`tonbo machine sleep ${name}\`; the next request boots the new spec.`
+    );
+    if (change.image !== void 0) lines.push("Naming the same tag again re-resolves its digest.");
+  }
+  return lines;
+}
 async function machineUpdateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (command.length && options.imageCommand)
@@ -2590,12 +3212,14 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
     if (options.clearPorts && (options.port?.length || options.defaultPort !== void 0))
       throw new Error("Give --port or --clear-ports, not both.");
     const key = await deps.auth.apiKey();
-    const read = await deps.api.getMachine(key, name);
+    const { machine: read, etag: readTag } = await deps.api.getMachineWithEtag(key, name);
     if (read.kind === "byoc")
       throw new Error(
         `${name} is one of your computers; only \`tonbo machine show\` and \`tonbo machine delete\` serve it.`
       );
     const current = read;
+    const etag = ifMatchHeader(options.ifMatch) ?? readTag;
+    if (etag === null) throw new Error(`The API answered ${name} without an ETag.`);
     const change = {
       image: options.image,
       shape: options.shape,
@@ -2606,59 +3230,95 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
     };
     if (options.clearPorts) change.ports = [];
     else if (options.port?.length) {
-      const ports = parsePorts(options.port, current.ports);
+      const ports = parsePorts(options.port);
       const kept = current.ports.find((entry) => entry.default)?.port;
       const defaultPort = options.defaultPort ?? (ports.some((entry) => entry.port === kept) ? kept : void 0);
       change.ports = withDefault(ports, defaultPort);
     } else if (options.defaultPort !== void 0)
       change.ports = withDefault(current.ports, options.defaultPort);
+    const setEnv = parseEnv(options.env ?? []);
     if (options.env?.length || options.unsetEnv?.length) {
-      const env = { ...current.env, ...parseEnv(options.env ?? []) };
+      const env = { ...current.env, ...setEnv };
       for (const variable of options.unsetEnv ?? []) delete env[variable];
       change.env = env;
     }
     if (options.discardSnapshot) change.discard_snapshot = true;
     if (Object.values(change).every((value) => value === void 0))
       throw new Error("Nothing to change: pass at least one option or a command.");
-    const machine = await deps.api.updateMachine(
-      key,
-      name,
-      options.revision ?? current.revision,
-      change
-    );
+    const machine = await deps.api.updateMachine(key, name, etag, change);
+    specWarnings(deps, machine.ports, Object.keys(setEnv));
     print(
       deps,
       options.json,
       machine,
       [
-        `Updated Machine ${machine.name} to revision ${machine.revision}. Ports and sleep-after apply now; image, command, shape and env at its next boot.`,
-        machineFields(machine)
+        `Updated Machine ${machine.name} to revision ${machine.revision}.`,
+        ...appliesText(machine.name, change),
+        machineText(machine)
       ].join("\n")
     );
   });
 }
+function sleptText(machine) {
+  if (machine.state === "creating")
+    return `Machine ${machine.name} is still creating; nothing to put to sleep.`;
+  if (machine.status.power === "asleep")
+    return `Machine ${machine.name} is already asleep; nothing to do. The next request boots it.`;
+  return `Machine ${machine.name} is going to sleep (${machine.status.sleep.action}); the next request boots it again, on its latest spec.`;
+}
 async function machineSleepCommand(deps, name, options = {}) {
   await machineCommand(async () => {
-    const machine = await deps.api.sleepMachine(await deps.auth.apiKey(), name);
+    const timeout = waitTimeout(options);
+    const key = await deps.auth.apiKey();
+    const { machine, retryAfterSeconds: retryAfterSeconds2 } = await deps.api.sleepMachine(
+      key,
+      name,
+      ifMatchHeader(options.ifMatch)
+    );
+    const going = options.wait && machine.state === "active" && machine.status.power !== "asleep";
+    if (!going) {
+      print(deps, options.json, machine, sleptText(machine));
+      return;
+    }
+    const { machine: asleep, waited } = await waitForMachine(
+      deps,
+      key,
+      name,
+      retryAfterSeconds2 ?? sleepPollAfterSeconds,
+      sleepPollAfterSeconds,
+      timeout,
+      (read) => read.status.power === "asleep" || read.state !== "active"
+    );
+    if (!asleep)
+      throw new Error(
+        `Machine ${name} is not asleep after ${waited} s; \`tonbo machine show ${name}\` says what keeps it awake.`
+      );
+    if (asleep.status.power !== "asleep")
+      throw new Error(`Machine ${name} is ${asleep.state}; it did not go to sleep.`);
     print(
       deps,
       options.json,
-      machine,
-      `Machine ${machine.name} is going to sleep (${machine.status.sleep.action}); its next connection wakes it.`
+      asleep,
+      `Machine ${asleep.name} is asleep (after ${waited} s); the next request boots it, on its latest spec.`
     );
   });
 }
 async function machineDeleteCommand(deps, name, options = {}) {
   await machineCommand(async () => {
     const key = await deps.auth.apiKey();
+    const read = { etag: null };
     await confirm(
       deps,
       options.yes,
       `delete Machine ${name}`,
-      () => deleteQuestion(deps, key, name),
+      () => deleteQuestion(deps, key, name, read),
       name
     );
-    const { machine, kind } = await deps.api.deleteMachine(key, name);
+    const { machine, kind } = await deps.api.deleteMachine(
+      key,
+      name,
+      ifMatchHeader(options.ifMatch) ?? read.etag ?? void 0
+    );
     print(deps, options.json, machine, deletedText(name, machine, kind));
     if (machine?.kind === "byoc" && machine.byoc.key_state === "active")
       deps.notice(
@@ -2666,10 +3326,12 @@ async function machineDeleteCommand(deps, name, options = {}) {
       );
   });
 }
-async function deleteQuestion(deps, key, name) {
+async function deleteQuestion(deps, key, name, read) {
   let kind = null;
   try {
-    kind = (await deps.api.getMachine(key, name)).kind;
+    const answer = await deps.api.getMachineWithEtag(key, name);
+    kind = answer.machine.kind;
+    read.etag = answer.etag;
   } catch (error) {
     if (!(error instanceof HttpError && error.status === 404)) throw error;
   }
@@ -2686,6 +3348,9 @@ function deletedText(name, machine, kind) {
     return `Machine ${machine.name} is being deleted; its name is free for a new Machine.`;
   return `Released the name ${name}; no Machine had been created under it.`;
 }
+function hourlyPrice(micros) {
+  return `$${(micros / 1e6).toFixed(4)}/h`;
+}
 async function machineShapesCommand(deps, options = {}) {
   await machineCommand(async () => {
     const shapes = await deps.api.listMachineShapes(await deps.auth.apiKey());
@@ -2694,14 +3359,15 @@ async function machineShapesCommand(deps, options = {}) {
       options.json,
       shapes,
       table(
-        ["SHAPE", "VCPUS", "MEMORY", "SCRATCH", "OFFERED", "SUSPENDABLE"],
+        ["SHAPE", "VCPUS", "MEMORY", "SCRATCH", "OFFERED", "SUSPENDABLE", "LIST PRICE"],
         shapes.data.map((shape) => [
           shape.shape === shapes.default ? `${shape.shape} (default)` : shape.shape,
           String(shape.vcpus),
           `${shape.memory_gib} GiB`,
           `${shape.scratch_gib} GiB`,
           shape.offered ? "yes" : "no",
-          shape.suspendable ? "yes" : "no"
+          shape.suspendable ? "yes" : "no",
+          hourlyPrice(shape.ceiling_usd_micros_per_hour)
         ])
       )
     );
@@ -2768,6 +3434,7 @@ function operationOptions(command, operationId) {
     command.option("--cursor <cursor>", "continue from the cursor a previous page printed");
   return command.option("--json", "print the API data as JSON");
 }
+var ifMatchHelp = (action) => `${action} only the Machine at the ETag \`tonbo machine show\` printed (with or without its quotes); the ETag the command reads, if it reads one, by default`;
 var repeated = (value, previous = []) => [...previous, value];
 var roleOption = (description) => new Option("--role <role>", description).choices(accountRoles);
 function machineSpecOptions(command, update) {
@@ -2814,7 +3481,9 @@ function parseUsageSort(value) {
 }
 function createProgram(dependencies = createDependencies) {
   const program = new Command().name("tonbo").description("Sign in to Tonbo and manage account resources.").version(packageVersion.version);
-  program.command("login").description("sign in through the browser and save a personal key for this computer").option("--account <name>", "the account to log in to; defaults to your personal account").action(async (options) => loginCommand(dependencies(), options));
+  program.command("login").description("sign in through the browser and save a personal key for this computer").option("--account <name>", "the account to log in to; defaults to your personal account").action(async (options) => {
+    await loginCommand(dependencies(), options);
+  });
   program.command("logout").description("revoke this computer's key and remove the saved login").action(async () => logoutCommand(dependencies()));
   const account = program.command("account").description("the account you are logged in to");
   operationOptions(
@@ -3075,6 +3744,10 @@ function createProgram(dependencies = createDependencies) {
     ).option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the Machine it created"
+    ).option("--wait", "wait until the Machine is active, or say why it failed").option(
+      "--timeout <seconds>",
+      `how long --wait waits; ${DEFAULT_WAIT_SECONDS} by default`,
+      parseWhole
     ),
     "createMachine"
   ).action(
@@ -3090,11 +3763,7 @@ function createProgram(dependencies = createDependencies) {
     machineSpecOptions(
       machine.command("update <name> [command...]").description(
         "change a Machine; [command...] after -- replaces its command at the next boot"
-      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option(
-        "--revision <revision>",
-        "write only if the Machine is still at this revision (tonbo machine show); the revision it reads by default",
-        parseWhole
-      ).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
+      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
       true
     ),
     "updateMachine"
@@ -3102,7 +3771,11 @@ function createProgram(dependencies = createDependencies) {
     async (name, command, options) => machineUpdateCommand(dependencies(), name, command, options)
   );
   operationOptions(
-    machine.command("sleep <name>").description("put a Machine to sleep now"),
+    machine.command("sleep <name>").description("put a Machine to sleep now; its next request boots it on its latest spec").option("--if-match <etag>", ifMatchHelp("put to sleep")).option("--wait", "wait until the Machine is asleep").option(
+      "--timeout <seconds>",
+      `how long --wait waits; ${DEFAULT_WAIT_SECONDS} by default`,
+      parseWhole
+    ),
     "sleepMachine"
   ).action(
     async (name, options) => machineSleepCommand(dependencies(), name, options)
@@ -3110,11 +3783,17 @@ function createProgram(dependencies = createDependencies) {
   operationOptions(
     machine.command("delete <name>").description(
       "delete a Machine with its disk, database and logs, or forget one of your computers"
-    ).option("--yes", "delete without asking; required when stdin is not a terminal"),
+    ).option("--yes", "delete without asking; required when stdin is not a terminal").option("--if-match <etag>", ifMatchHelp("delete")),
     "deleteMachine"
   ).action(
     async (name, options) => machineDeleteCommand(dependencies(), name, options)
   );
+  operationOptions(
+    machine.command("activations <name>").description("list a Machine's activations, newest first, and how each ended"),
+    "listMachineActivations"
+  ).action(
+    async (name, options) => machineActivationsCommand(dependencies(), name, options)
+  );
   operationOptions(
     machine.command("shapes").description("list the shapes a Machine may have"),
     "listMachineShapes"