@figs-so/cli 1.0.0 → 1.2.0

package/SPEC.md

@@ -156,9 +156,9 @@ edge of its autonomy.
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
-| `type` | enum | ✓ | `question` \| `sign-off` — **the type is the answer contract**: *question* wants an answer (an option or free text), *sign-off* wants a verdict (approve / request-changes / reject). (`needs-decision` was renamed `question`; `fyi` was retired — a for-the-record note is a settled report, not an ask; `blocked` is the run's `status`, not an ask type.) |
+| `type` | enum | ✓ | `question` \| `sign-off` — **the type is the answer contract**: *question* wants an answer (an option or free text), *sign-off* wants a verdict (approve / request-changes / reject). (`needs-decision` was renamed `question`; `fyi` was retired — a for-the-record note / assumption / heads-up is a `checkpoint` on the job (or a settled `report`), not an ask; `blocked` is the run's `status`, not an ask type.) |
 | `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the **agent** retracted it; nobody acted) \| `"rejected"` (a human declined it). **Rejected is terminal** on this id — re-raising is a new ask. |
-| `to` | `"manager"` \| `"builder"` | | Who the ask is addressed to: the human accountable for the **work** (`manager`) or for the **machine** (`builder`). Absent = unaddressed. |
+| `to` | `"manager"` \| `"builder"` | | Who the ask is addressed to: the human accountable for the **work** (`manager`) or for the **machine** (`builder`). Absent = unaddressed; `figs ask` **defaults it to `manager`** (the common case) when omitted, so a reader needn't infer. |
 | `title` | string | ✓ | The ask, in one line. |
 | `unit` | string | | The `Unit.id` this concerns. |
 | `run` | string | | The run `id` this ask was raised during. **Optional** — asks also arise outside runs. |
@@ -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

@@ -89,10 +89,11 @@ const COMMANDS = {
     eg: "figs status --json",
   },
   login: {
-    args: "[<token>]",
-    flags: [],
+    args: "[<token>] [--force]",
+    flags: ["--force"],
     desc: "log in — browser device-flow, or save a pasted token",
     more: [
+      "already logged in? it's a no-op that points you to `figs link` — pass --force to log in again.",
       "no arg → device flow: opens a browser for a human to approve (you never see the token).",
       "<token> → save a token you already have to ~/.figs/credentials.json.",
     ],
@@ -279,12 +280,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",
   },
@@ -842,6 +847,17 @@ async function login(token) {
     return
   }
 
+  // Already logged in? Don't start a needless device flow — it strands a cold/headless
+  // agent with no human to approve. Token presence is enough to short-circuit; a stale
+  // token surfaces on the next link/push. `--force` re-runs the flow deliberately.
+  if (!hasFlag("--force") && getToken()) {
+    console.log(`figs: ✓ already logged in to ${originOf(resolveEndpoint())}`)
+    console.log(
+      "        `figs status` for details · `figs link` to connect a workspace · `figs login --force` to log in again",
+    )
+    return
+  }
+
   const start = await request("POST", "/api/device/start")
   if (!start.ok) die(`could not start login (${start.status})`)
   const d = start.data
@@ -1820,6 +1836,14 @@ async function reportCmd() {
   // Announce new-vs-fold only for an explicit --id — that's where a typo means
   // "I meant to continue a job but opened a sibling" (auto-ids are always new).
   if (idGiven) announceFold("job", id, isNew, " (settled)")
+  // The "why it started": a born-settled job that never checkpointed still shows
+  // "triggered by …" in the manager's timeline when --trigger is set. Nudge it
+  // only on a fresh job (never on a fold/continuation — that would cry wolf).
+  if (isNew && !trigger) {
+    console.log(
+      `figs:   tip: \`--trigger '<what set this in motion>'\` records the "why" — your manager sees it on the job's timeline`,
+    )
+  }
   // Teaching, never a gate: a settled job with open asks citing it is the
   // normal tail-of-job pattern (the ask owns the waiting) — but if the job's
   // OUTCOME depends on an answer, in-flight is the honest state. Local fold
@@ -1883,6 +1907,11 @@ async function checkpointCmd() {
     console.log(
       `figs:   new job opened: ${id} (in flight) — checkpoint as you go; \`figs report --id ${id}\` settles it`,
     )
+    if (!trigger) {
+      console.log(
+        `figs:   tip: add \`--trigger '<what set this in motion>'\` so your manager sees why this job started`,
+      )
+    }
   } else if (settledBefore) {
     console.warn(
       `figs: ! reopening a settled job (${id}) — continue only if it's truly the same job; new work wants a new id`,
@@ -1933,6 +1962,10 @@ async function askCmd() {
     const v = flag(f)
     if (v) ask[k] = v
   }
+  // Default an unaddressed ask to the manager (the work-accountable human) — the common
+  // case; `--to builder` is the explicit exception. Saves the reader from inferring ("guess").
+  // (Hand-authored JSONL may still omit `to` → unaddressed; the verb is sugar that defaults.)
+  if (!ask.to) ask.to = "manager"
   const options = flagAll("--option")
   if (options.length) ask.options = options
   for (const o of ask.options ?? []) {
@@ -2135,6 +2168,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 +2188,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 +2203,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.2.0",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {