@figs-so/cli 1.1.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. |

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.",
     ],
@@ -846,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
@@ -1824,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
@@ -1887,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`,
@@ -1937,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 ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "1.1.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": {