@figs-so/cli 0.6.0 → 0.8.0

package/README.md

@@ -41,8 +41,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 —
-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.
+and day to day the agent records itself in one stroke per event: `figs checkpoint` (a job opens /
+progresses) · `figs report` (its outcome) · `figs ask` (needs a human) · `figs resolve` (close an
+ask). Each pushes itself.
 
 ## How it works
 
@@ -73,8 +74,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 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 inbox [<ask-id>]`** | start every session here — your humans' answers/verdicts, verbatim, with the next command per ask, plus your unfinished (in-flight) jobs; with an id: the full zero-context handoff package (thread + artifacts restored) |
+| **`figs checkpoint --id <job> --note '…'`** | save a job's progress mid-flight — the **first checkpoint opens the job** (`state: in-flight`), so a crash leaves a recoverable stub the next session finds in the inbox; `--trigger` records what set the sitting in motion |
+| **`figs report --result '…'`** | file a job's outcome — **one job, one stable `--id`** (re-reporting an id folds progress onto that job's row); settles the job (`state: settled`), 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` |

package/SPEC.md

@@ -25,13 +25,26 @@
 .figs/
 ├── config.json        # identity + destination (committed, non-secret)
 ├── agent.json         # the charter — who this agent is (committed)
+├── CONTRACT.md        # agent-authored: what this agent surfaces / holds back (committed)
+├── GUIDE.md           # orientation breadcrumb, written by the CLI (committed)
 ├── runs.jsonl         # activity log, one JSON object per line (outbox; gitignored)
 ├── asks.jsonl         # things needing a human, one per line (outbox; gitignored)
 └── artifacts/         # files referenced by runs/asks (outbox; gitignored)
 ```
 
-**Commit** `config.json` + `agent.json` (identity + charter). The activity files (`runs.jsonl`,
-`asks.jsonl`, `artifacts/`) are a transient outbox and are typically gitignored.
+**Commit** `config.json` + `agent.json` + `CONTRACT.md` + `GUIDE.md`. The activity files
+(`runs.jsonl`, `asks.jsonl`, `artifacts/`) are a transient outbox and are typically gitignored.
+
+**`CONTRACT.md` + `GUIDE.md` are companion conventions, not wire format** — they are never
+pushed. `CONTRACT.md` is the standing agreement between the agent and its user about what gets
+surfaced; `GUIDE.md` is an orientation stub the reference CLI writes (and never clobbers).
+Implementations may add files like these; readers must ignore files this spec doesn't name.
+
+**The membership rule — what belongs in `.figs/`:** everything in the folder is *Figs-facing* —
+protocol metadata (`config.json`), the published record (the charter, the outbox), or a
+convention *about* publishing (`CONTRACT.md`, `GUIDE.md`). An agent's private working state —
+memory, self-checks, scratch notes — lives outside `.figs/`, elsewhere in the repo. If a file's
+only reader is the agent itself, it does not belong here.
 
 ## 3. `config.json` — identity + destination
 
@@ -89,14 +102,22 @@ merge as asks): re-reporting a job's id layers progress onto its row (`status` e
 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.
 
+A job is either **in flight** or **settled** (`state`, below). A **checkpoint**
+(`figs checkpoint`) folds progress onto the job's id and marks it in-flight — the record
+survives the session working it, so a crash mid-job leaves a visible, recoverable stub
+instead of nothing. A **report** files the outcome and settles it; a report with no prior
+checkpoint is simply a job **born settled** (the single-sitting case). Nothing *external*
+ever closes a run — only the agent's own report settles its job.
+
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
 | `ts` | string (ISO-8601 w/ offset) | ✓ | When it ran, e.g. `2026-05-28T23:41:26Z`. |
 | `unit` | string | | The `Unit.id` this run is about. |
 | `period` | string | | |
-| `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. |
+| `result` | string | | The job's current one-line state — where it stands while in flight; the outcome once settled. |
+| `status` | `"ok"` \| `"warn"` \| `"fail"` | | Default `"ok"`. **Outcome, never lifecycle** — what the work looks like right now (a stuck job is `warn`); whether the job is *done* is `state`, the orthogonal dimension. |
+| `state` | `"in-flight"` \| `"settled"` | | Default `"settled"`. **Lifecycle, verb-stamped** — `figs checkpoint` stamps `in-flight`, `figs report` stamps `settled`; agents never hand-pick it. An in-flight job whose agent died stays visibly in flight — that's the point: the next session finds it in `figs inbox` and finishes or settles it. |
 | `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). |
 | `session` | `Session` | | Where/how this ran (see [§5.1](#51-session--runtime-metadata-optional)). Optional, self-reported. |
 
@@ -104,9 +125,9 @@ Closing an ask is **not** a job: that's a `resolution` in `asks.jsonl` (§6), ne
 
 An optional, **self-reported** block describing the runtime session that produced a run (or raised an
 ask — see §6). Every field is optional — fill what your runtime exposes, omit the rest. This is
-*transparency, not attestation*: the values come from the runtime's own records — `figs report`
-captures them automatically; hand-authors copy what their runtime exposes. Cryptographic provenance
-remains [reserved](#reserved-not-in-v1).
+*transparency, not attestation*: the values come from the runtime's own records — hand-authored, or
+written by integrations that can copy provable values at work-time (the CLI never infers them).
+Cryptographic provenance remains [reserved](#reserved-not-in-v1).
 
 | Field | Type | Meaning |
 |---|---|---|
@@ -115,6 +136,7 @@ remains [reserved](#reserved-not-in-v1).
 | `sessionId` | string | The runtime's own session identifier. |
 | `startedAt` | string (ISO-8601 w/ offset) | When this job began (the record's `ts` is when it was reported). |
 | `commit` | string | The agent repo's HEAD at run time; append `+dirty` when the working tree had uncommitted changes, e.g. `1b68668+dirty`. |
+| `trigger` | string | What set this sitting in motion — one self-reported line, e.g. `monthly close cron`, `inbox: answer on acme-bridge`, `Wayne, in chat`. A *fresh* sitting on a job states it (stamped from `--trigger` on `figs checkpoint`/`report`); records continuing the same session omit it. The one mechanically verified trigger stays `resolution.answer` ([§6.2](#62-resolution--how-an-ask-closed)). |
 | `tokens` | `{ input?, output?, cacheRead?, cacheWrite? }` (numbers) | **Session totals at report time** — cumulative for the whole session, *not* per-job. Approximate by design (an interactive session may include unrelated chat). Readers may derive per-run deltas between consecutive runs sharing a `sessionId`. Include cache figures when available — in agentic sessions they often dominate real cost. |
 
 ## 6. `asks.jsonl` — handoffs to a human
@@ -134,6 +156,7 @@ primitive** — the agent reached the edge of its autonomy.
 | `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: 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": … }`. |
