foldrun 2.10.10 → 2.10.12

package/docs/api.md

@@ -353,7 +353,7 @@ Reads return which secrets exist, never their values.
 | `/api/account/telemetry/test` | POST | send one made-up run as an OpenTelemetry trace to the collector `telemetry:` names — the account's, or `{ workspace }`'s — with its header secrets filled from the vault; `{ ok, status?, error?, spans?, endpoint }`. `409` when no `telemetry:` is set. Needs `workspace:manage` |
 | `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded; `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
 | `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a workspace's `/pause`, for every workspace at once. GET `{ paused, account, workspaces }` (`workspaces`: those paused on their own). POST `{ reason?, stop?: true }`, DELETE resumes the account — a workspace paused on its own stays paused. Needs `workspace:manage` and access to every workspace |
-| `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the super admin is mailed to settle the last invoice and any refund. Returns `{ ok, suspended, notified }`; 409 when already asked. Hosted installs only |
+| `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the super admin is mailed to settle the last invoice and any refund. A plan's subscription is set to stop at the end of the period already paid for — nothing renews, no refund — and `billing` says what was done (the close stands even if Stripe could not be reached; `billing` then says so). Returns `{ ok, suspended, notified, billing }`; 409 when already asked. Hosted installs only |
 | `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes` (the encrypted object), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
 | `/api/account/backups/requests` | GET, POST | ask the platform team to restore what an account cannot restore itself. POST `{ what, target, workspace?, backupId?, note? }` (`what` is runs, state, storage or everything) records the request, mails the operator and audits it as `backup.restore_requested`; answers 201 `{ ok, request }` with `notified` saying whether the mail went. Restores nothing. `workspace:manage`, and a member scoped to some workspaces must name one. GET lists this account's requests |
 | `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`. See [api-usage](api-usage.md) |
@@ -403,7 +403,7 @@ person: a key names an account, never a who.
 | `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some workspaces, as the audit log is |
 | `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency` |
 | `/api/billing/plans` | GET | the catalogue (four plans: fee, credits, per-credit price, runs at once, workspaces, lane), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
-| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, creator, pro or scale. With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true`. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
+| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, creator, pro or scale. With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true` — only once its prorated invoice is paid: when the payment needs the customer (a declined card, 3-D Secure) the change waits at Stripe as a pending update, nothing about the plan moves, and the answer is 402 `{ pending: true, payUrl }` — paying that invoice applies it; unpaid, Stripe drops it and voids the invoice after 23 hours. A plan set to stop and changed this way stays set to stop once paid — resuming it is the customer's own choice (`resume: true`); nothing resumes on its own. A plan set to stop at the period's end is still that live subscription: choosing a plan takes the stop off (and changes it if it is another plan) — never a second Checkout. With no subscription known here but one still billing at Stripe for the account's customer, 409: a second is not started. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
 | `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged (see `/api/admin/stripe-events`). Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
 
 ## Versions

package/docs/budgets-and-billing.md

@@ -176,7 +176,9 @@ asked. Without a plan, credit costs 1¢ each, one run at a time, up to 3
 workspaces, standard lane — a plan is cheaper from the first month you would have spent its fee
 anyway. Changing plan is charged at once, prorated by Stripe; the new plan
 and its bundle land when that invoice is paid — a change whose payment
-fails leaves you on the plan you had. Ending one ends it with the cycle.
+fails leaves you on the plan you had, with Stripe's page to pay it; paid
+within 23 hours it goes through, otherwise Stripe drops it and voids the
+invoice. Ending one ends it with the cycle.
 
 **Seats are unlimited** on every plan: agents work, people supervise, and a
 per-seat fee would tax the approver the safety story depends on.
@@ -370,9 +372,11 @@ when. If the invoice is still unpaid when the grace ends, the hourly sweep
 suspends the account for new runs with the reason **payment overdue**, and
 one more email says so; the banner turns red. Runs in flight finish, people
 can still sign in, nothing is deleted. The moment `invoice.paid` arrives
-for it — or `invoice.voided`, `invoice.marked_uncollectible`, or Stripe
-cancelling the subscription — the suspension is lifted, and a payment
-gets a thank-you email. Every step is once per invoice, however often
+for it — or `invoice.voided` or `invoice.marked_uncollectible`, which is
+how a debt is written off — the suspension is lifted, and a payment gets a
+thank-you email. The subscription ending does not settle it: the plan
+ends, but an invoice it left unpaid is still owed and still payable, and
+the account stays paused until it is paid or written off. Every step is once per invoice, however often
 Stripe retries or redelivers; a second invoice failing during the grace
 does not restart it. Dunning lifts only a suspension it placed: an account
 the super admin suspended for another reason stays suspended. The super
@@ -496,7 +500,7 @@ is `<public url>/api/billing/stripe`, sending exactly:
 | `invoice.voided` | an overdue invoice cancelled; dunning ends |
 | `invoice.marked_uncollectible` | an overdue invoice written off; dunning ends |
 | `customer.subscription.updated` | a plan swap, or a status change |
-| `customer.subscription.deleted` | the plan it paid for ends; its dunning ends |
+| `customer.subscription.deleted` | the plan it paid for ends; what it left unpaid stays owed (dunning and its pause stay) |
 | `payment_intent.succeeded` | an auto top-up credited |
 | `payment_intent.payment_failed` | an auto top-up refused; the warning goes |
 | `charge.refunded` | a refunded top-up's credits come off |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.10.10",
+  "version": "2.10.12",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "FSL-1.1-ALv2",
   "type": "module",