npm - @animaapp/cli - Versions diffs - 0.6.0 → 0.7.0 - Mend

@animaapp/cli 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -38,7 +38,8 @@ Every command runs as a **scoped agent identity**: it acts only within the
 workspaces and capabilities a human approved, and your team can see and
 **revoke** it at any time. The CLI renews it in the background; after a few
 months the consent reaches its renewal limit and a human approves again. You get
-that identity one of three ways — the third also covers the case where you have no human to ask yet.
+that identity one of four ways. Door 3 is the usual one — you lead with
+something to show, and it needs neither a token nor an account on their side.
 ### 1. Device login — `anima login`
@@ -91,30 +92,53 @@ Resolution priority: `ANIMA_API_TOKEN` env var → stored credentials file → e
 ### 3. Create first, hand off later — anonymous artifacts
-When there is **no human available yet** and no token, you can still put work on
-AgentGrid. Create an artifact anonymously over REST (the CLI needs an identity,
-so this one call is plain `curl`), then hand it to a human when they appear:
+This is the flow where **you** lead: no token, and a human who needs no
+AgentGrid account until the moment they claim. Two commands:
 ```bash
-curl -s -X POST "https://public-api.animaapp.com/v1/generationSessions" \
-  -H 'Content-Type: application/json' \
-  -d '{"type":"import","name":"My project","clientName":"Claude Code",
-       "files":{"index.html":"<!doctype html><h1>hi</h1>"}}'
+# 1. Create it. Prints claimUrl — send your human that link.
+anima create --anonymous -t import --from ./my-project \
+  --client-name "Claude Code" --json
+# 2. Wait for them to claim it, then store the credentials that grants.
+anima login --handoff --json
+```
+`create --anonymous` needs no credential at all. It returns a `claimUrl` for
+your human, and a **`handoffToken`** for you. The token has two uses:
+```bash
+anima login --handoff <token>                       # log in, once they claim it
+anima create --anonymous --handoff <token> --from … # another artifact, same claim
 ```
+The CLI stores the token, so both commands default to your last one and you can
+leave `<token>` off. Keep it yourself if this machine's config will not outlive
+the process — it is delivered exactly once and can never be re-fetched. Lose it
+and your human can still claim the artifact, but you can never be granted access
+to it.
+Once a claim window closes unclaimed, the next `create --anonymous` just starts
+a fresh one.
 **Send `clientName` — say what product you are** (`"Claude Code"`, `"Cursor"`,
 …), the same name you would pass to `login --client-name`. The human sees it on
 the claim page and it becomes the agent name they approve; without it they are
 asked to invent a name for an artifact they did not create. Display-only, never
 verified, ≤120 characters.
-The response returns a claim link for your human plus a `handoffToken` for you.
-The token does **not** claim anything — it groups further anonymous creates into
-the same handoff, and you poll `POST /oauth/token` with it
-(`grant_type=urn:animaapp:params:oauth:grant-type:handoff_token`) until the
-human claims, at which point the poll returns your agent token. Store it and use
-it as `ANIMA_API_TOKEN` (door 2) for every command after that. Anonymous
-artifacts are read-only and expire in 24h if nobody claims them.
+`login --handoff` blocks until the claim lands. Background it if you have other
+work, and check the state whenever you like:
+```bash
+anima login --handoff --json > anima-login.json &
+anima auth --status --json     # pendingHandoff.state: awaiting_claim | expired
+```
+Anonymous artifacts are read-only and expire in 24h if nobody claims them. The
+handoff token does **not** claim anything — the human never needs it, and never
+gets it. A claim without agent access grants no token, and `login --handoff`
+says so rather than polling forever.
 ### Which do I use?
@@ -124,7 +148,8 @@ artifacts are read-only and expire in 24h if nobody claims them.
 | Interactive agent, human nearby | `anima login` — show the URL + code, human approves on any device |
 | Headless agent, human reachable | `anima login --json` — relay the `verification_required` event, polling finishes automatically |
 | Fully headless / CI, no human | set `ANIMA_API_TOKEN` — no login step |
-| No human *yet*, nothing to authenticate with | create anonymously with `clientName`, send the claim link, poll for the token |
+| You want to lead: share something first, no account needed on their side | `anima create --anonymous …` → send `claimUrl` → `anima login --handoff` |
+| Your human led: they sent you an invite link to join | `anima login --invite <url-or-code>` — one exchange, no approval step |
 ---
@@ -163,10 +188,13 @@ npx @animaapp/cli@latest login --client-name "My CI Agent"   # label on the cons
 npx @animaapp/cli@latest login --no-open                      # don't auto-open the browser
 npx @animaapp/cli@latest login --print-mcp-config             # also emit an MCP server config
 npx @animaapp/cli@latest login --invite <url-or-code>         # redeem a pre-approved invite — no approval step
+npx @animaapp/cli@latest login --handoff                      # wait for a claim on your anonymous artifact
+npx @animaapp/cli@latest login --handoff <token>              # ...or name the token explicitly
 ```
 | Option | Description | Default |
 |--------|-------------|---------|
+| `--handoff [token]` | Log in with the handoff token from an anonymous create. Waits until a human claims the artifact, then stores the credentials their claim grants — same store as every other door. Defaults to your last one. Blocks; background it with `&` and watch `auth --status`. Stops with a clear message if the window closes unclaimed, or if the human claimed without granting agent access | — |
 | `--invite <url-or-code>` | Redeem an invite link (`…/invite/<code>.md`) or bare code. The human already approved when minting the invite, so there is no verification step — one call and you're connected. The invite URL's origin is persisted as the `api-url`, so follow-up commands target the right server with no flags | — |
 | `--client-name <name>` | How the CLI appears on the consent screen | `AgentGrid CLI` |
 | `--no-open` | Don't try to open the verification page in a browser | — |
@@ -197,6 +225,7 @@ npx @animaapp/cli@latest create -t empty --framework react --name "My project"
 npx @animaapp/cli@latest create -t p2c -p "Analytics dashboard with a sidebar"
 npx @animaapp/cli@latest create -t l2c -u https://stripe.com
 npx @animaapp/cli@latest create -t f2c --file-key <key> --nodes 42:15
+npx @animaapp/cli@latest create -t import --from ./my-project --anonymous     # no account — hand off later
 ```
 `-t import` is the one-step upload path: your folder (or .zip) becomes the
@@ -223,7 +252,10 @@ uploaded as an app produce an artifact with nothing to render.
 | `--file-key` | Figma file key or URL | _(f2c)_ |
 | `--nodes` | Figma node IDs, comma-separated | _(f2c)_ |
 | `--figma-token` | Figma PAT (or `FIGMA_TOKEN` env) | _(f2c)_ |
-| `--artifact-type` | `app` (web page, needs an `index.html`), `markdown` (document, needs `.md` files), `asset` (images/video, with a zip) | _inferred from your files_ |
+| `--artifact-type` | `app` (web page, needs an `index.html`), `markdown` (document, needs `.md` files) | _inferred from your files_ |
+| `--anonymous` | Create with no account (`-t import` only). Returns `claimUrl` for your human and a `handoffToken` for you | off |
+| `--handoff <token>` | Add this artifact to an existing claim (`--anonymous` only), so one link covers them all | _your last one_ |
+| `--client-name` | Who to credit as the creator on the claim page (`--anonymous` only) | `AgentGrid CLI` |
 | `--framework` | `react`, `html` — apps only | `react` |
 | `--styling` | `tailwind`, `css`, `plain_css`, `css_modules`, `inline_styles`¹ | `tailwind` |
 | `--language` | `typescript`, `javascript` | `typescript` (react) |
@@ -357,11 +389,15 @@ The API URL resolves in this order: **`--api-url` flag → `ANIMA_API_URL` env
 ### `auth` — inspect or manage credentials
 ```bash
-npx @animaapp/cli@latest auth --status            # token type + expiry
+npx @animaapp/cli@latest auth --status            # token type + expiry, and any pending claim
 npx @animaapp/cli@latest auth --figma-token <T>   # save a Figma token for codegen / f2c
 npx @animaapp/cli@latest auth --logout            # alias for `anima logout`
 ```
+`--status` also reports a handoff waiting to be claimed — including when you are
+not connected yet, which is exactly when you want to ask. `pendingHandoff.state`
+is `awaiting_claim` or `expired`, alongside the `claimUrl` to re-send.
 ---
 ## Global flags