@@ -149,7 +172,8 @@ An ask is the **anchor of a thread whose two halves are owned by different parti
 
   ```jsonc
   { "id": "acme-bridge", "status": "resolved",
-    "resolution": { "chosen": "Strip the alpha prefix", "via": "human", "by": "Sarah (accounting)" } }
+    "resolution": { "chosen": "Strip the alpha prefix", "via": "human",
+                    "by": "Sarah (accounting)", "ts": "2026-06-01T09:12:00Z" } }
   ```
 
   Appending keeps the local file crash-safe, concurrency-safe (multiple runners), and an honest
@@ -173,6 +197,7 @@ in the agent's own workflow; answers flowing back through the reader are arrivin
 | `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 | 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`). |
+| `ts` | string (ISO-8601 w/ offset) | When the agent closed it — **machine-stamped by `figs resolve`, never typed**. The agent's claim of the execution-adjacent moment, same self-reported grade as the record `ts`; readers stamp their own receipt at ingest and surface both only when they diverge. Lives *inside* `resolution` so the fold can't collide with the record's raise `ts`. |
 
 All fields optional; a bare-string `resolution` is shorthand for `{ "note": … }` and readers
 normalize it to the object form.
@@ -281,8 +306,10 @@ Deliberately out of scope for v1, named here so implementers don't repurpose the
 ```
 
 ```jsonc
-// .figs/runs.jsonl   (one object per line)
-{ "id": "acme-2025-11", "ts": "2026-05-28T23:41:26Z", "unit": "acme", "period": "2025-11", "result": "88% matched · 31 keys flagged", "status": "ok", "artifact": "acme-2025-11.html",
+// .figs/runs.jsonl   (one object per line; records fold by id — the checkpoint opened the job, the report settled it)
+{ "id": "acme-2025-11", "ts": "2026-05-28T23:05:40Z", "unit": "acme", "period": "2025-11", "state": "in-flight", "result": "Statements pulled — matching now",
+  "session": { "runtime": "claude-code", "trigger": "monthly close cron" } }
+{ "id": "acme-2025-11", "ts": "2026-05-28T23:41:26Z", "unit": "acme", "period": "2025-11", "result": "88% matched · 31 keys flagged", "status": "ok", "state": "settled", "artifact": "acme-2025-11.html",
   "session": { "runtime": "claude-code", "model": "claude-fable-5", "sessionId": "3fffcd97-d4f5-4b77-8243-8f450d7c9614",
     "startedAt": "2026-05-28T23:02:00Z", "commit": "1b68668",
     "tokens": { "input": 26608, "output": 135532, "cacheRead": 8677869, "cacheWrite": 543145 } } }

package/figs.mjs

@@ -111,15 +111,20 @@ const COMMANDS = {
   report: {
     args: "--result <text> [options]",
     flags: [
-      "--result", "--id", "--unit", "--period", "--status", "--attach", "--no-push",
+      "--result", "--id", "--unit", "--period", "--status", "--trigger", "--attach", "--no-push",
     ],
-    desc: "record a run — one job's row in runs.jsonl; stamps id/ts, pushes",
+    desc: "file a job's outcome — settles its row in runs.jsonl; stamps id/ts/state, 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.",
+      "A report SETTLES the job (state: settled). A job that outlives a sitting",
+      "should open with `figs checkpoint` first; a report with no prior checkpoint",
+      "is simply a job born settled (the single-sitting case).",
+      "--trigger '<what set this sitting in motion>' — state it in a fresh sitting",
+      "('monthly close cron', 'Wayne, in chat'); omit when continuing one.",
       "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 $,",
@@ -131,30 +136,57 @@ const COMMANDS = {
     ],
     eg: "figs report --id recon-acme-2026-11 --result '88% matched · 31 flagged' --attach ./acme-2025-11.html",
   },
+  checkpoint: {
+    args: "--id <job> --note <text> [options]",
+    flags: [
+      "--id", "--note", "--trigger", "--status", "--unit", "--period", "--attach", "--no-push",
+    ],
+    desc: "save a job's progress mid-flight — folds onto its row, marks it in-flight, pushes",
+    more: [
+      "Your first checkpoint OPENS the job (state: in-flight) — make it the first",
+      "act of any job that will outlive this sitting: say what triggered it",
+      "(--trigger) and what you're setting out to do (--note). If you die mid-job,",
+      "the checkpoint is what the next session finds in `figs inbox`; without one,",
+      "the job never existed anywhere.",
+      "Checkpoint at MANAGER grain — a step a human would recognize ('statements",
+      "pulled — matching now'), never per tool call.",
+      "--note is the job's current one-line state; it shows on the job's row and",
+      "evolves with each fold. --status still carries the outcome look (a stuck",
+      "job is --status warn — in-flight and warn are independent).",
+      "`figs report --id <same-id>` settles the job when it's done — including",
+      "abandoning it (--status warn --result 'abandoned — superseded by …').",
+      "A checkpoint isn't a checkpoint until it's pushed — this verb pushes itself.",
+    ],
+    eg: "figs checkpoint --id recon-acme-2026-11 --note 'Statements pulled — matching now' --trigger 'monthly close cron'",
+  },
   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> = 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;",
-      "for sign-offs attach the exact content for review + a brief: what to do once",
-      "approved and what it requires).",
+      "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').",
+      "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]",
@@ -166,8 +198,9 @@ const COMMANDS = {
       "With an ask id: the full handoff package — the ask, the whole thread, and its",
       "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.",
+      "Scope: THIS agent's open asks + human-rejected ones you haven't acknowledged",
+      "+ unfinished jobs (in-flight runs — your past self's work; finish or settle).",
+      "Reads only — closing still happens via figs resolve / figs report.",
     ],
     eg: "figs inbox",
   },
@@ -292,6 +325,9 @@ function genId(prefix) {
 // 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"]
+// Lifecycle, orthogonal to status (outcome): checkpoint stamps in-flight,
+// report stamps settled. Absent = settled (a plain report is a complete fact).
+const RUN_STATES = ["in-flight", "settled"]
 const ASK_STATUSES = ["open", "resolved", "withdrawn", "rejected"]
 const TO_VALUES = ["manager", "builder"]
 const ARTIFACT_EXTS = new Set([
@@ -318,6 +354,7 @@ function validateRun(r) {
   if (!r.id || typeof r.id !== "string") issues.push(`${label}: missing required "id"`)
   if (!r.ts) issues.push(`${label}: missing required "ts" (ISO-8601 — \`figs report\` stamps it for you)`)
   checkEnum(issues, r, "status", RUN_STATUSES, label)
+  checkEnum(issues, r, "state", RUN_STATES, label)
   if (r.artifact !== undefined && typeof r.artifact !== "string") {
     issues.push(`${label}.artifact: must be a single file name (use "artifacts" for a list)`)
   }
@@ -346,6 +383,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" }]`)
   }
@@ -509,6 +555,7 @@ else if (COMMANDS[cmd]) {
   else if (cmd === "workspaces") await workspaces()
   else if (cmd === "init") await init()
   else if (cmd === "report") await reportCmd()
+  else if (cmd === "checkpoint") await checkpointCmd()
   else if (cmd === "ask") await askCmd()
   else if (cmd === "inbox") await inboxCmd()
   else if (cmd === "resolve") await resolveCmd()
@@ -1082,7 +1129,12 @@ function nextMove(a) {
   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 `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --chosen '…'`
+  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} --note '…'`
 }
 
 /** Restore an ask's refs into artifacts/ — hash-verified; never clobbers. */
@@ -1181,15 +1233,17 @@ async function inboxCmd() {
   if (data.truncated) {
     console.warn(`figs: ! showing the first ${items.length} — more exist (close some asks)`)
   }
-  if (items.length === 0) {
-    console.log("figs: ✓ inbox empty — no open asks, nothing needs you")
+  const jobs = data.jobs ?? []
+  if (items.length === 0 && jobs.length === 0) {
+    console.log("figs: ✓ inbox empty — no open asks, no unfinished jobs, nothing needs you")
     return
   }
   const rejected = items.filter((a) => a.status === "rejected")
   const answered = items.filter((a) => a.status === "open" && a.events.length > 0)
   const quiet = items.filter((a) => a.status === "open" && a.events.length === 0)
   console.log(
-    `figs: inbox — ${answered.length} answered · ${rejected.length} rejected to acknowledge · ${quiet.length} waiting on your human`,
+    `figs: inbox — ${answered.length} answered · ${rejected.length} rejected to acknowledge · ${quiet.length} waiting on your human` +
+      (jobs.length ? ` · ${jobs.length} job${jobs.length === 1 ? "" : "s"} in flight` : ""),
   )
   const printItem = (a) => {
     const last = a.events[a.events.length - 1]
@@ -1202,6 +1256,17 @@ async function inboxCmd() {
     console.log(`\n  Waiting on your human (nothing for you to do):`)
     for (const a of quiet) console.log(`    · ${a.id} · ${a.type} — ${a.title} (raised ${agoStr(a.ts)})`)
   }
+  if (jobs.length) {
+    console.log(`\n  Unfinished jobs — in flight (your past self's work; finish or settle):`)
+    for (const j of jobs) {
+      console.log(
+        `    · ${j.id}${j.result ? ` — ${j.result}` : ""} (last update ${agoStr(j.updatedAt ?? j.ts)})`,
+      )
+      console.log(
+        `      → continue it (\`figs checkpoint --id ${j.id}\` as you go); \`figs report --id ${j.id}\` settles it`,
+      )
+    }
+  }
 }
 
 // ---------- the resolution fold (`resolve` — the one closing verb) ----------
@@ -1281,12 +1346,18 @@ async function buildResolution(askId, { chosen, by, note, withdrawn, rejected })
     if (!by && cited.byName) resolution.by = cited.byName
   }
 
+  // The close's own clock — machine-stamped, never typed (same posture as the
+  // record `ts`). It lives INSIDE resolution so the fold can't collide with
+  // the record's raise `ts` (folds are field-level merges); the reader stamps
+  // its own receipt (`closedAt`) at ingest — two clocks, claim vs receipt.
+  resolution.ts = nowIso()
+
   warnEatenDollar(resolution.chosen, resolution.note)
   const line = {
     id: askId,
     status: withdrawn ? "withdrawn" : rejected ? "rejected" : "resolved",
+    resolution,
   }
-  if (Object.keys(resolution).length) line.resolution = resolution
   return { line, warnings }
 }
 
@@ -1308,13 +1379,17 @@ async function reportCmd() {
   if (!result) {
     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 }
+  // state is verb-stamped, never typed: report settles the job (checkpoint
+  // marks it in-flight). The settling fold overrides any earlier checkpoint.
+  const run = { id: flag("--id") || genId("r"), ts: nowIso(), result, state: "settled" }
   const unit = flag("--unit")
   if (unit) run.unit = unit
   const period = flag("--period")
   if (period) run.period = period
   const status = flag("--status")
   if (status) run.status = status
+  const trigger = flag("--trigger")
+  if (trigger) run.session = { trigger }
   const attached = attachFiles(flagAll("--attach"))
   if (attached.length === 1) run.artifact = attached[0]
   else if (attached.length > 1) run.artifacts = attached
@@ -1323,9 +1398,76 @@ async function reportCmd() {
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
   appendJsonl("runs.jsonl", run)
   console.log(`figs: ✓ run recorded — ${JSON.stringify(run)}`)
+  // 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
+  // only (other machines' asks are invisible here): best-effort by design.
+  const openCiting = foldById(readJsonl("asks.jsonl")).filter(
+    (a) => a.run === run.id && (a.status ?? "open") === "open",
+  )
+  if (openCiting.length > 0) {
+    const n = openCiting.length
+    console.log(
+      `figs:   note: ${n} open ask${n === 1 ? "" : "s"} cite${n === 1 ? "s" : ""} this job (${openCiting
+        .map((a) => a.id)
+        .join(", ")}) — a tail sign-off is fine; if the OUTCOME depends on an answer, keep the job in flight instead (\`figs checkpoint --id ${run.id} --status warn\`)`,
+    )
+  }
   await autoPush()
 }
 
+/**
+ * `figs checkpoint` — save a job's progress so it survives this sitting. The
+ * first checkpoint on an id OPENS the job (state: in-flight); a crash mid-job
+ * then leaves a visible, recoverable stub the next session finds in
+ * `figs inbox`, instead of nothing. Same fold-by-id write as report — only
+ * the stamped state differs; `figs report` settles the id.
+ */
+async function checkpointCmd() {
+  requireFigs()
+  const id = flag("--id")
+  if (!id) {
+    die("checkpoint needs --id '<job-id>' — the stable job id the next session will look for (e.g. recon-acme-2026-11)")
+  }
+  const note = flag("--note")
+  if (!note) {
+    die(`checkpoint needs --note '<where the job stands>' — e.g. figs checkpoint --id ${id} --note 'Statements pulled — matching now'`)
+  }
+  // Before the append, so "new" means new-to-this-outbox (the teaching line).
+  const isNew = !foldById(readJsonl("runs.jsonl")).some((r) => r.id === id)
+  const run = { id, ts: nowIso(), result: note, state: "in-flight" }
+  const unit = flag("--unit")
+  if (unit) run.unit = unit
+  const period = flag("--period")
+  if (period) run.period = period
+  const status = flag("--status")
+  if (status) run.status = status
+  const trigger = flag("--trigger")
+  if (trigger) run.session = { trigger }
+  const attached = attachFiles(flagAll("--attach"))
+  if (attached.length === 1) run.artifact = attached[0]
+  else if (attached.length > 1) run.artifacts = attached
+  warnEatenDollar(run.result)
+  const issues = validateRun(run)
+  if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
+  appendJsonl("runs.jsonl", run)
+  console.log(`figs: ✓ checkpoint recorded — ${JSON.stringify(run)}`)
+  if (isNew) {
+    console.log(
+      `figs:   new job opened: ${id} (in flight) — checkpoint as you go; \`figs report --id ${id}\` settles it`,
+    )
+  }
+  await autoPush()
+  // A checkpoint exists to survive a crash — local-only protects nothing.
+  // autoPush already said "saved locally"; for THIS verb that reads like
+  // success, so say what it actually means.
+  if (process.exitCode === 1) {
+    console.warn(
+      `figs: ! this checkpoint is NOT protecting the job yet — nothing reached the server. Run \`figs push\` before continuing the work.`,
+    )
+  }
+}
+
 async function askCmd() {
   requireFigs()
   let base = {}
@@ -1366,6 +1508,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}"`)
@@ -1388,11 +1537,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>",
     )
   }
+  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)

package/package.json

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