@figs-so/cli 0.3.0 → 0.6.0

package/README.md

@@ -73,8 +73,9 @@ 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 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 inbox [<ask-id>]`** | start every session here — your humans' answers/verdicts, verbatim, with the next command per ask; with an id: the full zero-context handoff package (thread + artifacts restored) |
+| **`figs report --result '…'`** | record a run — **one job, one stable `--id`** (re-reporting an id folds progress onto that job's row); stamps the timestamp, `--attach`es artifacts, pushes itself |
+| **`figs ask <type> --title '…'`** | raise a self-contained ask (`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 |

package/SPEC.md

@@ -82,7 +82,12 @@ Use **`steps`** *or* **`responsibilities`** depending on shape — a fixed pipel
 
 ## 5. `runs.jsonl` — activity
 
-One JSON object per line (JSON Lines). Each is something the agent did.
+One JSON object per line (JSON Lines). **One record = one job** — a unit of work the agent's
+*manager* would recognize ("recon — Acme — November"), under a **stable, meaningful id**
+(`recon-acme-2026-11`); the runs list reads as the job list. Records **fold by `id`** (same
+merge as asks): re-reporting a job's id layers progress onto its row (`status` evolves
+blocked-ish `warn` → `ok`) — sittings/sessions are agent plumbing and never mint records.
+Closing an ask is **not** a job: that's a `resolution` in `asks.jsonl` (§6), never a run.
 
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
@@ -93,7 +98,6 @@ One JSON object per line (JSON Lines). Each is something the agent did.
 | `result` | string | | One-line outcome. |
 | `status` | `"ok"` \| `"warn"` \| `"fail"` | | Default `"ok"`. **Outcome, never lifecycle** — a run is a complete fact when reported; nothing "closes" a run. |
 | `artifacts` | string[] | | File names under `artifacts/` to attach. Singular `artifact` (string) remains valid shorthand for one — readers normalize to the array (same pattern as `resolution`'s bare-string shorthand). |
-| `resolves` | string | | The ask `id` this run executes/closes (the agent did the answered/approved thing and is reporting back — see [§6.1](#61-lifecycle--two-ledgers-split-by-author)). |
 | `session` | `Session` | | Where/how this ran (see [§5.1](#51-session--runtime-metadata-optional)). Optional, self-reported. |
 
 ### 5.1 `Session` — runtime metadata (optional)
@@ -121,7 +125,7 @@ primitive** — the agent reached the edge of its autonomy.
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
-| `type` | enum | ✓ | `blocked` \| `needs-decision` \| `sign-off` \| `fyi`. `fyi` is a non-blocking heads-up (no decision needed). |
+| `type` | enum | ✓ | `needs-decision` \| `sign-off` \| `fyi` — **the type is the answer contract**: *needs-decision* wants an answer (an option or free text), *sign-off* wants a verdict (approve / request changes / reject), *fyi* wants nothing (a for-the-record note; readers never count it as needing a human). `blocked` was **folded into `needs-decision`** (2026-06, pre-launch in-place edit): a stuck job is the *run's* `status`, not an ask type. |
 | `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. |
@@ -129,7 +133,7 @@ primitive** — the agent reached the edge of its autonomy.
 | `run` | string | | The run `id` this ask was raised during (the work that surfaced it). **Optional** — asks also arise outside runs (a self-found issue, expired credentials). |
 | `found` | string | | What the agent found / why it's stuck. |
 | `need` | string | | What it needs from the human. |
-| `options` | string[] | | Candidate resolutions — **short, stable, quotable** strings: a future answer references one *verbatim* (see [§6.2](#62-resolution--how-an-ask-closed)). |
+| `options` | string[] | | Candidate resolutions — **short, stable, quotable** strings: an answer references one *verbatim* (see [§6.2](#62-resolution--how-an-ask-closed)). On a **sign-off** they are **answer paths** — qualified verdicts the human's verdict can cite verbatim alongside approve/request-changes (e.g. `"Approved — file the 15 ready charges"`). |
 | `details` | `{ l, v }[]` | | Labelled facts (e.g. amount at risk). |
 | `refs` | `{ label, artifact? }[]` | | Pointers to artifacts that back the ask. |
 | `resolution` | string \| `Resolution` | | The agent's account of the close ([§6.2](#62-resolution--how-an-ask-closed)). A bare string is shorthand for `{ "note": … }`. |
@@ -166,9 +170,9 @@ in the agent's own workflow; answers flowing back through the reader are arrivin
 |---|---|---|
 | `note` | string | The agent's one-line account of the close. |
 | `chosen` | string | The decision taken — **verbatim** one of the ask's `options[]`. |
-| `via` | `"figs"` \| `"human"` \| `"self"` | Where the unblock came from: an answer pulled from Figs (verifiable, future) · answered out-of-band (self-reported) · the blocker cleared on its own. |
+| `via` | `"figs"` \| `"human"` \| `"self"` | Where the unblock came from: an answer pulled from Figs (verified — see `answer`) · answered out-of-band (self-reported) · the blocker cleared on its own. |
 | `by` | string | Who answered, as the agent knows it (self-reported; verified attribution only exists for `via: "figs"`). |
-| `answer` | string | **Reserved** — the Figs answer-event id the agent acted on, once answer-down ships. |
+| `answer` | string | The Figs answer-event id the agent acted on — written by `figs resolve` when the answer came through the inbox (attribution by mechanism, never typed). The cited event may be an answer **or a qualified verdict** (a verdict carrying `chosen`). |
 
 All fields optional; a bare-string `resolution` is shorthand for `{ "note": … }` and readers
 normalize it to the object form.

package/figs.mjs

@@ -9,8 +9,8 @@
  *   figs workspaces                     list the user's workspaces               [--json]
  *   figs init --workspace <slug-or-id> [--endpoint <url>]
  *                                         create .figs/config.json + GUIDE.md (generates a stable agent id)
- *   figs report --result "…"            record a run (stamps id/ts/session, --attach files, auto-push)
- *   figs ask <type> --title "…"         raise an ask (self-contained: options/details/attachments, auto-push)
+ *   figs report --result '…'            record a run (stamps id/ts, --attach files, auto-push)
+ *   figs ask <type> --title '…'         raise an ask (self-contained: options/details/attachments, auto-push)
  *   figs inbox [<ask-id>]               what needs you — answers/verdicts from your humans (pure read)
  *   figs resolve <ask-id>               close an ask (verbatim-checks --chosen; cites the Figs answer it acted on)
  *   figs doctor                         validate .figs/ against the spec before pushing
@@ -42,16 +42,14 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from "node:fs"
 import { homedir } from "node:os"
 import { basename, extname, join } from "node:path"
 import { createHash, randomUUID } from "node:crypto"
-import { execSync, spawn } from "node:child_process"
+import { spawn } from "node:child_process"
 
 // Single source of truth for the version: package.json (shipped alongside this
 // file in the published package). One edit keeps `figs version`, the floor
@@ -113,20 +111,25 @@ const COMMANDS = {
   report: {
     args: "--result <text> [options]",
     flags: [
-      "--result", "--id", "--unit", "--period", "--status", "--attach",
-      "--resolves", "--chosen", "--by", "--note", "--no-push",
+      "--result", "--id", "--unit", "--period", "--status", "--attach", "--no-push",
     ],
-    desc: "record a run — writes one line to runs.jsonl, stamps id/ts/session, pushes",
+    desc: "record a run — one job's row in runs.jsonl; stamps id/ts, pushes",
     more: [
-      "You supply the content; the CLI does the bookkeeping (id, real-clock ts, session",
-      "trace from your runtime's own records, validation, artifact copy, push).",
+      "One run = one JOB — a unit of work your manager would recognize; the runs",
+      "list reads as the job list. Give a job a stable, meaningful --id",
+      "(recon-acme-2026-11); reporting the same id again folds onto that job's row",
+      "(progress evolves: blocked → ok). Sittings/sessions never mint runs —",
+      "stopping to wait for a human is not a job.",
+      "You supply the content; the CLI does the bookkeeping (id, real-clock ts,",
+      "validation, artifact copy, push).",
+      "Single-quote prose values ('…') — inside double quotes your shell expands $,",
+      "so \"($4,474.63)\" reaches figs as \"(,474.63)\": silent corruption.",
       "--attach <file> (repeatable) copies the file into artifacts/ and links it.",
-      "--resolves <ask-id> also closes that ask (with optional --chosen/--by/--note).",
-      "--id only for deliberate stable ids (re-running the same job updates the same run).",
       "--no-push writes locally only; `figs push` publishes later.",
+      "Closing an ask is `figs resolve` — a close is not a job; never report one.",
       "Hand-writing runs.jsonl works too — this verb is sugar over the same file.",
     ],
-    eg: 'figs report --result "88% matched · 31 flagged" --attach ./acme-2025-11.html',
+    eg: "figs report --id recon-acme-2026-11 --result '88% matched · 31 flagged' --attach ./acme-2025-11.html",
   },
   ask: {
     args: "<type> --title <text> [options]",
@@ -136,18 +139,22 @@ const COMMANDS = {
     ],
     desc: "raise an ask — one self-contained line in asks.jsonl, pushed so a human sees it",
     more: [
-      "<type> is one of: blocked · needs-decision · sign-off · fyi.",
+      "<type> = the answer contract: needs-decision (give me an answer) ·",
+      "sign-off (give me a verdict) · fyi (no answer — a for-the-record note).",
       "Make it self-contained — a future session with zero context (or another human)",
       "must be able to act from this record alone: --found (what you saw), --need (what",
       "you need), --option (repeatable; short, stable, quotable — answers cite one",
-      "verbatim), --detail \"Label=Value\" (repeatable), --attach <file> (repeatable;",
+      "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).",
+      "On a sign-off, --option entries are answer paths — the human's verdict can",
+      "cite one verbatim ('Approved — file the 15 ready charges').",
       "--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).",
+      "Single-quote prose values ('…') — double quotes let your shell eat $ amounts.",
     ],
-    eg: 'figs ask sign-off --title "Send 10 payment reminders" --attach ./previews.html --run recon-2026-06',
+    eg: "figs ask sign-off --title 'Send 10 payment reminders' --attach ./previews.html --run recon-2026-06",
   },
   inbox: {
     args: "[<ask-id>] [--json]",
@@ -160,7 +167,7 @@ const COMMANDS = {
       "attached artifacts restored into .figs/artifacts/ (hash-verified) so a fresh",
       "session can act from the record alone.",
       "Scope: THIS agent's open asks + human-rejected ones you haven't acknowledged.",
-      "Reads only — closing still happens via figs resolve / figs report --resolves.",
+      "Reads only — closing still happens via figs resolve.",
     ],
     eg: "figs inbox",
   },
@@ -173,9 +180,11 @@ const COMMANDS = {
       "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.",
+      "After an answer, fork on what it unlocked: nothing new → resolve right away;",
+      "real work → do the job, `figs report` it under its own id, THEN resolve —",
+      "cite the job id in --note so a reader can find the work.",
     ],
-    eg: 'figs resolve acme-bridge --chosen "Strip the alpha prefix" --by "Sarah (accounting)"',
+    eg: "figs resolve acme-bridge --chosen 'Strip the alpha prefix' --by 'Sarah (accounting)'",
   },
   doctor: {
     args: "",
@@ -277,7 +286,11 @@ function genId(prefix) {
 // ---------- local validation (the spec's common mistakes, caught on write) ----
 // The server's schema stays the source of truth; these catch what hand-authors
 // and flag typos get wrong, with errors that teach the fix.
-const ASK_TYPES = ["blocked", "needs-decision", "sign-off", "fyi"]
+// Three types = three answer contracts: needs-decision (give me an answer) ·
+// sign-off (give me a verdict) · fyi (no answer — a for-the-record note).
+// "blocked" was folded into needs-decision in 0.6.0: a stuck JOB is the run's
+// status, not an ask type; what you need from a human is a needs-decision.
+const ASK_TYPES = ["needs-decision", "sign-off", "fyi"]
 const RUN_STATUSES = ["ok", "warn", "fail"]
 const ASK_STATUSES = ["open", "resolved", "withdrawn", "rejected"]
 const TO_VALUES = ["manager", "builder"]
@@ -322,6 +335,10 @@ function validateAsk(a) {
     issues.push(
       `${label}: missing required "type" — was it raised on another machine? (closing it from here needs the full record; cross-machine fetch is coming)`,
     )
+  } else if (a.type === "blocked") {
+    issues.push(
+      `${label}.type: "blocked" was folded into needs-decision — a stuck job is the RUN's status (re-report --status onto the same job id); what you need from a human is a needs-decision ask`,
+    )
   } else checkEnum(issues, a, "type", ASK_TYPES, label)
   if (!a.title) issues.push(`${label}: missing required "title"`)
   checkEnum(issues, a, "status", ASK_STATUSES, label)
@@ -943,8 +960,16 @@ async function init() {
 // ====================== the writing verbs ===================================
 // report / ask / resolve — sugar over the same files (hand-writing stays
 // first-class). The agent supplies content; the CLI stamps id + real-clock ts,
-// captures the session trace, validates with teaching errors, copies
-// attachments, then invokes the same push as `figs push`.
+// validates with teaching errors, copies attachments, then invokes the same
+// push as `figs push`.
+//
+// NOTE — no session auto-capture (removed in 0.5.0). The CLI used to infer a
+// `session` trace (runtime/model/tokens) from "the newest transcript on this
+// machine"; in nested/headless runs that stamped the WRONG runtime+model — a
+// fabricated audit line (e.g. gpt-5.5 on a Claude Code run). A trace must be
+// true or absent, never false, so inference is gone. The spec's optional
+// `session` block remains legal for integrations that can copy provable values
+// from the runtime's own records at work-time.
 
 function requireFigs() {
   if (!existsSync(repoDir)) die("no .figs/ here — run `figs init` first")
@@ -956,12 +981,6 @@ function requireFigs() {
 function appendJsonl(name, obj) {
   appendFileSync(join(repoDir, name), JSON.stringify(obj) + "\n")
 }
-/** Print a record without its (noisy) session block. */
-function summarize(obj) {
-  const { session, ...rest } = obj
-  return JSON.stringify(rest) + (session ? "  (+ session trace)" : "")
-}
-
 /** Copy attachments into artifacts/ — ext + size checks; immutable once there. */
 function attachFiles(paths) {
   const names = []
@@ -989,134 +1008,20 @@ function attachFiles(paths) {
   return names
 }
 
-// ---------- session auto-capture --------------------------------------------
-// The trace comes from the runtime's own records, never from the model's
-// memory. Best-effort by design: any failure → the optional block is omitted;
-// a report is never blocked on trace capture.
-function captureSession() {
-  try {
-    const candidates = [findClaudeTranscript(), findCodexTranscript()].filter(Boolean)
-    if (!candidates.length) return undefined
-    // The transcript being written *now* is the newest one, whichever runtime
-    // owns it. Anything older than a day is a leftover, not this session.
-    const best = candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)[0]
-    if (Date.now() - best.mtimeMs > 86400000) return undefined
-    const session = best.parse(best.path)
-    if (!session) return undefined
-    const commit = captureCommit()
-    if (commit) session.commit = commit
-    return session
-  } catch {
-    return undefined
-  }
-}
-function newestFile(dir, filter) {
-  if (!existsSync(dir)) return null
-  let best = null
-  for (const f of readdirSync(dir)) {
-    if (!filter(f)) continue
-    const p = join(dir, f)
-    let st
-    try {
-      st = statSync(p)
-    } catch {
-      continue
-    }
-    if (!st.isFile()) continue
-    if (!best || st.mtimeMs > best.mtimeMs) best = { path: p, name: f, mtimeMs: st.mtimeMs }
-  }
-  return best
-}
-function findClaudeTranscript() {
-  const dir = join(homedir(), ".claude", "projects", process.cwd().replace(/[\\/:]/g, "-"))
-  const f = newestFile(dir, (n) => n.endsWith(".jsonl"))
-  return f ? { ...f, parse: parseClaudeTranscript } : null
-}
-function parseClaudeTranscript(path) {
-  const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
-  let model, startedAt
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (!line.trim()) continue
-    let e
-    try {
-      e = JSON.parse(line)
-    } catch {
-      continue
-    }
-    if (!startedAt && typeof e.timestamp === "string") startedAt = e.timestamp
-    const m = e.message
-    if (!m?.usage || m.model === "<synthetic>") continue
-    if (typeof m.model === "string") model = m.model
-    tokens.input += m.usage.input_tokens ?? 0
-    tokens.output += m.usage.output_tokens ?? 0
-    tokens.cacheRead += m.usage.cache_read_input_tokens ?? 0
-    tokens.cacheWrite += m.usage.cache_creation_input_tokens ?? 0
-  }
-  const out = { runtime: "claude-code", sessionId: basename(path, ".jsonl") }
-  if (model) out.model = model
-  if (startedAt) out.startedAt = startedAt
-  if (tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite > 0) out.tokens = tokens
-  return out
-}
-function findCodexTranscript() {
-  const root = join(homedir(), ".codex", "sessions")
-  if (!existsSync(root)) return null
-  const desc = (dir) => {
-    try {
-      return readdirSync(dir).sort().reverse()
-    } catch {
-      return []
-    }
-  }
-  for (const y of desc(root)) {
-    for (const m of desc(join(root, y))) {
-      for (const d of desc(join(root, y, m))) {
-        const f = newestFile(join(root, y, m, d), (n) => n.startsWith("rollout-") && n.endsWith(".jsonl"))
-        if (f) return { ...f, parse: parseCodexTranscript }
-      }
-    }
-  }
-  return null
-}
-function parseCodexTranscript(path) {
-  let model, usage, startedAt
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (!line.trim()) continue
-    let e
-    try {
-      e = JSON.parse(line)
-    } catch {
-      continue
-    }
-    if (!startedAt && typeof e.timestamp === "string") startedAt = e.timestamp
-    const p = e.payload ?? e
-    if (!model && typeof p?.model === "string") model = p.model
-    const u = p?.info?.total_token_usage ?? p?.total_token_usage
-    if (u) usage = u
-  }
-  const out = { runtime: "codex" }
-  const uuid = basename(path).match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i)
-  if (uuid) out.sessionId = uuid[0]
-  if (model) out.model = model
-  if (startedAt) out.startedAt = startedAt
-  if (usage) {
-    out.tokens = {
-      input: usage.input_tokens ?? 0,
-      output: usage.output_tokens ?? 0,
-      cacheRead: usage.cached_input_tokens ?? 0,
-    }
-  }
-  return out
-}
-function captureCommit() {
-  try {
-    const opts = { stdio: ["ignore", "pipe", "ignore"] }
-    const sha = execSync("git rev-parse --short HEAD", opts).toString().trim()
-    if (!sha) return undefined
-    const dirty = execSync("git status --porcelain", opts).toString().trim()
-    return dirty ? `${sha}+dirty` : sha
-  } catch {
-    return undefined
+// A `$` eaten by the caller's shell (double-quoted "$4,474.63" → ",474.63")
+// leaves a signature legit prose essentially never has: an orphaned thousands
+// group or a bare ".00" cents tail. Best-effort tripwire — warn and teach,
+// never block (the heuristic can't be certain, and records fold by id, so a
+// corrected re-run heals the row). "$1K" → "K" leaves no signature; that case
+// is why every emitted template teaches single-quoted prose in the first place.
+function warnEatenDollar(...texts) {
+  // regex lives inside the function: the CLI dispatches commands during module
+  // evaluation, so a top-level const here would still be in its TDZ when called
+  const eaten = /(^|[\s([{])(,\d{3}\b|\.00\b)/
+  if (texts.flat().filter(Boolean).some((t) => eaten.test(String(t)))) {
+    console.warn(
+      "figs: ! a value looks like your shell ate a `$` (\"$4,474.63\" in double quotes becomes \",474.63\") — single-quote prose args ('…') and re-run; the same id folds the fix onto the record",
+    )
   }
 }
 
@@ -1166,12 +1071,18 @@ function nextMove(a) {
   const last = a.events[a.events.length - 1]
   if (!last) return "waiting on your human — nothing for you to do"
   if (last.kind === "verdict" && last.verdict === "approved") {
-    return `approved — verify any prerequisites in the ask, do it, then: figs report --resolves ${a.id}`
+    // A qualified verdict carries the chosen answer path — cite it in the close.
+    const chosen = last.chosen ? ` --chosen '${last.chosen}'` : ""
+    return (
+      `approved — verify any prerequisites in the ask, then fork on what it unlocked:` +
+      `\n      nothing left to do → figs resolve ${a.id}${chosen}` +
+      `\n      real work → do the job, figs report it under its own --id, then figs resolve ${a.id}${chosen} --note 'job <id>'`
+    )
   }
   if (last.kind === "verdict" && last.verdict === "changes_requested") {
-    return `revise, then re-raise on the same id: figs ask ${a.type} --id ${a.id} --title "…" …`
+    return `revise, then re-raise on the same id: figs ask ${a.type} --id ${a.id} --title '…' …`
   }
-  return `act on the answer, then: figs report --resolves ${a.id}  (or figs resolve ${a.id} --chosen "…")`
+  return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --chosen '…'`
 }
 
 /** Restore an ask's refs into artifacts/ — hash-verified; never clobbers. */
@@ -1220,7 +1131,7 @@ async function fetchRefs(config, refs) {
  * `figs inbox` — session start. Bare: every ask with thread activity + the
  * next command for each. With an id: the zero-context handoff package (the
  * ask, the whole thread verbatim, refs restored to disk). Pure read — writes
- * nothing to the outbox; closing happens via resolve / report --resolves.
+ * nothing to the outbox; closing happens via resolve.
  */
 async function inboxCmd() {
   requireFigs()
@@ -1293,7 +1204,7 @@ async function inboxCmd() {
   }
 }
 
-// ---------- the resolution fold (shared by `resolve` and `report --resolves`) -
+// ---------- the resolution fold (`resolve` — the one closing verb) ----------
 /**
  * Build the closing fold line. Best-effort, the verified path: fetches this
  * agent's inbox and, when the ask has human events, cites the one acted on —
@@ -1361,15 +1272,16 @@ async function buildResolution(askId, { chosen, by, note, withdrawn, rejected })
   // chosen matches, else the latest event (e.g. the approval, the rejection).
   const events = serverAsk?.events ?? []
   if (!withdrawn && events.length) {
-    const match = chosen
-      ? [...events].reverse().find((e) => e.kind === "answer" && e.chosen === chosen)
-      : null
+    // Any human event can carry the chosen path — an answer, or a qualified
+    // verdict (verdict + chosen together). Match on the text, not the kind.
+    const match = chosen ? [...events].reverse().find((e) => e.chosen === chosen) : null
     const cited = match ?? events[events.length - 1]
     resolution.via = "figs"
     resolution.answer = cited.id
     if (!by && cited.byName) resolution.by = cited.byName
   }
 
+  warnEatenDollar(resolution.chosen, resolution.note)
   const line = {
     id: askId,
     status: withdrawn ? "withdrawn" : rejected ? "rejected" : "resolved",
@@ -1394,7 +1306,7 @@ async function reportCmd() {
   requireFigs()
   const result = flag("--result")
   if (!result) {
-    die('report needs --result "<one-line outcome>" — e.g. figs report --result "88% matched · 31 flagged"')
+    die("report needs --result '<one-line outcome>' — e.g. figs report --result '88% matched · 31 flagged'")
   }
   const run = { id: flag("--id") || genId("r"), ts: nowIso(), result }
   const unit = flag("--unit")
@@ -1406,28 +1318,11 @@ async function reportCmd() {
   const attached = attachFiles(flagAll("--attach"))
   if (attached.length === 1) run.artifact = attached[0]
   else if (attached.length > 1) run.artifacts = attached
-  const resolves = flag("--resolves")
-  let resolution = null
-  if (resolves) {
-    run.resolves = resolves
-    resolution = await buildResolution(resolves, {
-      chosen: flag("--chosen"),
-      by: flag("--by"),
-      note: flag("--note"),
-    })
-  }
-  const session = captureSession()
-  if (session) run.session = session
-
+  warnEatenDollar(run.result)
   const issues = validateRun(run)
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
   appendJsonl("runs.jsonl", run)
-  console.log(`figs: ✓ run recorded — ${summarize(run)}`)
-  if (resolution) {
-    for (const w of resolution.warnings) console.warn(`figs: ! ${w}`)
-    appendJsonl("asks.jsonl", resolution.line)
-    console.log(`figs: ✓ ask ${resolves} ${resolution.line.status}`)
-  }
+  console.log(`figs: ✓ run recorded — ${JSON.stringify(run)}`)
   await autoPush()
 }
 
@@ -1452,11 +1347,11 @@ async function askCmd() {
     }
   }
   const type = positional() ?? base.type
-  if (!type) die(`ask needs a type: figs ask <${ASK_TYPES.join("|")}> --title "…"`)
+  if (!type) die(`ask needs a type: figs ask <${ASK_TYPES.join("|")}> --title '…'`)
   const ask = { ...base, id: flag("--id") ?? base.id ?? genId("ask"), ts: nowIso(), type }
   if (!ask.status) ask.status = "open"
   const title = flag("--title") ?? base.title
-  if (!title) die('ask needs --title "<the ask, in one line>"')
+  if (!title) die("ask needs --title '<the ask, in one line>'")
   ask.title = title
   for (const [f, k] of [["--need", "need"], ["--found", "found"], ["--unit", "unit"], ["--to", "to"]]) {
     const v = flag(f)
@@ -1493,13 +1388,17 @@ async function askCmd() {
       "figs: ! tip: a sign-off reviews best with attachments — the exact content to approve, plus a brief (what to do once approved + what it requires). Add --attach <file>",
     )
   }
-  const session = captureSession()
-  if (session) ask.session = session
-
+  warnEatenDollar(
+    ask.title,
+    ask.found,
+    ask.need,
+    ask.options ?? [],
+    (ask.details ?? []).flatMap((d) => [d.l, d.v]),
+  )
   const issues = validateAsk(ask)
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
   appendJsonl("asks.jsonl", ask)
-  console.log(`figs: ✓ ask raised — ${summarize(ask)}`)
+  console.log(`figs: ✓ ask raised — ${JSON.stringify(ask)}`)
   if (!ask.to) {
     console.log("figs:   tip: address asks with --to manager|builder so they route to the right person")
   }

package/package.json

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