package/dist/index.js CHANGED Viewed

@@ -13,6 +13,7 @@ import path from "path";
 import os from "os";
 var CONFIG_DIR = path.join(os.homedir(), ".config", "anima");
 var CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+var HANDOFF_FILE = path.join(CONFIG_DIR, "handoff.json");
 function classifyCredentials() {
   let parsed;
   try {
@@ -56,14 +57,17 @@ function saveFigmaToken(figmaToken) {
   write({ ...existing ?? {}, figmaToken });
 }
 function write(credentials) {
-  const merged = { ...credentials };
+  writeSecretJson(CREDENTIALS_FILE, { ...credentials });
+}
+function writeSecretJson(file, data) {
+  const merged = { ...data };
   for (const key of Object.keys(merged)) {
     if (merged[key] === void 0) delete merged[key];
   }
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  const tmp = `${CREDENTIALS_FILE}.${process.pid}.tmp`;
+  const tmp = `${file}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + "\n", { mode: 384 });
-  fs.renameSync(tmp, CREDENTIALS_FILE);
+  fs.renameSync(tmp, file);
 }
 function deleteCredentials() {
   try {
@@ -76,8 +80,35 @@ function deleteCredentials() {
     return false;
   }
 }
+function savePendingHandoff(pending) {
+  writeSecretJson(HANDOFF_FILE, { ...pending });
+}
+function readPendingHandoff() {
+  try {
+    if (!fs.existsSync(HANDOFF_FILE)) return null;
+    const parsed = JSON.parse(fs.readFileSync(HANDOFF_FILE, "utf-8"));
+    const required2 = ["handoffToken", "sessionId", "claimUrl", "claimableUntil", "apiUrl"];
+    if (required2.some((field) => typeof parsed[field] !== "string")) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function clearPendingHandoff() {
+  try {
+    if (!fs.existsSync(HANDOFF_FILE)) return false;
+    fs.unlinkSync(HANDOFF_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getHandoffPath() {
+  return HANDOFF_FILE;
+}
 function clearStorage() {
   const had = deleteCredentials();
+  clearPendingHandoff();
   try {
     if (fs.existsSync(CONFIG_DIR) && fs.readdirSync(CONFIG_DIR).length === 0) {
       fs.rmdirSync(CONFIG_DIR);
@@ -734,6 +765,51 @@ function parsePlaygroundUrl(input) {
   }
 }
+// src/api/anonymousCreate.ts
+async function createAnonymousArtifact(request, fetchFn = fetch) {
+  const url = `${request.apiUrl.replace(/\/$/, "")}/v1/generationSessions`;
+  const body = {
+    type: "import",
+    ...request.files ? { files: request.files } : {},
+    ...request.zipUploadId ? { zipUploadId: request.zipUploadId } : {},
+    ...request.framework ? { framework: request.framework } : {},
+    ...request.artifactType ? { artifactType: request.artifactType } : {},
+    ...request.name ? { name: request.name } : {},
+    ...request.handoffToken ? { handoffToken: request.handoffToken } : {},
+    ...request.clientName ? { clientName: request.clientName } : {}
+  };
+  logEvent("anonymous_create_request", { url, type: "import", artifactType: request.artifactType });
+  const response = await fetchFn(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const payload = await response.json().catch(() => ({}));
+  logEvent("anonymous_create_response", { url, status: response.status, error: payload.error });
+  if (!response.ok || payload.success !== true) {
+    const message = typeof payload.reason === "string" && payload.reason || typeof payload.error === "string" && payload.error || `Anonymous create failed (HTTP ${response.status})`;
+    const nextSteps = typeof payload.nextSteps === "string" ? payload.nextSteps : void 0;
+    throw apiError(nextSteps ? `${message}
+${nextSteps}` : message, payload);
+  }
+  for (const field of ["sessionId", "handoffToken", "claimUrl", "claimableUntil"]) {
+    if (typeof payload[field] !== "string") {
+      throw apiError(`The API's create response is missing \`${field}\`.`, payload);
+    }
+  }
+  return payload;
+}
+async function getAnonymousZipUploadUrl(apiUrl, fetchFn = fetch) {
+  const url = `${apiUrl.replace(/\/$/, "")}/v1/generationSessions/zip-upload-url`;
+  const response = await fetchFn(url, { method: "POST" });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || payload.success !== true || typeof payload.uploadUrl !== "string") {
+    const message = typeof payload.reason === "string" && payload.reason || typeof payload.error === "string" && payload.error || `Could not get a zip upload URL (HTTP ${response.status})`;
+    throw apiError(message, payload);
+  }
+  return { zipUploadId: payload.zipUploadId, uploadUrl: payload.uploadUrl };
+}
 // src/commands/create.ts
 var createCommand = new Command("create").description(
   "Create an artifact from your own code: empty for code you'll push (instant) or import your existing code (instant). Also supports AI generation: p2c/l2c/f2c (3-7 min)."
@@ -746,13 +822,23 @@ var createCommand = new Command("create").description(
 ).option("--styling <style>", "tailwind | css | plain_css | css_modules | inline_styles", "tailwind").option("--language <lang>", "typescript | javascript").option("--ui-library <lib>", "mui | antd | shadcn | clean_react").option("--guidelines <text>", "Additional constraints (p2c only)").option(
   "--artifact-type <kind>",
   "app | markdown \u2014 what the artifact IS. app (default) needs an index.html; markdown needs .md files"
-).option("--name <name>", "Project name (empty/import only)").option("--from <path>", "Folder or .zip with your project (import only) \u2014 becomes the first commit").option("--json", "Output as JSON").option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
+).option("--name <name>", "Project name (empty/import only)").option("--from <path>", "Folder or .zip with your project (import only) \u2014 becomes the first commit").option(
+  "--anonymous",
+  "Create without an account (import only). Returns a claim link to send a human, and a handoff token to log in with once they claim it"
+).option(
+  "--handoff <token>",
+  "Add this artifact to an existing claim (--anonymous only), so one claim link covers them all. Defaults to the token from your last anonymous create"
+).option("--client-name <name>", "How this CLI is credited as the creator of an anonymous artifact", "AgentGrid CLI").option("--json", "Output as JSON").option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
   try {
     const type = opts.type;
     validateCreateOptions(type, opts);
+    if (opts.anonymous) {
+      await runAnonymousCreate(opts, mode, progress);
+      return;
+    }
     const auth = await resolveAuth(opts.apiUrl);
     const figmaToken = type === "f2c" ? resolveFigmaToken(opts, auth.figmaToken) : void 0;
     const args = buildCreateArgs(type, opts);
@@ -856,6 +942,88 @@ ${result.nextSteps}` : message, result);
     throw err;
   }
 });
+async function runAnonymousCreate(opts, mode, progress) {
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  progress.start("Collecting project files...");
+  const source = collectProjectSource(opts.from);
+  let files;
+  let zipUploadId;
+  if (source.kind === "files") {
+    files = source.files;
+  } else {
+    progress.update(`Uploading project zip (${source.reason})...`);
+    const grant = await getAnonymousZipUploadUrl(apiUrl);
+    const putResponse = await fetch(grant.uploadUrl, {
+      method: "PUT",
+      body: new Uint8Array(source.buffer)
+    });
+    if (!putResponse.ok) {
+      throw apiError(`Zip upload failed: HTTP ${putResponse.status}`, { status: putResponse.status });
+    }
+    zipUploadId = grant.zipUploadId;
+  }
+  progress.start("Creating anonymous artifact...");
+  const request = {
+    apiUrl,
+    files,
+    zipUploadId,
+    ...opts.framework && opts.artifactType !== "markdown" ? { framework: opts.framework } : {},
+    ...opts.artifactType ? { artifactType: opts.artifactType } : {},
+    ...opts.name ? { name: opts.name } : {},
+    clientName: opts.clientName
+  };
+  const reusable = opts.handoff ? { handoffToken: opts.handoff } : livePendingHandoff();
+  const result = reusable ? await createAnonymousArtifact({ ...request, handoffToken: reusable.handoffToken }).catch((err) => {
+    if (!isHandoffTokenInvalid(err)) throw err;
+    clearPendingHandoff();
+    progress.update("Previous claim is no longer open \u2014 starting a new one...");
+    return createAnonymousArtifact(request);
+  }) : await createAnonymousArtifact(request);
+  const claimUrl = result.claimUrl;
+  savePendingHandoff({
+    handoffToken: result.handoffToken,
+    sessionId: result.sessionId,
+    claimUrl,
+    claimableUntil: result.claimableUntil,
+    apiUrl
+  });
+  progress.succeed("Artifact created!");
+  if (mode === "pretty") {
+    printSessionResult({ sessionId: result.sessionId, playgroundUrl: result.previewUrl });
+    console.log("  Send your human this link to claim it:");
+    console.log(`    ${chalk2.cyan.underline(claimUrl)}`);
+    console.log();
+    console.log(`  Claimable until ${result.claimableUntil}. Until then the artifact is read-only.`);
+    console.log(`  Then run ${chalk2.cyan("anima login --handoff")} to pick up your credentials.`);
+    if (result.notes) console.log(`  Note: ${result.notes}`);
+    console.log();
+  } else {
+    outputResult(mode, {
+      success: true,
+      sessionId: result.sessionId,
+      previewUrl: result.previewUrl,
+      claimUrl,
+      claimableUntil: result.claimableUntil,
+      // Returned, not just stored: it is delivered exactly once and can never
+      // be re-fetched, so a caller whose config does not outlive the process
+      // would otherwise lose the only route to a credential.
+      handoffToken: result.handoffToken,
+      handoffStored: getHandoffPath(),
+      ...result.fileCount !== void 0 ? { fileCount: result.fileCount } : {},
+      ...result.skippedFiles?.length ? { skippedFiles: result.skippedFiles } : {},
+      ...result.notes ? { notes: result.notes } : {},
+      nextSteps: `Send claimUrl to your human \u2014 that is the link that transfers the artifact to them. handoffToken is yours, never theirs: use it to log in (\`anima login --handoff\`, which waits until they claim and then stores your credentials), or to add more artifacts to the same claim (\`anima create --anonymous --handoff <token>\`). Run the login in the background if you have other work.`
+    });
+  }
+}
+function livePendingHandoff() {
+  const pending = readPendingHandoff();
+  if (!pending) return null;
+  return new Date(pending.claimableUntil).getTime() > Date.now() ? pending : null;
+}
+function isHandoffTokenInvalid(err) {
+  return err instanceof CliError && /handoff_token_invalid/.test(JSON.stringify(err.detail ?? ""));
+}
 function validateCreateOptions(type, opts) {
   if (!["empty", "import", "p2c", "l2c", "f2c"].includes(type)) {
     throw validationError(`Invalid type "${type}". Must be empty, import, p2c, l2c, or f2c.`);
@@ -869,11 +1037,27 @@ function validateCreateOptions(type, opts) {
   if (type === "f2c" && !opts.fileKey) {
     throw validationError("--file-key is required for f2c type");
   }
-  if (type === "empty" && !opts.framework) {
+  if (type === "empty" && !opts.framework && opts.artifactType !== "markdown") {
     throw validationError(
       "--framework is required for type empty \u2014 html for plain HTML/CSS/JS, react for React (declare react if you will push React code)"
     );
   }
+  if (opts.artifactType && !["app", "markdown"].includes(opts.artifactType)) {
+    throw validationError(
+      `Invalid --artifact-type "${opts.artifactType}". Must be app or markdown.`
+    );
+  }
+  if (opts.handoff && !opts.anonymous) {
+    throw validationError(
+      "--handoff only applies to --anonymous creates \u2014 it adds the new artifact to an existing claim. An authenticated create already belongs to your team."
+    );
+  }
+  if (opts.anonymous && type !== "import") {
+    throw validationError(
+      `--anonymous only works with -t import (got "${type}"). Anonymous artifacts are created FROM code you already have: there is no way to push to an empty one, and AI generation needs an account.
+Log in first for the other types: anima login`
+    );
+  }
   if (type === "import" && !opts.from) {
     throw validationError("--from <folder|zip> is required for type import \u2014 the path to the project to import");
   }
@@ -894,7 +1078,10 @@ function buildCreateArgs(type, opts) {
   if (type === "empty" || type === "import") {
     return {
       type,
-      ...opts.framework ? { framework: opts.framework } : {},
+      // A document has no framework to build with, and declaring one on an
+      // import is what made markdown artifacts render as empty apps.
+      ...opts.framework && opts.artifactType !== "markdown" ? { framework: opts.framework } : {},
+      ...opts.artifactType ? { artifactType: opts.artifactType } : {},
       ...opts.name ? { name: opts.name } : {}
     };
   }
@@ -1379,13 +1566,84 @@ async function loginWithInvite(options) {
   return session;
 }
+// src/auth/handoff.ts
+var HANDOFF_GRANT_TYPE = "urn:animaapp:params:oauth:grant-type:handoff_token";
+var POLL_INTERVAL_SECONDS = 30;
+var defaultSleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function loginWithHandoff(options) {
+  const fetchFn = options.fetchFn ?? fetch;
+  const sleep = options.sleepFn ?? defaultSleep2;
+  const now = options.nowFn ?? Date.now;
+  const base = options.apiUrl.replace(/\/$/, "");
+  const tokenUrl = `${base}/oauth/token`;
+  const deadline = resolveDeadline(options.claimableUntil, now);
+  let intervalMs = POLL_INTERVAL_SECONDS * 1e3;
+  for (; ; ) {
+    const response = await fetchFn(tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: HANDOFF_GRANT_TYPE,
+        handoff_token: options.handoffToken
+      }).toString()
+    });
+    const body = await response.json().catch(() => ({}));
+    logEvent("handoff_token_poll", { status: response.status, error: body.error });
+    if (response.ok && typeof body.access_token === "string") {
+      const session = agentSessionFromTokenResponse(body);
+      persistAgentSession(session);
+      clearPendingHandoff();
+      return session;
+    }
+    switch (body.error) {
+      case "authorization_pending":
+        break;
+      case "slow_down":
+        intervalMs += 5e3;
+        break;
+      case "expired_token":
+        clearPendingHandoff();
+        throw authError(
+          "This handoff token can no longer be redeemed \u2014 the claim window closed unclaimed, the token was already redeemed, or the human claimed the artifact without granting agent access. Share again with a new `anima create --anonymous` \u2014 or, if they claimed it and want you to keep editing, have them grant your agent from the artifact page."
+        );
+      default:
+        throw new CliError(
+          "API_ERROR",
+          `Unexpected token response: ${body.error ?? `HTTP ${response.status}`}`,
+          EXIT_CODES.API_ERROR
+        );
+    }
+    const remainingMs = deadline.getTime() - now();
+    if (remainingMs <= 0) break;
+    const waitMs = Math.min(intervalMs, remainingMs);
+    options.onPending?.({ nextPollInSeconds: Math.round(waitMs / 1e3), deadline });
+    await sleep(waitMs);
+  }
+  throw authError(
+    "The claim window closed before anyone claimed the artifact. Share again with a new `anima create --anonymous` \u2014 the previous one has expired and can no longer be claimed."
+  );
+}
+var FALLBACK_POLL_WINDOW_MS = 24 * 60 * 60 * 1e3;
+function resolveDeadline(claimableUntil, now) {
+  const parsed = claimableUntil ? new Date(claimableUntil) : null;
+  if (parsed && !Number.isNaN(parsed.getTime())) return parsed;
+  return new Date(now() + FALLBACK_POLL_WINDOW_MS);
+}
 // src/commands/login.ts
-var loginCommand = new Command6("login").description("Log in via the device flow, or redeem a pre-approved invite with --invite").option("--invite <url-or-code>", "Redeem an invite link (\u2026/invite/<code>.md) or bare code \u2014 no approval step").option("--client-name <name>", "How this CLI appears on the consent screen", "AgentGrid CLI").option("--no-open", "Do not try to open the verification page in a browser").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").option(
+var loginCommand = new Command6("login").description("Log in via the device flow, redeem an invite with --invite, or finish an anonymous create with --handoff").option("--invite <url-or-code>", "Redeem an invite link (\u2026/invite/<code>.md) or bare code \u2014 no approval step").option(
+  "--handoff [token]",
+  "Log in with the handoff token from an anonymous create. Waits until a human claims the artifact. Defaults to your last one"
+).option("--client-name <name>", "How this CLI appears on the consent screen", "AgentGrid CLI").option("--no-open", "Do not try to open the verification page in a browser").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").option(
   "--print-mcp-config",
   "After login, also print an MCP server config (URL only \u2014 the client authorizes itself) to paste into an MCP-capable agent"
 ).action(async (opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
+  if (opts.handoff) {
+    await runHandoffLogin(opts, mode);
+    return;
+  }
   if (opts.invite) {
     const inviteOrigin = parseInvite(opts.invite).origin;
     const apiUrl2 = opts.apiUrl ? resolveApiUrl(opts.apiUrl) : inviteOrigin ?? resolveApiUrl();
@@ -1502,6 +1760,89 @@ var loginCommand = new Command6("login").description("Log in via the device flow
     throw err;
   }
 });
+async function runHandoffLogin(opts, mode) {
+  const explicitToken = typeof opts.handoff === "string" ? opts.handoff : void 0;
+  const stored = readPendingHandoff();
+  const pending = stored && (!explicitToken || stored.handoffToken === explicitToken) ? stored : explicitToken ? { handoffToken: explicitToken, sessionId: "", claimUrl: "", claimableUntil: "", apiUrl: resolveApiUrl() } : null;
+  if (!pending) {
+    const message = "No handoff token. Pass one (`anima login --handoff <token>`), or run `anima create --anonymous -t import --from <path>` to get one. (Already logged in another way? `anima auth --status`.)";
+    if (mode === "pretty") {
+      printError(message);
+    } else {
+      outputError(mode, { code: "VALIDATION_ERROR", message });
+    }
+    process.exit(1);
+  }
+  const apiUrl = opts.apiUrl ? resolveApiUrl(opts.apiUrl) : pending.apiUrl;
+  try {
+    if (mode === "pretty") {
+      console.log();
+      printInfo("Waiting for a human to claim the artifact:");
+      if (pending.claimUrl) {
+        console.log();
+        console.log(`    ${chalk5.cyan.underline(pending.claimUrl)}`);
+      }
+      console.log();
+      printInfo(
+        pending.claimableUntil ? `Claimable until ${pending.claimableUntil}. Ctrl-C to stop \u2014 this does not cancel the claim.` : "Ctrl-C to stop \u2014 this does not cancel the claim."
+      );
+    } else {
+      process.stderr.write(
+        JSON.stringify({
+          event: "claim_required",
+          ...pending.claimUrl ? { claimUrl: pending.claimUrl } : {},
+          ...pending.sessionId ? { sessionId: pending.sessionId } : {},
+          ...pending.claimableUntil ? { claimableUntil: pending.claimableUntil } : {}
+        }) + "\n"
+      );
+    }
+    const result = await loginWithHandoff({
+      apiUrl,
+      handoffToken: pending.handoffToken,
+      claimableUntil: pending.claimableUntil || void 0
+    });
+    if (readConfig().apiUrl !== apiUrl) {
+      setConfig("api-url", apiUrl);
+    }
+    const mcpConfig = opts.printMcpConfig ? buildMcpConfig(apiUrl) : void 0;
+    if (mode === "pretty") {
+      printSuccess("Claimed \u2014 you're connected!");
+      printKeyValue("Credentials", getCredentialsPath());
+      printKeyValue("Agent", result.agentId);
+      printKeyValue("Team ID", result.teamId);
+      printKeyValue("Token expires", result.expiresAt);
+      printInfo("The artifact is now editable: anima get-git-token " + pending.sessionId);
+      if (mcpConfig) {
+        console.log();
+        printInfo("MCP server config \u2014 your client will prompt to authorize on first use:");
+        console.log();
+        console.log(JSON.stringify(mcpConfig, null, 2));
+      }
+    } else {
+      outputResult(mode, {
+        success: true,
+        action: "logged_in",
+        via: "handoff",
+        tokenType: "agent",
+        agentId: result.agentId,
+        teamId: result.teamId,
+        expiresAt: result.expiresAt,
+        sessionId: pending.sessionId,
+        ...mcpConfig ? { mcpConfig } : {}
+      });
+    }
+  } catch (err) {
+    if (err instanceof CliError) {
+      if (mode === "pretty") {
+        printError(err.message);
+      } else {
+        outputError(mode, { code: err.code, message: err.message });
+      }
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+}
 function buildMcpConfig(apiUrl) {
   return {
     mcpServers: {
@@ -1544,6 +1885,25 @@ var mcpConfigCommand = new Command7("mcp-config").description("Print an MCP serv
 import { Command as Command8 } from "commander";
 import chalk6 from "chalk";
 var DEFAULT_API_URL2 = "https://api.agentgrid.io";
+function describePendingHandoff(pending, state) {
+  return {
+    state,
+    sessionId: pending.sessionId,
+    claimUrl: pending.claimUrl,
+    claimableUntil: pending.claimableUntil,
+    nextSteps: state === "expired" ? "The claim window closed. Create another artifact, or ask your human for an agent invite: anima login --invite <url-or-code>" : "Send claimUrl to your human, then run `anima login --handoff` to wait for the credentials their claim grants."
+  };
+}
+function printPendingHandoff(pending, state) {
+  console.log();
+  if (state === "expired") {
+    printInfo(`Anonymous artifact ${pending.sessionId} was never claimed \u2014 its window closed at ${pending.claimableUntil}.`);
+    return;
+  }
+  printInfo(`Anonymous artifact ${pending.sessionId} is awaiting a claim (until ${pending.claimableUntil}):`);
+  console.log(`    ${chalk6.cyan.underline(pending.claimUrl)}`);
+  console.log(`  Run ${chalk6.cyan("anima login --handoff")} to wait for it.`);
+}
 var authCommand = new Command8("auth").description("Manage authentication").option("--token <token>", "Store AgentGrid API token").option("--figma-token <token>", "Store Figma personal access token").option("--team-id <teamId>", "Team ID to associate with token").option("--status", "Show current auth status").option("--logout", "Clear stored credentials (alias for `anima logout`)").option("--json", "Output as JSON").option("--api-url <url>", "API base URL", DEFAULT_API_URL2).action(async (opts) => {
   const mode = detectOutputMode(opts);
   try {
@@ -1591,6 +1951,8 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
       return;
     }
     if (opts.status) {
+      const pending = readPendingHandoff();
+      const pendingState = !pending ? void 0 : new Date(pending.claimableUntil).getTime() <= Date.now() ? "expired" : "awaiting_claim";
       try {
         const auth = await resolveAuth(opts.apiUrl);
         const creds = readCredentials();
@@ -1604,6 +1966,7 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
           if (creds?.tokenType === "agent" && creds.expiresAt) printKeyValue("Expires", creds.expiresAt);
           if (auth.teamId) printKeyValue("Team ID", auth.teamId);
           printKeyValue("Figma token", hasFigma ? "configured" : "not set (needed for codegen/f2c)");
+          if (pending) printPendingHandoff(pending, pendingState);
         } else {
           outputResult(mode, {
             success: true,
@@ -1612,12 +1975,22 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
             tokenPreview: auth.token.slice(0, 12) + "..." + auth.token.slice(-4),
             teamId: auth.teamId,
             expiresAt: creds?.tokenType === "agent" ? creds.expiresAt : void 0,
-            figmaToken: hasFigma
+            figmaToken: hasFigma,
+            ...pending ? { pendingHandoff: describePendingHandoff(pending, pendingState) } : {}
           });
         }
       } catch (err) {
         if (err instanceof CliError) {
-          if (mode === "pretty") {
+          if (pending && mode === "pretty") {
+            printInfo("Not connected yet.");
+            printPendingHandoff(pending, pendingState);
+          } else if (pending) {
+            outputResult(mode, {
+              success: true,
+              tokenType: null,
+              pendingHandoff: describePendingHandoff(pending, pendingState)
+            });
+          } else if (mode === "pretty") {
             printError(err.message);
           } else {
             outputError(mode, { code: err.code, message: err.message });
@@ -1632,6 +2005,7 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
       console.log();
       printInfo("Auth commands:");
       console.log(`  ${chalk6.cyan("anima login")}                    Log in (device flow \u2014 approve on any browser)`);
+      console.log(`  ${chalk6.cyan("anima login --handoff")}          Wait for a human to claim your anonymous artifact`);
       console.log(`  ${chalk6.cyan("anima logout")}                   Clear all credentials`);
       console.log(`  ${chalk6.cyan("anima auth --status")}            Check auth status`);
       console.log(`  ${chalk6.cyan("anima auth --figma-token <T>")}   Save Figma token (needed for codegen/f2c)`);