Cloud permission and spend (cluster A)
Status: approved 2026-11-04 (manager, delegated by the owner; owner’s request of 2026-11-03, for this release). Extends
ai/where-models-run.md§D–E (ai.where.one-egress-gate,ai.where.cloud-spend-cap,ai.where.run-cap-beside-the-project-cap) andsource/recipe-designer.md§11b (designer.budget.*). Iterate on what exists; nothing here replaces the one spend hold (llm/spend.py) or the one egress gate (llm/egress.py).
The problem, and one decision per question
Today a cloud spend cap exists only as a project’s Set Up answer (answers.cloud_spend_cap_usd, US$10 a month unless
set, held by llm/spend.py, booked in the project’s recipe/cloud-spend.json by UTC month), and whether pages may go to
the cloud is a project answer (cloud_allowed) under an app-wide places tick (recipes/places.py, models_may_run,
the Settings > AI “Allow cloud AI services” switch). Someone who never runs Set Up has no cap control, and no daily cap
exists anywhere. A refusal from a hand-run path (the context menu, the workflow bar, the runner) is a validation 400
whose only switch is in the error text (#6028), or a page row with category egress_refused / a run paused at the cap
with words the app does not act on. The CLI and MCP get the same bare detail.
Decisions (details under “Decisions I made”): 1. App-wide caps are defaults, not second ceilings. Settings > AI holds a monthly and a daily cap; a project with its own answer uses its own, a project with none uses the app’s. The hold still judges one project ledger. 2. A daily cap is held exactly like the monthly one, from the same ledger, which gains a day total. 3. Images-to-cloud: the Settings switch is the default; a project may say yes or no for itself. A project that has not answered inherits. This replaces “the app’s places cap every project” for the cloud place only. 4. One typed refusal, served, never computed in the app, for every cap and the images rule, with its fixes. 5. A person never has to answer per project. The Settings defaults (the two caps, the images switch) are enough on their own; a project answer only departs from them, and every refusal offers the app-wide fix beside the project one. 6. Overrides are of two kinds: a permanent one (an audited action: raise the cap, allow for this project) and a one-run one (carried on the run row, written nowhere else).
Behaviours
Status tags are as of 2026-11-04 (A: the engine half of its first three lines is built, three PARTIAL, the Swift half is Step 1.2; nothing in C or D is built; B’s three OK lines and two PARTIAL are as named). Tests are files that must exist when the line is built.
A. Caps in Settings (#6346, #6347)
ai.cloud.monthly-cap-in-settings[PARTIAL] (#6346; engine built; Step 1.2 built the Settings fields (CloudCapsSection,CloudCapsStore), uncompiled until the build rung) — Settings > AI > Cloud has “This Mac a month, at most”, an app setting (cloud_monthly_cap_usdin the app DB, besidemodels_may_run), default US$10;spend.cap_usd()reads it for a project with nocloud_spend_cap_usdanswer, in place of the constantDEFAULT_CAP_USD. Tests:fichero-server/tests/unit/llm/test_app_cloud_caps_6346.py,fichero/Tests/Unit/general/Views/Settings/CloudCapsSettingsTests.swift.ai.cloud.daily-cap[PARTIAL] (#6347; engine built: the ledger, the hold, the plan line, the project’s route and the refusal words, also pinned byfichero-server/tests/unit/recipes/test_daily_cap_paths_6347.py; the Set Up field and the typed refusal are Steps 1.2 and 3.1) — the ledger (recipe/cloud-spend.json) keeps adayandday_usdbeside the month; a daily cap (the app’scloud_daily_cap_usd, or the project’scloud_daily_cap_usdanswer, normalised like the monthly one: 0 is a cap, below 0 refused, empty is none) is a third ceiling in_past_a_cap,_cap_stopandplan_line(over_day,needed_day_cap_usd), named in words when it refuses (“capped at $N a day, of which $M is spent today”). Tests:fichero-server/tests/unit/llm/test_daily_cloud_cap_6347.py(a day rolls over; the daily cap refuses first when lower; a run cap, a daily cap and a monthly cap all hold through the one hold).ai.cloud.caps-are-one-audited-action[PARTIAL] (#6346; built: the auditedapp.set_cloud_caprow andPUT/GET /api/ai/cloud-caps, a project’s daily answer onPUT /api/recipes/project/cloud-cap; NOT built: Undo, by decision 10; the route test sets the cap back to itsfromfigure instead;project.set_budgetis the existingproject.save_setupbehind that route) — the app caps are set through one audited action,app.set_cloud_cap(which cap, from, to; undoable), routePUT /api/ai/cloud-capswithGETbeside it, so MCP and the CLI get it from the regen; a project’s daily answer rides on the existingproject.set_budget. Tests:fichero-server/tests/unit/api/test_cloud_caps_route_6346.py(set, read back, undo, below 0 refused).ai.cloud.set-up-shows-the-defaults[PARTIAL] (#6346; built, uncompiled: the daily field with the app’s daily cap as its greyed prompt,cloud_daily_cap_usdin the answers, and a line naming the app’s figures while the project has no answer; the monthly field still shows the held figure, not a greyed one) — Set Up’s Budget block (designer.budget.beside-the-estimate) shows the app’s figure greyed as the default when the project has no answer, and a daily field beside the monthly one. Tests:fichero/Tests/Unit/general/Models/MoneyAndPlaceAnswersTests.swift(extended).
B. Images to the cloud (#6348, #6022, #6037, #6031)
ai.cloud.images-default-in-settings[PARTIAL] (#6348; the words built, uncompiled) — the Settings > AI “Allow cloud AI services” switch (CloudAccessSection,PUT /api/recipes/places) is the app-wide default for whether pages may leave. Built: the switch andplaces.inherits_cloud()for a project with no answer. Not built: the count of projects that answered for themselves. Tests:fichero/Tests/Unit/general/Views/Settings/CloudAccessSectionTests.swift.ai.cloud.project-overrides-the-default[PARTIAL] (#6348, #6022 place 1; engine built:may_leave_tofor the cloud,project.allow_cloudwithallowed, and the call-time gate (llm._enforce_local_only_provider) now judges the cloud by the project’s answer, not by the app’s places answer; the Set Up question reads the samecloud_allowedanswer but is uncompiled, Step 2.2) — a project’scloud_allowedanswer wins over the app switch in both directions:places.project_says_cloudreturns the project’s own answer when it has one (today a project may only be stricter); the existing auditedproject.allow_cloudtakesallowed: boolso one action sets yes or no (undoable, Set Up’s question shows the same answer). Tests:fichero-server/tests/unit/recipes/test_project_cloud_override_6348.py(app off + project yes sends; app on + project no refuses; no answer inherits; the gateegress.project_allows_leavingagrees),fichero-server/tests/unit/recipes/test_places_cap_projects_5828.py(updated: the cap stays for every place but cloud).ai.cloud.switch-in-the-project[PARTIAL] (#6022 place 1; built, uncompiled: the Inspector’s Cloud section withProjectCloudSwitchwords, and the Project menu’s “Allow Cloud AI Services for This Project” toggle (FocusedCloudSwitchButton); the “as Settings” state is shown only in the Inspector) — the project’s Inspector and the Project menu show “Allow cloud AI services for this project” (on, off, or “as Settings: on/off”), calling the action above. Tests:fichero/Tests/Unit/general/Views/ProjectCloudSwitchTests.swift(three states from a served answer).ai.cloud.switch-in-settings[OK] (#6022 place 2, #6031) — the Settings switch sets the places answer (CloudAccessSection;test_places_cap_the_routes_5831.py).ai.cloud.switch-in-set-up[OK] (#6022 place 3, #6031) — Set Up asks it (designer.rank.cloud-permission-said-once) and the step menu offers “Allow Cloud for This Project” (StepChoiceMenusView).ai.cloud.switch-at-first-launch[OK] (#6022 place 4) — first-launch setup asks where models may run (WhatFicheroRunsFields,FirstRunWindow,AppPlacesStore).ai.cloud.finder-carries-the-permission[PARTIAL] (#6037) — the finder route takescloud_allowedand ANDs it with the places (api/routes/system/recipes.pyfinder route), and the finder’s Allow Cloud Models button saves the yes and reloads with it (ModelFinderView, uncompiled). Not built: the finder opened from Settings (no step) has no button; after B’s override the button calls the one action and the reload reads the engine’s answer, not a flag the app sets. Tests:fichero/Tests/Unit/general/Models/ModelFinderStoreTests.swift(extended),fichero-server/tests/unit/recipes/test_cloud_candidates_need_permission_5768.py(extended).ai.cloud.never-sent-while-off[OK] (#6028) — a cloud call under a project that may not send is refused at the gate and at validation; nothing leaves (test_one_egress_gate_5368.py,test_egress_gate_every_call_site.py). The refusal’s WORDS and action are C below.
C. A refusal is an alert with a way through (#6349, #6028, #6022, #6350)
ai.cloud.one-typed-refusal[PARTIAL] (#6349, #6350; Step 3.1a built:llm/refusal.py, on both errors, the execute 400’sdetail.refusal, a paused run’sstopped_refusaland a page failure’srefusal; theallow-everywhereandallow-projectbuttons act through the existing actions, app side is Step 3.2) — every refusal for money or images is one served shape,CloudRefusal:kind(cap-monthly·cap-daily·cap-project·cap-run·images),scope(app·project),project,cap_usd,spent_usd,estimate_usd(this call’s worst case, or the run’s estimate),words, andfixes[](raise-towithusd, aimed at the scope the refusal names, so an app cap raises the app setting;allow-everywhere, forimagesonly: sets the APP default through the audited places action;allow-project;allow-once;over-cap-once;open-settingswith the control’s id,settings.ai.cloudAllowedorsettings.ai.cloudCaps), extendingdesigner.budget.refusal-offers-the-fix’sfixes[]and_cap_stop’s figures. It rides onCloudSpendRefusedErrorandEgressRefusedErroras a field, on the validation 400 asdetail.refusal, on a run’s paused-at-cap status (spend.stopped_at_cap) and on the per-page failure (categoryegress_refusedgainsspend_refused). Tests:fichero-server/tests/unit/llm/test_cloud_refusal_shape_6349.py(each kind, each fix includingallow-everywhere, the words name the figure).ai.cloud.hand-run-refused-before-it-starts[PARTIAL] (#6349, #6028; Step 3.1a built the typed 400; the onerefusedstream event is built (execution.runner.refused_event, sent as the run pauses at a cap); the app listens for it:WorkflowStreamEvent.refused, and the alert’s answer resumes the paused run with the once overrides, uncompiled) — a hand run (POST /api/workflow-execution/execute) refused at validation for images answers the typed refusal, not prose alone; a run whose first cloud call would not fit a cap is refused at that call and paused (built:_STOPPED_AT_CAP), and the execution stream sends onerefusedevent carrying the refusal so the app need not read a sentence. Tests:fichero-server/tests/unit/api/test_execute_refusal_is_typed_6349.py,fichero-server/tests/unit/workflows/test_paused_at_cap_event_6349.py. Built, uncompiled: the 400 is declared as the sharedErrorDetail(a sentence or an object, #5094) and the app readsmessageandrefusalout of that object itself (CloudRefusedBody). Tests:fichero-server/tests/unit/api/test_structured_refusals_declared_5094.py::test_execute_declares_its_400_refusal_as_error_detail,fichero/Tests/Unit/general/Models/CloudRefusedBodyTests.swift.ai.cloud.one-run-overrides[PARTIAL] (#6349, #6350; Step 3.1b built: the two flags on the execute and resume requests,llm/run_overrides.pyread by the gate and the hold, the spend still booked; the recipe Start’s two flags are built too (tests/unit/recipes/test_recipe_start_one_run_overrides_6350.py); the run status serves the Activity words asonce_wordsand the project run strip says them beside its line (ProjectRunStripStateTests, uncompiled)) — the execute request (and a recipe Start) takeallow_cloud_once: boolandover_cap_once: bool; both are kept on the run row (likerun_cap_usd), read by the gate and the hold for calls of that run only, written to no project or app setting, and shown on the run’s Activity row (“cloud allowed for this run” / “ran past the cap by your say”); spend is still booked. Resume after a pause at the cap accepts the same two flags. Tests:fichero-server/tests/unit/llm/test_one_run_overrides_6349.py(the next run is refused again; the ledger still books; the row says so).ai.cloud.alert-on-hand-run-paths[PARTIAL] (#6349, #6028, #6022; built, uncompiled:CloudRefusalAlerton a refused hand run from the context menu, the workflow bar and the selection runner, with the images buttons and the once overrides; “Raise the cap to $N” raises the cap the refusal names through the audited route for its scope (the app’s monthly or daily, or the project’s) and sends the run again; a run paused at a cap raises the same alert from therefusedevent and the answer resumes that run (resumeWorkflowtakes the two flags)) — the context menu, the workflow bar and the runner show oneCloudRefusalAlertbuilt from the served refusal: its words, then the fixes as buttons: for a cap “Raise the cap to $N” (the audited action for the scope the refusal names), “Run past the cap this once”, “Open Settings…”; for images “Allow for all projects” (the audited places action: the app default), “Allow for this project” (project.allow_cloud), “Allow this once”, “Open Settings…”; never a raw “Server error (400)”. After any button the app re-sends the execute (a refusal before the run started) or resumes the run (a pause at the cap) with the override, without the person starting it again.importErrorkeeps no cloud refusal. Tests:fichero/Tests/Unit/general/Views/CloudRefusalAlertTests.swift(buttons from each served kind, images showing the four in that order; “Allow for all projects” sets the app default and no project answer; the re-send carries the flag; a refusal with no fixes shows Open Settings only),fichero/Tests/Unit/general/Models/CloudCapFixTests.swift(extended).ai.cloud.allow-everywhere-sets-the-default[GAP] (#6349, #6348) — theallow-everywherefix of animagesrefusal calls the audited places action (the Settings switch’s own), so one yes ends the question for every project that has not answered for itself; noproject.allow_cloudrow is written. Tests:fichero-server/tests/unit/llm/test_cloud_refusal_shape_6349.py(the fix names the places action),fichero/Tests/Unit/general/Views/CloudRefusalAlertTests.swift(the button sets the app default, no project answer).ai.cloud.cli-refuses-in-words[PARTIAL] (#6350; Step 3.3 builtfichero workflow run: the words, the figures, each way through as a command or flag, exit 3; a recipe start takes the same two flags from the regen; a start’s refusals are the plan’s, not a 400, and are not built) —fichero workflow runand a recipe start print the refusal’s words, the figures, and the route: the flags--allow-cloud-onceand--over-cap-once, the commands that set the caps and the project’s yes (from the regen), and the Settings control; exit code 3, never a traceback. Tests:fichero-cli/tests/test_cli_cloud_refusal_6350.py.ai.cloud.mcp-refuses-in-words[PARTIAL] (#6350; Step 3.3 builtfichero_workflow_run:detail.refusalintact and the message namingallow_cloud_once,over_cap_onceand the tools; the recipe start tool takesallow_cloud_onceandover_cap_oncefrom the regen; a start’s refusals are the plan’s and not yet typed) —fichero_workflow_runand the recipe start tool returnEngineErrorwithdetail.refusalintact and the tool’s own argumentsallow_cloud_once,over_cap_oncenamed in the words; the cap and allow actions are tools from the regen. Tests:fichero-server/tests/unit/mcp/test_mcp_cloud_refusal_6350.py.
D. The plan knows before Start (#6097, #6098, #6099, #6031)
ai.cloud.plan-knows-a-dead-key[OK] (#6097; Step 4.1) — the Start plan reads the provider dead marks (llm/retry._DEADwithfatal_cause) and skips a step whose provider is out of credit or has a refused key, with that cause’s words (ai.where.dead-provider-says-why) and the fixchoose-model; a rate limit ranks the provider down, not out; the mark outlives its 30 s for the plan’s purpose (kept with its time, read-only). Tests:fichero-server/tests/unit/recipes/test_plan_knows_dead_key_6097.py.ai.cloud.plan-checks-the-capability[OK] (#6098; Step 4.1) — a step’s row must have the capability its job needs (start._capability,llm._model_has_capability); a row that lacks it is skipped at plan time with the validation’s words andchoose-model, so no Read fails at validation for it. Built beside it: remote reader cards inherit their provider’s vision (test_remote_reader_cards_inherit_vision.py, #6031). Tests:fichero-server/tests/unit/recipes/test_plan_checks_capability_6098.py.ai.cloud.no-model-names-the-missing-row[OK] (#6099; Step 4.1) — when a key is set for a provider with no provider row, the “no model” line says so and names the place: “a key is set forbut Settings > AI > Providers has no row for it; add the row”. Extends provider_without_key’s neighbour inrecipes/start.py. Tests:fichero-server/tests/unit/recipes/test_no_model_names_the_row_6099.py.
Out of this cluster from #6031: reader tiers, HTR-United hidden, RecipeCard remote source (the finder spec).
Build order (engine first; each step shippable alone; one batch of at most ~25 files)
Stage 1 — Caps in Settings
Step 1.1 — App-wide monthly and daily caps in the engine
- Issues: #6346, #6347
- Behaviours:
ai.cloud.monthly-cap-in-settings(engine),ai.cloud.daily-cap,ai.cloud.caps-are-one-audited-action - Files:
llm/spend.py,recipes/answers.py,recipes/cloud_cap.py, a newapi/routes/ai/cloud_caps.py, the OpenAPI regen - Tests: fichero-server/tests/unit/llm/test_app_cloud_caps_6346.py, fichero-server/tests/unit/llm/test_daily_cloud_cap_6347.py, fichero-server/tests/unit/api/test_cloud_caps_route_6346.py
- Size: M
Step 1.2 — The two fields in Settings and Set Up
- Issues: #6346, #6347
- Behaviours:
ai.cloud.monthly-cap-in-settings(app),ai.cloud.set-up-shows-the-defaults - Files:
Views/Settings/AI/AISettingsView+Tabs.swift(aCloudCapsSectionbesideCloudAccessSection), aCloudCapsStore,RecipeSetupAnswers.swift,RecipeSetupPlanFields.swift - Tests: fichero/Tests/Unit/general/Views/Settings/CloudCapsSettingsTests.swift, fichero/Tests/Unit/general/Models/MoneyAndPlaceAnswersTests.swift
- Size: S
Stage 2 — Images to the cloud: default and override
Step 2.1 — The project’s answer wins; one action sets yes or no
- Issues: #6348, #6022
- Behaviours:
ai.cloud.project-overrides-the-default,ai.cloud.never-sent-while-off(re-pinned) - Files:
recipes/places.py,llm/egress.py,api/routes/system/recipes.py(project.allow_cloudwithallowed), the regen - Tests: fichero-server/tests/unit/recipes/test_project_cloud_override_6348.py, fichero-server/tests/unit/recipes/test_places_cap_projects_5828.py, fichero-server/tests/unit/llm/test_one_egress_gate_5368.py
- Size: S
Step 2.2 — The switch in the project, the Settings words, the finder’s permission
- Issues: #6348, #6022, #6037
- Behaviours:
ai.cloud.images-default-in-settings,ai.cloud.switch-in-the-project,ai.cloud.finder-carries-the-permission - Files:
AISettingsView+Tabs.swift(CloudAccessSection), an Inspector project section and the Project menu,ModelFinderView.swift,ModelFinderStore.swift,RecipeSetupStore.swift(allowCloud(allowed:)) - Tests: fichero/Tests/Unit/general/Views/Settings/CloudAccessSectionTests.swift, fichero/Tests/Unit/general/Views/ProjectCloudSwitchTests.swift, fichero/Tests/Unit/general/Models/ModelFinderStoreTests.swift
- Size: M
Stage 3 — A refusal is an alert with a way through
Step 3.1 — One typed refusal, the one-run overrides, the stream event
- Issues: #6349, #6350, #6028
- Behaviours:
ai.cloud.one-typed-refusal,ai.cloud.hand-run-refused-before-it-starts,ai.cloud.one-run-overrides - Files:
llm/spend.py,llm/__init__.py(EgressRefusedError),execution/runner.py(_typed_failure),api/routes/workflow_execution/core.py,recipes/start.py,recipes/cloud_cap.py, the run row store, the regen - Tests: fichero-server/tests/unit/llm/test_cloud_refusal_shape_6349.py, fichero-server/tests/unit/api/test_execute_refusal_is_typed_6349.py, fichero-server/tests/unit/workflows/test_paused_at_cap_event_6349.py, fichero-server/tests/unit/llm/test_one_run_overrides_6349.py
- Size: L (split the overrides out as 3.1b if the batch passes ~25 files)
Step 3.2 — The alert on the hand-run paths
- Issues: #6349, #6028, #6022
- Behaviours:
ai.cloud.alert-on-hand-run-paths - Files: a new
Views/Shell/CloudRefusalAlert.swift,ContentView+WorkflowActions.swift(failWorkflowStart, the stream handler), the workflow bar’s run,LibraryView+ContextMenu.swift,CloudCapFixTestshelpers - Tests: fichero/Tests/Unit/general/Views/CloudRefusalAlertTests.swift, fichero/Tests/Unit/general/Models/CloudCapFixTests.swift
- Size: M
Step 3.3 — The CLI and MCP say it and offer the route
- Issues: #6350
- Behaviours:
ai.cloud.cli-refuses-in-words,ai.cloud.mcp-refuses-in-words - Files:
fichero-cli/src/fichero_cli/__main__.py(workflow_run, the recipe start command),fichero-cli/src/fichero_cli/client.py,fichero-mcp/src/fichero_mcp/server.py, the regen outputs - Tests: fichero-cli/tests/test_cli_cloud_refusal_6350.py, fichero-server/tests/unit/mcp/test_mcp_cloud_refusal_6350.py
- Size: S
Stage 4 — The plan knows before Start
Step 4.1 — Dead key, capability, missing row
- Issues: #6097, #6098, #6099, #6031
- Behaviours:
ai.cloud.plan-knows-a-dead-key,ai.cloud.plan-checks-the-capability,ai.cloud.no-model-names-the-missing-row - Files:
recipes/start.py,llm/retry.py(a read-onlydead_marks()),recipes/run_view.py - Tests: fichero-server/tests/unit/recipes/test_plan_knows_dead_key_6097.py, fichero-server/tests/unit/recipes/test_plan_checks_capability_6098.py, fichero-server/tests/unit/recipes/test_no_model_names_the_row_6099.py
- Size: S
Decisions I made (overrule any in one line)
- App cap = default, not a ceiling. The owner said a project’s own cap overrides the app’s, so the app caps fill
in for a project with no answer and the hold judges one project ledger as today. Alternative if the owner wants a
wallet guard across projects: an app ledger booked beside the project’s and the lower of the two refusing; one more
file in Step 1.1, and the refusal’s
scopealready says which. - Defaults: monthly US$10 (today’s constant, now editable); daily none. Empty = no cap; 0 = a cap of zero (nothing
sent); below 0 refused, as
answers.normalisedoes now. - Daily and monthly both hold; the lower remainder refuses first, named. Day and month are UTC calendar units as
the ledger is today (the owner may prefer the Mac’s local day; one line in
_month’s neighbour). - Per-project override of the images switch goes both ways. This relaxes
source.onboard.places-cap-projectsfor the cloud place only; the other places (another Mac, Hugging Face, ACENET) keep the app cap. If the owner wants “Settings off” to stay a guarantee, drop the “project yes over app no” half and Step 2.1 shrinks to the action’sallowedparameter. - “Allow once” and “past the cap once” persist on the run row only, shown in Activity, never in a setting; a second run meets the rule again. Spend past the cap is still booked, so the next refusal counts it.
- “Raise the cap” raises the cap the refusal names (project monthly, project daily, app monthly, app daily, or the
run cap), to the figure the engine serves (
needed_*, to the cent, no margin), through the existing audited actions. - The refusal before a hand run starts is only for images (validation already sees the model); a cap is judged at the first cloud call and the run pauses, because a hand run has no plan estimate today. A pre-run estimate for hand runs is a later line, not this release.
- CLI exit code 3 for a cloud refusal, distinct from 1 (any error), so a script can tell a refusal from a failure.
- Settings control ids
settings.ai.cloudAllowed(exists) andsettings.ai.cloudCaps(new) are whatopen-settingsdeep-links to. - The app caps are audited, not on the undo stack, same as places (manager ruling 2026-11-04, delegated by the owner):
app.set_cloud_capwrites its audit row in the account chain and a person undoes it by setting the cap back to the row’sfromfigure, asPUT /api/recipes/placesdoes. Undo for app-chain audits is a later line, not this release.