@figs-so/cli 0.2.0 → 0.2.1

package/README.md

@@ -40,7 +40,9 @@ npx @figs-so/cli@latest push                     # publish → it appears in you
 ```
 
 That's it — your agent now shows up at **[app.figs.so](https://app.figs.so)**. No instrumentation, no
-SDK in your agent's code. From there you decide, deliberately, how much of its real work to surface.
+SDK in your agent's code. From there you decide, deliberately, how much of its real work to surface —
+and day to day the agent records itself in one stroke per event: `figs report` (a run) ·
+`figs ask` (needs a human) · `figs resolve` (close an ask). Each pushes itself.
 
 ## How it works
 
@@ -71,8 +73,11 @@ are shorthand for exactly that (always current, no version drift). Prefer a real
 | `figs login` / `logout` | device-flow browser approve / remove local token |
 | `figs workspaces [--json]` | list your workspaces (create one in the web app) |
 | `figs init [--workspace <slug>]` | generate identity + write `.figs/` (omit the flag: uses your only workspace, else lists them) |
-| `figs doctor` | validate `.figs/` against the contract before pushing |
-| `figs push` | one-way publish of `.figs/` |
+| **`figs report --result "…"`** | record a run — stamps id + timestamp, auto-captures the session trace, `--attach`es artifacts, pushes itself (`--resolves <ask-id>` closes an ask in the same stroke) |
+| **`figs ask <type> --title "…"`** | raise a self-contained ask (`blocked` · `needs-decision` · `sign-off` · `fyi`) — options/details/attachments, pushed so a human sees it |
+| **`figs resolve <ask-id>`** | close an ask — `--chosen` verbatim-checked against its options, `--withdrawn` for the un-ask |
+| `figs push` | the bare transport — the verbs call it automatically; type it yourself after hand-edits or `--no-push` |
+| `figs doctor` | validate `.figs/` against the spec without pushing — the conformance check for hand-authored or non-CLI setups |
 | `figs status [--json]` | login / workspace / agent state |
 | `figs help [<command>]` | usage (`-h`/`--help` on any command; `-v` for version) |
 

package/SPEC.md

@@ -122,7 +122,7 @@ primitive** — the agent reached the edge of its autonomy.
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
 | `type` | enum | ✓ | `blocked` \| `needs-decision` \| `sign-off` \| `fyi`. `fyi` is a non-blocking heads-up (no decision needed). |
-| `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the agent un-asked — no longer needed, nobody acted). |
+| `status` | enum | | `"open"` (default) \| `"resolved"` (the need was met) \| `"withdrawn"` (the **asker** retracted it — no longer needed, nobody acted) \| `"rejected"` (the **answerer** declined it — a human said no; usually born in the reader's UI, but the agent may record an out-of-band rejection too). Three closes, three authors-of-the-ending. **Rejected is terminal** on this id — readers keep it sticky; 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` — e.g. self-edit/logic-change flags). Absent = unaddressed; readers may guess from `type` but must present it as a guess. |
 | `title` | string | ✓ | The ask, in one line. |
 | `unit` | string | | The `Unit.id` this concerns. |
@@ -154,9 +154,11 @@ An ask is the **anchor of a thread whose two halves are owned by different parti
   These are [reserved](#reserved-not-in-v1) in v1 and **never appear in `asks.jsonl`**: nobody
   writes into the other side's record; the two ledgers cross-reference by id.
 
-The full state machine: `open` → *(claimed → answered — human, server-side, reserved)* →
-`resolved` | `withdrawn` *(agent, in `asks.jsonl`)*. In v1 only the agent-owned transitions exist;
-resolution happens in the agent's own workflow.
+The full state machine: `open` → *(answered/verdict — human, server-side)* →
+`resolved` | `withdrawn` *(agent, in `asks.jsonl`)* — plus the one human-side close:
+**`rejected`** (a reject verdict in the reader's UI closes the ask immediately; the agent's
+later resolution append folds onto it without reopening). Today resolution otherwise happens
+in the agent's own workflow; answers flowing back through the reader are arriving incrementally.
 
 ### 6.2 `Resolution` — how an ask closed
 

package/figs.mjs

@@ -142,18 +142,21 @@ const COMMANDS = {
       "verbatim), --detail \"Label=Value\" (repeatable), --attach <file> (repeatable;",
       "for sign-offs attach the exact content for review + a brief: what to do once",
       "approved and what it requires).",
-      "--run <id|last> links the run this came out of (last = newest local run).",
+      "--run <run-id> links the run this came out of — explicit id only (other",
+      "sessions may report concurrently; `figs report` prints the id it wrote).",
       "--stdin reads a full JSON object instead of flags (long texts; attachments still via --attach).",
     ],
-    eg: 'figs ask sign-off --title "Send 10 payment reminders" --attach ./previews.html --run last',
+    eg: 'figs ask sign-off --title "Send 10 payment reminders" --attach ./previews.html --run recon-2026-06',
   },
   resolve: {
-    args: "<ask-id> [--chosen <option>] [--by <who>] [--note <text>] [--withdrawn]",
-    flags: ["--chosen", "--by", "--note", "--withdrawn", "--no-push"],
+    args: "<ask-id> [--chosen <option>] [--by <who>] [--note <text>] [--withdrawn|--rejected]",
+    flags: ["--chosen", "--by", "--note", "--withdrawn", "--rejected", "--no-push"],
     desc: "close an ask — appends the resolution fold line and pushes",
     more: [
       "--chosen must quote one of the ask's options[] verbatim (checked).",
-      "--withdrawn = the ask is no longer needed, nobody acted (don't mark resolved).",
+      "Three closes, by who ended it: resolved (default — the need was met) ·",
+      "--withdrawn (YOU retracted it; nobody acted) · --rejected (a HUMAN declined",
+      "it — record their out-of-band no; rejected is terminal, re-raising = a new ask).",
       "Use `figs report --resolves <ask-id>` instead when a run did the work.",
     ],
     eg: 'figs resolve acme-bridge --chosen "Strip the alpha prefix" --by "Sarah (accounting)"',
@@ -234,7 +237,9 @@ function positional() {
   }
   return undefined
 }
-const BOOLEAN_FLAGS = new Set(["--no-push", "--stdin", "--withdrawn", "--json", "-h", "--help"])
+const BOOLEAN_FLAGS = new Set([
+  "--no-push", "--stdin", "--withdrawn", "--rejected", "--json", "-h", "--help",
+])
 
 /** ISO-8601 with the machine's real UTC offset (never the agent's guess). */
 function nowIso() {
@@ -258,7 +263,7 @@ function genId(prefix) {
 // and flag typos get wrong, with errors that teach the fix.
 const ASK_TYPES = ["blocked", "needs-decision", "sign-off", "fyi"]
 const RUN_STATUSES = ["ok", "warn", "fail"]
-const ASK_STATUSES = ["open", "resolved", "withdrawn"]
+const ASK_STATUSES = ["open", "resolved", "withdrawn", "rejected"]
 const TO_VALUES = ["manager", "builder"]
 const ARTIFACT_EXTS = new Set([
   ".html", ".md", ".txt", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg",
@@ -1099,9 +1104,12 @@ function captureCommit() {
 }
 
 // ---------- the resolution fold (shared by `resolve` and `report --resolves`) -
-function buildResolution(askId, { chosen, by, note, withdrawn }) {
-  if (withdrawn && chosen) {
-    die("--withdrawn and --chosen are mutually exclusive (withdrawn = the ask is no longer needed, nobody acted)")
+function buildResolution(askId, { chosen, by, note, withdrawn, rejected }) {
+  if (withdrawn && rejected) {
+    die("--withdrawn and --rejected are different closes: withdrawn = YOU retracted the ask; rejected = a HUMAN declined it. Pick the one that's true.")
+  }
+  if ((withdrawn || rejected) && chosen) {
+    die(`--chosen marks the need as met — it can't combine with ${withdrawn ? "--withdrawn" : "--rejected"} (use --note for the account)`)
   }
   const asks = foldById(readJsonl("asks.jsonl"))
   const ask = asks.find((a) => a.id === askId)
@@ -1125,10 +1133,14 @@ function buildResolution(askId, { chosen, by, note, withdrawn }) {
   if (by) resolution.by = by
   if (note) resolution.note = note
   // `via` says where the unblock came from; out-of-band human answers are
-  // "human". Set it only when there's evidence of one (a chosen/by), never on
-  // withdrawn (nobody acted — that's the point).
-  if (!withdrawn && (chosen || by)) resolution.via = "human"
-  const line = { id: askId, status: withdrawn ? "withdrawn" : "resolved" }
+  // "human". A rejection is inherently a human's call; otherwise set it only
+  // when there's evidence of one (a chosen/by), never on withdrawn (nobody
+  // acted — that's the point).
+  if (rejected || (!withdrawn && (chosen || by))) resolution.via = "human"
+  const line = {
+    id: askId,
+    status: withdrawn ? "withdrawn" : rejected ? "rejected" : "resolved",
+  }
   if (Object.keys(resolution).length) line.resolution = resolution
   return { line, warnings }
 }
@@ -1234,12 +1246,11 @@ async function askCmd() {
   if (details.length) ask.details = [...(base.details ?? []), ...details]
   const runRef = flag("--run")
   if (runRef === "last") {
-    const runs = foldById(readJsonl("runs.jsonl"))
-    if (!runs.length) {
-      die("--run last: no runs in the local runs.jsonl — `figs report` one first, or pass an explicit id")
-    }
-    ask.run = runs.reduce((a, b) => ((a.ts ?? "") > (b.ts ?? "") ? a : b)).id
-  } else if (runRef) ask.run = runRef
+    // Deliberately unsupported: concurrent sessions of the same agent report
+    // runs in parallel — "the latest run" may be someone else's. Explicit only.
+    die('--run takes the explicit run id (no "last" — another session may have reported since); `figs report` prints the id of what it wrote')
+  }
+  if (runRef) ask.run = runRef
   const attached = attachFiles(flagAll("--attach"))
   if (attached.length) {
     ask.refs = [...(base.refs ?? []), ...attached.map((n) => ({ label: n, artifact: n }))]
@@ -1274,6 +1285,7 @@ async function resolveCmd() {
     by: flag("--by"),
     note: flag("--note"),
     withdrawn: hasFlag("--withdrawn"),
+    rejected: hasFlag("--rejected"),
   })
   for (const w of warnings) console.warn(`figs: ! ${w}`)
   appendJsonl("asks.jsonl", line)

package/package.json

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