@koda-sl/baker-cli 0.306.0-dev.bb28562ac → 0.306.1-dev.bb28562ac

package/README.md

@@ -2957,8 +2957,14 @@ Read one avatar: status, `sheetUrl` for `--reference`, and the `subjectDescripti
 ```bash
 baker avatars get marta
 baker avatars get marta --full --output md
+baker avatars get marta --wait            # returns the moment the sheet settles (≤90s)
 ```
 
+`--wait` returns immediately, rather than blocking, when the avatar is waiting for its
+face (`needsFace: true`). That state is `generating` with nothing rendering — the casting
+portraits are in front of the user and the build starts when they choose — so there is
+nothing for the deadline to wait out.
+
 #### `baker avatars create`
 
 Cast a new presenter. `--name` and `--subject` are required; `--subject` describes one person plainly (age, build, hair, skin, face) with no scene, lighting, camera, or wardrobe.
@@ -2976,6 +2982,12 @@ baker avatars create --name "Marta" --subject "…" \
 
 Optional: `--handle`, `--speech`, `--motion`, `--setting`, `--accent`. Returns `{ avatarId, handle, likeness, status }`.
 
+The handle is slugged from `--name` when you do not pass one, and a taken slug is numbered
+rather than refused — a second Marta becomes `marta-2`, so a retired avatar never blocks the
+next one that shares her name. A `--handle` you pass yourself still conflicts: that one is a
+decision, and moving it quietly would point `@marta` at somebody else. The returned `handle`
+is the one the avatar actually got.
+
 #### `baker avatars update <handle>`
 
 Edit an avatar. Profile flags are merged over the stored profile, so `--persona` alone keeps the subject description intact; an empty value clears the field it names (except `--subject`, which can only be replaced). Changing `--subject` requires `--regenerate-sheet` in the same call — otherwise the sheet still shows the person described before.
@@ -2990,6 +3002,9 @@ baker avatars update marta --new-handle marta-founder --accent "Spanish from Spa
 
 Remove an avatar. `--archive` retires it — it leaves the roster but past work and `@handle` mentions keep resolving. Without `--archive` it is deleted for good.
 
+Refused, either way, while the user is choosing that avatar's face: removing it would leave
+the casting question on their screen with nothing behind it.
+
 ```bash
 baker avatars delete marta --archive --dry-run
 baker avatars delete marta --archive

package/dist/cli.js

@@ -4470,6 +4470,15 @@ var avatarSummarySchema = z10.object({
   sheetUrl: z10.string().optional(),
   coverUrl: z10.string().optional(),
   errorMessage: z10.string().optional(),
+  /**
+   * The build is parked on a face nobody has picked yet.
+   *
+   * `generating` otherwise means a render is running. This is the one case where it
+   * does not, and it is the difference between "come back in thirty seconds" and
+   * "the user is looking at four portraits right now" — so anything that waits on an
+   * avatar has to read it, or it waits out its whole deadline on nothing.
+   */
+  needsFace: z10.boolean().optional(),
   /**
    * The chat this avatar was created in, when it was created in one.
    *
@@ -30332,6 +30341,11 @@ var CAST_FLAG_RULE = "Cast with `--avatar <handle>` on `baker studio generate`,
 var VERBATIM_RULE = "When you do write the description yourself \u2014 a hand-built canvas node, a landing image, anywhere `--avatar` does not exist \u2014 copy `subjectDescription` VERBATIM, word for word. Re-phrasing it per generation is the other reason a face drifts across a set.";
 var VIDEO_ROUTING = "In video, a photoreal presenter renders on `google/veo-3.1` (or `google/veo-3.1-fast`), never `bytedance/seedance-2.0` \u2014 it refuses photoreal human faces, AI-generated ones included. Scaffolding a video creative: `baker canvas scaffold-video \u2026 --real-face`.";
 function castingHints(avatar) {
+  if (avatar.status === "generating" && avatar.needsFace) {
+    return [
+      `The user is picking @${avatar.handle}'s face right now \u2014 portraits are on their screen and nothing renders until they answer. There is NOTHING to wait for and nothing to check: do not poll, do not block on it, do not ask about the face in a question of your own, and do not delete or recreate this avatar. Whatever you do next simply runs after they have chosen.`
+    ];
+  }
   if (avatar.status === "generating") {
     return [
       `Still building \u2014 a ~30s render that settles on its own, and this avatar is castable only once it reads \`ready\`. If the next thing you do needs it (a clip, a still, anything with --avatar), block on it: \`baker avatars get ${avatar.handle} --wait\` returns the moment it is ready. Otherwise do other work first and read it back with \`baker avatars get ${avatar.handle}\`. Never write your own sleep or poll loop, and never end the turn waiting \u2014 the user would have to come back and tell you it is ready.`
@@ -30811,17 +30825,18 @@ import { defineCommand as defineCommand98 } from "citty";
 // src/commands/avatars/wait.ts
 var WAIT_TIMEOUT_MS = 9e4;
 var WAIT_INTERVAL_MS = 3e3;
-function shouldKeepWaiting(status, elapsedMs) {
-  if (status === "ready") return { done: true, reason: "ready" };
-  if (status === "error" || status === "archived") return { done: true, reason: "settled" };
+function shouldKeepWaiting(avatar, elapsedMs) {
+  if (avatar.status === "ready") return { done: true, reason: "ready" };
+  if (avatar.status === "error" || avatar.status === "archived") return { done: true, reason: "settled" };
+  if (avatar.needsFace) return { done: true, reason: "needs-face" };
   if (elapsedMs >= WAIT_TIMEOUT_MS) return { done: false, reason: "expired" };
   return { done: false, reason: "building" };
 }
 async function waitForSheet(first, read, sleep4 = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms))) {
   const startedAt = Date.now();
   let latest = first;
-  while (!shouldKeepWaiting(latest.status, Date.now() - startedAt).done) {
-    if (shouldKeepWaiting(latest.status, Date.now() - startedAt).reason === "expired") return latest;
+  while (!shouldKeepWaiting(latest, Date.now() - startedAt).done) {
+    if (shouldKeepWaiting(latest, Date.now() - startedAt).reason === "expired") return latest;
     await sleep4(WAIT_INTERVAL_MS);
     latest = await read();
   }