@figs-so/cli 1.0.0 → 1.1.0

package/SPEC.md

@@ -259,7 +259,8 @@ minimum CLI version requires Bearer.)
      "agent":    { /* agent.json */ },
      "runs":     [ /* runs.jsonl     */ ],   // optional
      "asks":     [ /* asks.jsonl     */ ],   // optional
-     "messages": [ /* messages.jsonl */ ]    // optional — transcribed replies the reader lacks
+     "messages": [ /* messages.jsonl */ ],   // optional — transcribed replies the reader lacks
+     "confirmRename": true                   // optional — `figs push --rename`: confirm a real name change
    }
    ```
 2. **Each attached file** → `POST {endpoint}/api/artifacts/upload`, base64-encoded, hash-verified.
@@ -270,7 +271,12 @@ server refuses a fold older than the record's stored close/settle (a stale machi
 and accepts a newer one (a legitimate reopen — the `warn` → `ok` evolution). **A push never re-homes an
 agent:** a `workspaceId` differing from the agent's registered home is rejected `409`
 `{ "error", "code": "agent_moved", "workspaceId"? }`; the agent recovers by setting
-`config.json#workspaceId` to the named workspace and pushing again.
+`config.json#workspaceId` to the named workspace and pushing again. **A push never silently
+re-identifies an agent:** a `name` differing from the one registered for that `agentId` is the
+fingerprint of a copied folder and is rejected `409` `{ "error", "code": "agent_renamed" }` — the
+agent rotates identity (`rm -rf .figs && figs init`) for a genuinely new agent, or sets
+`confirmRename` (`figs push --rename`) once to confirm a real rename. `name` is the signal because a
+copy-to-make-another always renames while role/mandate evolve legitimately; the check is `name` only.
 
 **Down — the reply sync.** Delivery is **agent-pulled**, never pushed into the repo: a reader exposes a
 read returning **this agent's human messages** (answers/verdicts), which the CLI merges into

package/figs.mjs

@@ -279,12 +279,16 @@ const COMMANDS = {
   },
   push: {
     args: "",
-    flags: [],
+    flags: ["--rename"],
     desc: "publish .figs/ — spine to /api/ingest, artifacts to /api/artifacts",
     more: [
       "Idempotent (records fold by id). Exits non-zero if an artifact upload is rejected.",
       "The writing verbs (report/ask/resolve) call this automatically — you only need it",
       "after hand-editing files, after --no-push, or to retry a failed auto-push.",
+      "--rename: confirm a genuine name change on an already-registered agent (one",
+      "time). The server refuses a name that doesn't match the registered one — it's",
+      "the fingerprint of a copied folder; if that's what happened, rotate identity",
+      "instead with `rm -rf .figs && figs init`, don't --rename.",
     ],
     eg: "figs push",
   },
@@ -2135,6 +2139,9 @@ async function doPush() {
   const asks = foldById(readJsonl("asks.jsonl"))
   // Messages are immutable events — sent whole (no fold); the server dedupes by id.
   const messages = readJsonl("messages.jsonl")
+  // One-time confirm that a name change on an already-registered id is a real
+  // rename, not a copied folder (the server's rename guard refuses it otherwise).
+  const confirmRename = hasFlag("--rename")
 
   // Local pre-flight — fail fast, offline, with teaching errors.
   const placeholders = findPlaceholders(agentJson)
@@ -2152,7 +2159,14 @@ async function doPush() {
     res = await fetchT(`${base}/api/ingest`, {
       method: "POST",
       headers: { "content-type": "application/json", ...authHeaders(token) },
-      body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks, messages }),
+      body: JSON.stringify({
+        workspaceId: config.workspaceId,
+        agent,
+        runs,
+        asks,
+        messages,
+        ...(confirmRename ? { confirmRename: true } : {}),
+      }),
     })
   } catch (e) {
     // Network/timeout — transient; the records are safe locally.
@@ -2160,7 +2174,17 @@ async function doPush() {
   }
   const text = await res.text()
   // 4xx = the payload is wrong (re-pushing won't help) → structural; 5xx = transient.
-  if (!res.ok) return fail(`server rejected it (${res.status}): ${text}`, res.status >= 500)
+  // The server's teaching message rides in { error } — surface that, not raw JSON.
+  if (!res.ok) {
+    let detail = text
+    try {
+      const body = JSON.parse(text)
+      if (body?.error) detail = body.error
+    } catch {
+      // non-JSON body — keep the raw text
+    }
+    return fail(`server rejected it (${res.status}): ${detail}`, res.status >= 500)
+  }
   console.log(
     `figs: ✓ pushed ${agent.name ?? agent.id} — ${runs.length} runs, ${asks.length} asks, ${messages.length} messages`,
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {