@figs-so/cli 0.4.0 → 0.7.0

package/README.md

@@ -74,8 +74,8 @@ are shorthand for exactly that (always current, no version drift). Prefer a real
 | `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 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, auto-captures the session trace, `--attach`es artifacts, pushes itself |
-| **`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 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

@@ -125,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. |
@@ -133,7 +133,8 @@ 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"`). |
+| `onApprove` | string[] | | **Sign-off only.** The ordered steps approval sets in motion — **an approval authorizes exactly these stated steps, in order** (e.g. `"Post the 8 journal entries to SAP"`, `"Email the filing to Acme"`); flag anything irreversible in the step itself. This is the agent's **declared intent, not a bound plan** — readers present it as the agent's claim. Invalid on other types: a *needs-decision* has no approval; there, the chosen option carries the next step. |
 | `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": … }`. |
@@ -170,9 +171,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
@@ -115,42 +113,52 @@ const COMMANDS = {
     flags: [
       "--result", "--id", "--unit", "--period", "--status", "--attach", "--no-push",
     ],
-    desc: "record a run — one job's row in runs.jsonl; stamps id/ts/session, pushes",
+    desc: "record a run — one job's row in runs.jsonl; stamps id/ts, pushes",
     more: [
       "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, session",
-      "trace from your runtime's own records, validation, artifact copy, push).",
+      "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.",
       "--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 --id recon-acme-2026-11 --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]",
     flags: [
-      "--id", "--title", "--need", "--found", "--option", "--detail", "--attach",
-      "--to", "--unit", "--run", "--stdin", "--no-push",
+      "--id", "--title", "--need", "--found", "--option", "--on-approve", "--detail",
+      "--attach", "--to", "--unit", "--run", "--stdin", "--no-push",
     ],
     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.",
-      "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;",
-      "for sign-offs attach the exact content for review + a brief: what to do once",
-      "approved and what it requires).",
+      "<type> = the answer contract: needs-decision (give me an answer) ·",
+      "sign-off (give me a verdict) · fyi (no answer — a for-the-record note).",
+      "Two strangers read every ask — a human deciding, a future session acting;",
+      "the record must carry everything both need: --found (what you saw), --need",
+      "(what you need), --option (repeatable; short, stable, quotable — answers cite",
+      "one verbatim; the option is the label, context goes in --found/--detail),",
+      "--detail 'Label=Value' (repeatable), --attach <file> (repeatable; a verdict",
+      "blesses what the ask carries — 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') — and",
+      "--on-approve '<step>' (repeatable, ordered; sign-off only) states what",
+      "approval sets in motion: an approval authorizes exactly the steps you stated.",
+      "Flag anything irreversible in the step itself.",
       "--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 --on-approve 'Send the 10 reminder emails' --on-approve 'Mark the invoices chased' --run recon-2026-06",
   },
   inbox: {
     args: "[<ask-id>] [--json]",
@@ -180,7 +188,7 @@ const COMMANDS = {
       "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: "",
@@ -282,7 +290,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"]
@@ -327,6 +339,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)
@@ -334,6 +350,15 @@ function validateAsk(a) {
   if (a.options !== undefined && (!Array.isArray(a.options) || a.options.some((o) => typeof o !== "string"))) {
     issues.push(`${label}.options: must be an array of short, quotable strings`)
   }
+  if (a.onApprove !== undefined) {
+    if (!Array.isArray(a.onApprove) || a.onApprove.some((s) => typeof s !== "string")) {
+      issues.push(`${label}.onApprove: must be an array of strings — the ordered steps approval sets in motion`)
+    } else if (a.type !== "sign-off") {
+      issues.push(
+        `${label}.onApprove: sign-off only — it is the approval contract; a ${a.type ?? "non-sign-off ask"} has no approval (the chosen option carries the next step)`,
+      )
+    }
+  }
   if (a.details !== undefined && (!Array.isArray(a.details) || a.details.some((d) => !d || typeof d.l !== "string"))) {
     issues.push(`${label}.details: must be [{ "l": "Label", "v": "Value" }]`)
   }
@@ -948,8 +973,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")
@@ -961,12 +994,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 = []
@@ -994,134 +1021,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",
+    )
   }
 }
 
@@ -1171,16 +1084,23 @@ 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") {
+    // 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}` +
-      `\n      real work → do the job, figs report it under its own --id, then figs resolve ${a.id} --note "job <id>"`
+      `\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 '…' …`
+  }
+  if (last.chosen) {
+    // Pre-fill the cited option verbatim — the note is substance for --note, never for --chosen.
+    const note = last.text ? ` --note '…'` : ""
+    return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --chosen '${last.chosen}'${note}`
   }
-  return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --chosen "…"`
+  return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --note '…'`
 }
 
 /** Restore an ask's refs into artifacts/ — hash-verified; never clobbers. */
@@ -1370,15 +1290,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",
@@ -1403,7 +1324,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")
@@ -1415,13 +1336,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 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)}`)
+  console.log(`figs: ✓ run recorded — ${JSON.stringify(run)}`)
   await autoPush()
 }
 
@@ -1446,11 +1365,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)
@@ -1465,6 +1384,13 @@ async function askCmd() {
       )
     }
   }
+  const onApprove = flagAll("--on-approve")
+  if (onApprove.length) ask.onApprove = onApprove
+  if (ask.onApprove?.length && ask.type !== "sign-off") {
+    die(
+      `--on-approve is the approval contract — sign-off only. A ${ask.type} has no approval; the chosen option carries the next step (put it in the --option text)`,
+    )
+  }
   const details = flagAll("--detail").map((d) => {
     const i = d.indexOf("=")
     if (i < 1) die(`--detail must be "Label=Value", got "${d}"`)
@@ -1487,13 +1413,23 @@ 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
-
+  if (ask.type === "sign-off" && !ask.onApprove?.length) {
+    console.warn(
+      "figs: ! tip: state what approval sets in motion — --on-approve '<step>' (repeatable, ordered); an approver shouldn't have to guess what approve causes",
+    )
+  }
+  warnEatenDollar(
+    ask.title,
+    ask.found,
+    ask.need,
+    ask.options ?? [],
+    ask.onApprove ?? [],
+    (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.4.0",
+  "version": "0.7.0",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {