segreant 0.1.0 → 0.2.0

package/dist/dashboard/web/app/core/actions.js

@@ -10,8 +10,68 @@
 import { api } from './api.js';
 import { h } from './dom.js';
 import { signal } from './signal.js';
-import { isPrecise, usd, count } from './fmt.js';
+import { isPrecise, usd, usdFromMicros, share, count, basisWords } from './fmt.js';
+import { residualBoundWords, dayRange, quantizationWords } from './reconcileWords.js';
+import { localMidnightIso, dayAfterIso, monthRange, REASON_WORDS } from './periods.js';
+import { slug } from './slug.js';
+import { ruleFields, describeRule } from '../components/ruleFields.js';
+import { pricingUnknownAction, repriceAction } from './pricingActions.js';
+/**
+ * Sample data runs against a read-only configuration: the server refuses every
+ * settings write. The preview says so before Apply is offered, instead of
+ * enabling a button whose only outcome is a refusal (H005).
+ */
+const DEMO_SETTINGS_BLOCKED = 'This dashboard is showing sample data, so settings can\'t be changed here. Start Segreant without --demo to change your own.';
+/** Sample data refuses every ledger write; the preview says so before Apply. */
+const DEMO_LEDGER_BLOCKED = 'This dashboard is showing sample data, so nothing can be saved here. Start Segreant without --demo to change your own.';
+/** A value no quoting can carry literally into every shell the command may be pasted into. */
+class UnquotableValue extends Error {
+}
+/**
+ * A value as one literal shell word. Single quotes are literal in POSIX shells
+ * and in PowerShell; the double quotes JSON produces are not, so a name like
+ * `$(whoami)` pasted from the drawer ran in the shell and saved a different
+ * value from Apply. A value holding a single quote has no quoting that is
+ * literal in both, so the command is withheld instead of shown wrong.
+ */
+function shellWord(text) {
+    // Bare only when no shell gives the first character a meaning: a leading
+    // `@` is splatting in PowerShell, and a leading `-` would read as a flag.
+    if (/^[A-Za-z0-9._:/][A-Za-z0-9._:/@-]*$/.test(text))
+        return text;
+    // PowerShell closes a single-quoted string on the curly quotes too
+    // (U+2018, U+2019, U+201A, U+201B), so a name like O\u2019Brien broke out of
+    // the quoting and anything after it ran (Codex review 2026-10-16).
+    if (!/['\u2018\u2019\u201A\u201B]/.test(text) && !text.startsWith('-'))
+        return `'${text}'`;
+    throw new UnquotableValue();
+}
+/** The command a drawer shows, or null when a value cannot be written literally. */
+function quoted(build) {
+    try {
+        return build();
+    }
+    catch (e) {
+        if (e instanceof UnquotableValue)
+            return null;
+        throw e;
+    }
+}
+/** Tell the shell a claim changed, so the four-figure strip re-reads it (as the pages do). */
+function ledgerChanged(claim) {
+    window.dispatchEvent(new CustomEvent('segreant:ledger-changed', { detail: { claim } }));
+}
+/** Read a typed dollar amount: null for empty, NaN for anything unusable. */
+function enteredUsd(raw) {
+    const t = raw.trim();
+    if (t === '')
+        return null;
+    const n = Number(t);
+    return Number.isFinite(n) && n >= 0 ? n : Number.NaN;
+}
 const BUILDERS = {
+    'pricing-unknown': pricingUnknownAction,
+    reprice: repriceAction,
     'clear-proposals': (cap) => ({
         capability: cap,
         preview: async () => {
@@ -128,8 +188,20 @@ const BUILDERS = {
      */
     budget: (cap) => {
         const entered = signal('');
+        let adviceRead = null;
+        let advice;
+        const adviceSoon = () => {
+            adviceRead ??= api.value().then((v) => (advice = v.budget ?? null), () => (advice = null));
+            if (advice !== undefined)
+                return Promise.resolve(advice);
+            return Promise.race([adviceRead, new Promise((resolve) => setTimeout(() => resolve(undefined), 1200))]);
+        };
         return {
             capability: cap,
+            command: () => {
+                const amount = enteredUsd(entered());
+                return amount === null || Number.isNaN(amount) ? null : `segreant budget --daily ${amount}`;
+            },
             fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'budget-cap-input' }, isPrecise() ? 'New daily cap (USD)' : 'New daily limit, in dollars'), h('input', {
                 id: 'budget-cap-input',
                 class: 'drawer-input',
@@ -150,23 +222,40 @@ const BUILDERS = {
                 oninput: (event) => entered.set(event.target.value),
             }), h('p', { id: 'budget-cap-note', class: 'drawer-note', text: 'Leave this empty to change nothing. Enter 0 to block all spend.' })),
             preview: async () => {
-                const [settings, value] = await Promise.all([api.settings(), api.value()]);
+                const [settings, advice] = await Promise.all([api.settings(), adviceSoon()]);
                 const current = settings.budget?.dailyUsd ?? null;
-                const advice = value.budget ?? null;
+                // Validation is part of the preview, so a wrong amount is named before
+                // Apply and a corrected one re-enables it (H004).
+                const amount = enteredUsd(entered());
+                const blockedReason = settings.demo
+                    ? DEMO_SETTINGS_BLOCKED
+                    : amount === null
+                        ? 'Enter an amount to see the change. An empty field changes nothing.'
+                        : Number.isNaN(amount)
+                            ? 'That is not a usable amount. Enter a number of dollars, or 0 to block everything.'
+                            : amount === current
+                                ? 'The cap is already that amount, so nothing would change.'
+                                : undefined;
                 return {
-                    applicable: true,
+                    applicable: blockedReason === undefined,
+                    blockedReason,
                     summary: isPrecise()
                         ? 'Writes the daily cap to the local config file. Enforcement happens at the proxy, so only spend routed through it can be blocked.'
                         : 'Saves a new daily limit on this machine. Segreant can only actually block spend that goes through it.',
                     rows: [
                         { label: 'Current cap', value: current === null ? 'unlimited' : usd(current) },
-                        {
-                            label: 'Recommended',
-                            value: advice?.recommendedDailyUsd != null ? usd(advice.recommendedDailyUsd) : 'not established',
-                            note: advice?.canApply
-                                ? `from ${count(advice.basisDays)} days of observed spend`
-                                : 'not enough observed history to recommend acting on',
-                        },
+                        ...(amount !== null && !Number.isNaN(amount)
+                            ? [{ label: 'New cap', value: usd(amount), note: amount === 0 ? 'blocks every proxied request' : undefined }]
+                            : []),
+                        advice === undefined
+                            ? { label: 'Recommended', value: 'still being worked out', note: 'it comes from the value read; edit the amount or reopen to see it' }
+                            : {
+                                label: 'Recommended',
+                                value: advice?.recommendedDailyUsd != null ? usd(advice.recommendedDailyUsd) : 'not established',
+                                note: advice?.canApply
+                                    ? `from ${count(advice.basisDays)} days of observed spend`
+                                    : 'not enough observed history to recommend acting on',
+                            },
                         {
                             label: 'Counts toward the cap',
                             value: settings.budget?.capIncludesImported ? 'all observed spend' : 'live proxy spend only',
@@ -186,11 +275,12 @@ const BUILDERS = {
                 };
             },
             commit: async () => {
-                const raw = entered().trim();
-                if (raw === '')
+                // The preview already refused these; this guards a commit that races
+                // a field edit.
+                const parsed = enteredUsd(entered());
+                if (parsed === null)
                     return { ok: false, message: 'No value entered, so nothing was changed.' };
-                const parsed = Number(raw);
-                if (!Number.isFinite(parsed) || parsed < 0) {
+                if (Number.isNaN(parsed)) {
                     return { ok: false, message: 'That is not a usable amount. Enter a number of dollars, or 0 to block everything.' };
                 }
                 // `dailyUsd`, not `dailyCapUsd`. applySettingsPatch only copies keys it
@@ -205,6 +295,620 @@ const BUILDERS = {
             },
         };
     },
+    /**
+     * Add, rename or archive a cost centre: everything `segreant alloc centre`
+     * does. The Allocate page adds and archives; only here can an existing
+     * centre's name or owner change, because the page derives the id from the
+     * name and so can never reach a centre under a new name.
+     */
+    'alloc-centres': (cap) => {
+        const target = signal('');
+        // Separate from `target`: the regions below re-render only when whether a
+        // centre is chosen changes, never on the choice itself, so a keyboard user
+        // arrowing through the select keeps focus on it.
+        const editing = signal(false);
+        const archive = signal(false);
+        const name = signal('');
+        const owner = signal('');
+        let read = null;
+        const allocation = () => (read ??= api.allocation());
+        let open = [];
+        const id = () => target() || slug(name());
+        const fill = (inputId, value) => {
+            const input = document.getElementById(inputId);
+            if (input)
+                input.value = value;
+        };
+        return {
+            capability: cap,
+            command: () => quoted(() => {
+                if (!id())
+                    return null;
+                if (archive())
+                    return `segreant alloc centre ${id()} --archive`;
+                if (!name().trim())
+                    return null;
+                return `segreant alloc centre ${id()} --name ${shellWord(name().trim())}${owner().trim() ? ` --owner ${shellWord(owner().trim())}` : ''}`;
+            }),
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'centre-target' }, 'Cost centre'), h('select', {
+                id: 'centre-target',
+                class: 'drawer-input',
+                onchange: (event) => {
+                    const chosen = event.target.value;
+                    const centre = open.find((c) => c.costCentreId === chosen);
+                    target.set(chosen);
+                    if (editing() !== (chosen !== ''))
+                        editing.set(chosen !== '');
+                    archive.set(false);
+                    name.set(centre?.name ?? '');
+                    owner.set(centre?.owner ?? '');
+                    fill('centre-drawer-name', name());
+                    fill('centre-drawer-owner', owner());
+                    fill('centre-change', 'save');
+                },
+            }, 
+            // Built once; the centres are appended when they arrive. Rebuilding the
+            // select on arrival took focus, and the choice, from a reader who had
+            // already reached it.
+            (() => {
+                const placeholder = h('option', { value: '', text: 'A new cost centre' });
+                void allocation().then((d) => {
+                    open = d.costCentres.filter((c) => c.archivedAtMs == null);
+                    placeholder.after(...open.map((c) => h('option', { value: c.costCentreId, text: `${c.name} (${c.costCentreId})` })));
+                }, () => undefined);
+                return placeholder;
+            })()), () => editing()
+                ? h('div', null, h('label', { class: 'drawer-h3', for: 'centre-change' }, 'Change'), h('select', { id: 'centre-change', class: 'drawer-input', onchange: (event) => archive.set(event.target.value === 'archive') }, h('option', { value: 'save', text: 'Its name or owner' }), h('option', { value: 'archive', text: 'Archive it' })))
+                : null, h('label', { class: 'drawer-h3', for: 'centre-drawer-name' }, 'Name'), h('input', {
+                id: 'centre-drawer-name', class: 'drawer-input', maxlength: '120', autocomplete: 'off', placeholder: 'for example Engineering',
+                oninput: (event) => name.set(event.target.value),
+            }), h('label', { class: 'drawer-h3', for: 'centre-drawer-owner' }, 'Owner (optional)'), h('input', {
+                id: 'centre-drawer-owner', class: 'drawer-input', maxlength: '120', autocomplete: 'off', placeholder: 'who answers for it',
+                'aria-describedby': 'centre-drawer-note',
+                oninput: (event) => owner.set(event.target.value),
+            }), h('p', { id: 'centre-drawer-note', class: 'drawer-note', text: 'Saving replaces the owner, so an empty owner field clears it, as the command does.' })),
+            preview: async () => {
+                const d = await allocation();
+                const key = id();
+                const existing = d.costCentres.find((c) => c.costCentreId === key) ?? null;
+                const now = Date.now();
+                const namedBy = d.rules.filter((r) => r.revokedAtMs == null
+                    && (r.effectiveToMs == null || r.effectiveToMs > now)
+                    && !d.rules.some((o) => o.ruleId === r.ruleId && o.version > r.version)
+                    && r.targets.some((t) => t.costCentreId === key)).length;
+                if (archive()) {
+                    return {
+                        applicable: !d.demo && existing?.archivedAtMs == null,
+                        blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : existing?.archivedAtMs != null ? 'This cost centre is already archived.' : undefined,
+                        summary: isPrecise()
+                            ? 'Sets archived_at_ms on the centre. Recorded runs keep it; later runs do not allocate to it.'
+                            : 'Stops this cost centre receiving spend. Splits already recorded keep it, so they still add up.',
+                        rows: [
+                            { label: 'Cost centre', value: existing ? existing.name : key, note: key },
+                            { label: 'Rules that name it', value: count(namedBy), note: namedBy > 0 ? 'revise them on the Allocate page, or their share has nowhere to go' : undefined },
+                            { label: 'Reversible', value: 'not from here', note: 'an archived centre stays archived; saving it again only changes its name' },
+                        ],
+                    };
+                }
+                const typed = name().trim();
+                const blockedReason = d.demo
+                    ? DEMO_LEDGER_BLOCKED
+                    : !key
+                        ? 'Give the cost centre a name with at least one letter or number.'
+                        : !typed
+                            ? 'A cost centre needs a name.'
+                            : existing && existing.name === typed && (existing.owner ?? '') === owner().trim()
+                                ? 'Nothing would change yet: the name and owner are already these.'
+                                : undefined;
+                const unchanged = existing !== null && existing.name === typed && (existing.owner ?? '') === owner().trim();
+                const effect = !existing
+                    ? 'adds a new cost centre'
+                    : unchanged
+                        ? 'none yet; edit the name or owner'
+                        : existing.archivedAtMs != null
+                            ? 'renames an archived centre; it stays archived and still receives no spend'
+                            : 'changes its name or owner';
+                return {
+                    applicable: blockedReason === undefined,
+                    blockedReason,
+                    summary: isPrecise()
+                        ? 'Upserts one cost_centres row by id. Recorded runs keep the figures they were computed with.'
+                        : 'Saves this cost centre on this machine. Splits already recorded are not changed.',
+                    rows: [
+                        { label: 'Saved as', value: key || '—', note: target() ? 'the id stays the same' : 'derived from the name' },
+                        { label: 'Effect', value: effect },
+                        ...(existing ? [{ label: 'Now', value: existing.name, note: existing.owner ? `owner ${existing.owner}` : 'no owner' }] : []),
+                        { label: 'Rules that name it', value: count(namedBy) },
+                    ],
+                };
+            },
+            commit: async () => {
+                const key = id();
+                const result = archive()
+                    ? await api.write.allocation({ op: 'archive', id: key })
+                    : await api.write.allocation({ op: 'centre', id: key, name: name().trim(), ...(owner().trim() ? { owner: owner().trim() } : {}) });
+                read = null;
+                if (result.ok)
+                    ledgerChanged('allocation');
+                return { ok: result.ok, message: result.message ?? 'Saved.' };
+            },
+        };
+    },
+    /**
+     * Allocation rules: `segreant alloc rule` and `segreant alloc revoke`. The
+     * fields are the Allocate page's own (components/ruleFields.ts), so a rule
+     * written here is the rule written there; the preview says what it takes,
+     * where it sends it, and whether it replaces a current version.
+     */
+    'alloc-rules': (cap) => {
+        const revoking = signal(false);
+        const revokeId = signal('');
+        const ready = signal(null);
+        let read = null;
+        const load = () => (read ??= Promise.all([api.allocation(), api.overview('all').catch(() => null)]).then(([d, o]) => {
+            const open = d.costCentres.filter((c) => c.archivedAtMs == null);
+            const projects = o ? o.byProject.map((p) => p.label).filter((l) => l && l !== '(unattributed)') : [];
+            const models = o ? [...new Set(o.byModel.map((m) => m.label).filter(Boolean))] : [];
+            const r = { d, fields: ruleFields(open, () => projects, () => models, 'rule-drawer') };
+            ready.set(r);
+            return r;
+        }));
+        void load();
+        const nameOf = (d) => (id) => d.costCentres.find((c) => c.costCentreId === id)?.name ?? id;
+        const current = (d) => d.rules.filter((r) => r.revokedAtMs == null && !d.rules.some((o) => o.ruleId === r.ruleId && o.version > r.version));
+        const draft = () => {
+            const r = ready();
+            return r ? r.fields.build() : null;
+        };
+        return {
+            capability: cap,
+            command: () => quoted(() => {
+                if (revoking())
+                    return revokeId() ? `segreant alloc revoke ${revokeId()}` : null;
+                const x = draft();
+                if (!x || typeof x === 'string')
+                    return null;
+                const centre = x.rule.targets.map((t) => (x.rule.method === 'fixed_split' ? `${t.costCentreId}:${t.ratio}` : t.costCentreId)).join(',');
+                const match = Object.entries(x.rule.match).map(([k, v]) => ` --match-${k} ${shellWord(String(v))}`).join('');
+                const body = x.body;
+                return `segreant alloc rule ${x.id} --method ${x.rule.method} --centre ${centre}${match}`
+                    + (x.priority === null ? '' : ` --priority ${x.priority}`)
+                    + (body.from ? ` --from ${body.from}` : '')
+                    + (body.until ? ` --until ${body.until}` : '')
+                    + (x.owner ? ` --owner ${shellWord(x.owner)}` : '')
+                    + (x.note ? ` --note ${shellWord(x.note)}` : '');
+            }),
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'rule-drawer-change' }, 'Change'), h('select', { id: 'rule-drawer-change', class: 'drawer-input', onchange: (event) => revoking.set(event.target.value === 'revoke') }, h('option', { value: 'save', text: 'Add a rule, or a new version of one' }), h('option', { value: 'revoke', text: 'Revoke a rule' })), 
+            // Each region reads only whether its data has arrived or the choice
+            // above, so typing in a field never rebuilds the field.
+            () => {
+                if (!revoking())
+                    return null;
+                const r = ready();
+                if (!r)
+                    return h('p', { class: 'drawer-muted', text: 'Reading your rules…' });
+                return h('div', null, h('label', { class: 'drawer-h3', for: 'rule-drawer-revoke' }, 'Rule'), h('select', { id: 'rule-drawer-revoke', class: 'drawer-input', onchange: (event) => revokeId.set(event.target.value) }, h('option', { value: '', text: 'Choose a rule' }), ...current(r.d).map((rule) => h('option', { value: rule.ruleId, text: `${describeRule(rule, nameOf(r.d))} (${rule.ruleId})` }))));
+            }, () => {
+                if (revoking())
+                    return null;
+                const r = ready();
+                if (!r)
+                    return h('p', { class: 'drawer-muted', text: 'Reading your cost centres…' });
+                // A form with nowhere to send spend only fails at Apply; say so first.
+                if (!r.d.costCentres.some((c) => c.archivedAtMs == null)) {
+                    return h('p', { class: 'drawer-note', text: 'Add a cost centre first: a rule needs somewhere to send spend. Open "Cost centres" on this map, or use step 1 of Allocate.' });
+                }
+                return h('div', { class: 'rule-drawer-fields' }, ...r.fields.children);
+            }),
+            preview: async () => {
+                const { d } = await load();
+                const names = nameOf(d);
+                const live = current(d);
+                if (revoking()) {
+                    const rule = live.find((r) => r.ruleId === revokeId());
+                    if (!rule)
+                        return { applicable: false, blockedReason: live.length === 0 ? 'There are no current rules to revoke.' : 'Choose a rule to revoke.', summary: 'Stops a rule claiming spend from now on.' };
+                    return {
+                        applicable: !d.demo,
+                        blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : undefined,
+                        summary: isPrecise()
+                            ? 'Sets revoked_at_ms on every version of the rule. Recorded runs keep the splits computed under it.'
+                            : 'Stops this rule claiming spend. Splits already recorded keep their results, and the rule stays listed as revoked.',
+                        rows: [
+                            { label: 'Rule', value: describeRule(rule, names), note: `${rule.ruleId} v${rule.version}` },
+                            { label: 'Its spend goes to', value: 'the next rule that matches, or unallocated' },
+                            { label: 'Reversible', value: 'not as such', note: 'saving the same rule again starts a new version' },
+                        ],
+                    };
+                }
+                const x = draft();
+                if (x === null)
+                    return { applicable: false, blockedReason: 'Reading your cost centres…', summary: 'Decides which cost centre carries which spend.' };
+                if (typeof x === 'string')
+                    return { applicable: false, blockedReason: x, summary: 'Decides which cost centre carries which spend.' };
+                const existing = live.find((r) => r.ruleId === x.id) ?? null;
+                return {
+                    applicable: !d.demo,
+                    blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : undefined,
+                    summary: isPrecise()
+                        ? 'Saves an allocation_rules version. Recorded runs are unchanged; new previews use effective dates.'
+                        : 'Saves this rule on this machine. Splits already recorded are not changed; the next preview uses it.',
+                    rows: [
+                        { label: 'The rule', value: describeRule(x.rule, names) },
+                        { label: 'Saved as', value: x.id, note: existing ? `version ${existing.version + 1}; version ${existing.version} is kept and closed when this one starts` : 'a new rule' },
+                        { label: 'Checked in order', value: x.priority === null ? '100' : String(x.priority), note: 'lowest number first; the first rule that matches takes the request' },
+                        { label: 'Applies', value: x.from || x.until ? `${x.from ? `from ${x.from}` : 'from the start'}${x.until ? ` until ${x.until}` : ''}` : 'to all of your history' },
+                        ...(x.owner ? [{ label: 'Owner', value: x.owner }] : []),
+                        ...(x.note ? [{ label: 'Note', value: x.note }] : []),
+                    ],
+                };
+            },
+            commit: async () => {
+                if (revoking()) {
+                    const r = await api.write.allocation({ op: 'revoke', id: revokeId() });
+                    read = null;
+                    void load();
+                    if (r.ok)
+                        ledgerChanged('allocation');
+                    return { ok: r.ok, message: r.message };
+                }
+                const x = draft();
+                if (!x || typeof x === 'string')
+                    return { ok: false, message: typeof x === 'string' ? x : 'Nothing to save yet.' };
+                const r = await api.write.allocation(x.body);
+                read = null;
+                if (r.ok)
+                    ledgerChanged('allocation');
+                return { ok: r.ok, message: isPrecise() ? r.message : 'Rule saved. Splits already recorded keep their results; the next preview uses this rule.' };
+            },
+        };
+    },
+    /**
+     * Run an allocation: `segreant alloc run --from --to [--apply]`. The preview
+     * is the server's own computation for the period, refused if it does not
+     * conserve its input; Apply records exactly that run.
+     */
+    'alloc-run': (cap) => {
+        const ranges = [monthRange(-1), monthRange(0)];
+        const CUSTOM = String(ranges.length);
+        const chosen = signal('0');
+        const custom = signal(false);
+        const first = signal('');
+        const last = signal('');
+        let read = null;
+        const allocation = () => (read ??= api.allocation());
+        /** The period the fields name, or the reason they name none. */
+        const period = () => {
+            if (chosen() !== CUSTOM)
+                return ranges[Number(chosen())];
+            if (!first() || !last())
+                return 'Choose both the first and the last day of the period.';
+            if (last() < first())
+                return 'The last day must not be before the first day.';
+            // Both days are included: the period ends at the local midnight after the last one.
+            return { from: localMidnightIso(first()), to: dayAfterIso(last()) };
+        };
+        return {
+            capability: cap,
+            command: () => {
+                const p = period();
+                return typeof p === 'string' ? null : `segreant alloc run --from ${p.from} --to ${p.to} --apply`;
+            },
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'run-drawer-period' }, 'Period'), h('select', {
+                id: 'run-drawer-period', class: 'drawer-input',
+                onchange: (event) => {
+                    const value = event.target.value;
+                    chosen.set(value);
+                    if (custom() !== (value === CUSTOM))
+                        custom.set(value === CUSTOM);
+                },
+            }, ...ranges.map((r, i) => h('option', { value: String(i), text: r.label })), h('option', { value: CUSTOM, text: 'Choose dates…' })), () => custom()
+                ? h('div', null, h('label', { class: 'drawer-h3', for: 'run-drawer-first' }, 'First day'), h('input', { id: 'run-drawer-first', class: 'drawer-input', type: 'date', value: first.peek(), oninput: (event) => first.set(event.target.value) }), h('label', { class: 'drawer-h3', for: 'run-drawer-last' }, 'Last day (included)'), h('input', { id: 'run-drawer-last', class: 'drawer-input', type: 'date', value: last.peek(), oninput: (event) => last.set(event.target.value) }))
+                : null),
+            preview: async () => {
+                const p = period();
+                if (typeof p === 'string')
+                    return { applicable: false, blockedReason: p, summary: 'Splits the spend in a period across your cost centres, by your rules.' };
+                const [d, r] = await Promise.all([allocation(), api.write.allocation({ op: 'run', from: p.from, to: p.to })]);
+                const result = r.result;
+                if (!result)
+                    return { applicable: false, blockedReason: 'The server returned no split for this period.', summary: r.message };
+                const nameOf = (id) => d.costCentres.find((c) => c.costCentreId === id)?.name ?? id;
+                const shareOf = (m) => (result.totalMicros > 0 ? share(m / result.totalMicros, 1) : '—');
+                const blockedReason = d.demo
+                    ? DEMO_LEDGER_BLOCKED
+                    : !result.conserves
+                        ? 'This split does not add up to the spend it divides, so it cannot be recorded. Please report it.'
+                        : undefined;
+                return {
+                    applicable: blockedReason === undefined,
+                    blockedReason,
+                    summary: isPrecise()
+                        ? 'Previews alloc run for the period. Apply appends an immutable allocation run; recorded runs are never recomputed.'
+                        : 'This is how the estimated spend in the period would be split. Recording it saves this split; it is never recalculated later.',
+                    rows: [
+                        ...result.byCostCentre.map((c) => ({ label: nameOf(c.costCentreId), value: usdFromMicros(c.allocatedMicros), note: `${shareOf(c.allocatedMicros)} · ${count(c.requestCount)} requests` })),
+                        ...result.unallocated.map((u) => ({ label: `Unallocated: ${REASON_WORDS[u.reason] ?? u.reason.replace(/_/g, ' ')}`, value: usdFromMicros(u.micros), note: `${shareOf(u.micros)} · ${count(u.requestCount)} requests` })),
+                        { label: 'Total estimated spend', value: usdFromMicros(result.totalMicros), note: result.totalMicros > 0 ? 'list cost (estimate), not the provider bill' : 'no spend in this period' },
+                    ],
+                    notes: [
+                        ...(result.retention?.truncated ? ['Some records in this period were deleted by retention. The split covers what remains, so the unallocated part may be understated.'] : []),
+                        'Recorded splits are listed on the Allocate page, where each one downloads as CSV.',
+                    ],
+                };
+            },
+            commit: async () => {
+                const p = period();
+                if (typeof p === 'string')
+                    return { ok: false, message: p };
+                const r = await api.write.allocation({ op: 'run', from: p.from, to: p.to, apply: true });
+                read = null;
+                if (r.ok)
+                    ledgerChanged('allocation');
+                return {
+                    ok: r.ok,
+                    message: isPrecise() && r.allocationRunId
+                        ? `Recorded allocation run ${r.allocationRunId}.`
+                        : 'Recorded. The split is saved and listed under Saved splits on the Allocate page.',
+                };
+            },
+        };
+    },
+    /**
+     * Adopt an imported export as the provider side: `segreant billing
+     * openai-costs adopt --import-id <id> [--apply]`. No credential, no network;
+     * the preview is the server's adoption plan, refusals included.
+     */
+    'billing-adopt': (cap) => {
+        const chosen = signal('');
+        let read = null;
+        const billing = () => (read ??= api.billing());
+        return {
+            capability: cap,
+            command: () => (chosen() ? `segreant billing openai-costs adopt --import-id ${chosen()} --apply` : null),
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'adopt-drawer-import' }, 'Imported cost export'), h('select', { id: 'adopt-drawer-import', class: 'drawer-input', onchange: (event) => chosen.set(event.target.value) }, 
+            // Built once; the imports are appended when they arrive, so a reader
+            // already on the select keeps focus and their place.
+            (() => {
+                const placeholder = h('option', { value: '', text: 'Choose an export' });
+                void billing().then((d) => {
+                    placeholder.after(...d.imports.map((imp) => h('option', {
+                        value: imp.importId,
+                        text: `${imp.fileName} · ${dayRange(imp.periodStartMs, imp.periodEndMs)}${imp.inUse ? ' · in use' : ''}`,
+                    })));
+                }, () => undefined);
+                return placeholder;
+            })())),
+            preview: async () => {
+                const d = await billing();
+                const summary = isPrecise()
+                    ? 'Adopts an imported operator export as an operator_supplied observation for the declared scope. No credential is read and no request is made.'
+                    : 'Uses a cost export you already imported as the provider side of the comparison. Nothing is fetched and no key is used.';
+                if (!d.activeScope)
+                    return { applicable: false, blockedReason: 'Declare the OpenAI organisation and project first, so the export’s lines can be matched to it.', summary };
+                if (d.imports.length === 0)
+                    return { applicable: false, blockedReason: 'No cost export has been imported yet. Import one on the Close page first.', summary };
+                if (!chosen())
+                    return { applicable: false, blockedReason: 'Choose an export to see what would be used.', summary };
+                const p = (await api.write.billing({ op: 'adopt', importId: chosen() })).plan;
+                if (!p)
+                    return { applicable: false, blockedReason: 'The server returned no plan for this export.', summary };
+                if (!p.adoptable)
+                    return { applicable: false, blockedReason: p.detail ?? (p.refusal ? p.refusal.replace(/_/g, ' ') : 'This export cannot be used.'), summary };
+                const left = p.excluded && p.excluded.otherOrNoProjectRecordCount > 0
+                    ? { value: `${count(p.excluded.otherOrNoProjectRecordCount)} lines, ${usdFromMicros(p.excluded.otherOrNoProjectMicros)}`, note: 'no project, or another one' }
+                    : { value: 'none' };
+                return {
+                    applicable: !d.demo,
+                    blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : undefined,
+                    summary,
+                    rows: [
+                        { label: 'Matched to your project', value: `${count(p.matchedRecordCount)} lines, ${usdFromMicros(p.matchedMicros)}`, note: p.providerProjectRef },
+                        { label: 'Left out', ...left },
+                        { label: 'Days', value: dayRange(p.periodStartMs, p.periodEndMs) },
+                        { label: 'Evidence class', value: 'supplied by you', note: 'not read from the provider; every comparison built on it says so' },
+                    ],
+                };
+            },
+            commit: async () => {
+                const r = await api.write.billing({ op: 'adopt', importId: chosen(), apply: true });
+                read = null;
+                if (r.ok)
+                    ledgerChanged('billing');
+                return {
+                    ok: r.ok,
+                    message: isPrecise() && r.observationRunId
+                        ? `Adopted as observation ${r.observationRunId}.`
+                        : 'Recorded as the provider side for these days. You can now compare on the Close page or in the Reconcile drawer.',
+                };
+            },
+        };
+    },
+    /**
+     * Reconcile: `segreant billing reconcile [--materiality <usd>] [--apply]`.
+     * Readiness is checked first and its missing steps named; the comparison
+     * previewed is the server's own, under the threshold Apply records with.
+     */
+    'billing-reconcile': (cap) => {
+        const materiality = signal('');
+        let read = null;
+        const billing = () => (read ??= api.billing());
+        /** Blank is the server's default; NaN is a value nobody can record under. */
+        const threshold = () => {
+            const raw = materiality().trim();
+            if (raw === '')
+                return undefined;
+            const n = Number(raw);
+            return Number.isFinite(n) && n >= 0 ? n : Number.NaN;
+        };
+        return {
+            capability: cap,
+            command: () => {
+                const m = threshold();
+                if (m !== undefined && Number.isNaN(m))
+                    return null;
+                return `segreant billing reconcile${m === undefined ? '' : ` --materiality ${m}`} --apply`;
+            },
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'reconcile-drawer-materiality' }, 'Ignore daily differences up to ($)'), h('input', {
+                id: 'reconcile-drawer-materiality', class: 'drawer-input', type: 'number', min: '0', step: '0.01', inputmode: 'decimal', placeholder: '0.50',
+                'aria-describedby': 'reconcile-drawer-note',
+                oninput: (event) => materiality.set(event.target.value),
+            }), h('p', { id: 'reconcile-drawer-note', class: 'drawer-note', text: 'A day counts as different only when the bill and our measurement differ by more than this. Blank uses $0.50.' })),
+            preview: async () => {
+                const d = await billing();
+                if (d.readiness && !d.readiness.ready) {
+                    return {
+                        applicable: false,
+                        blockedReason: 'Not ready to compare yet. The preview lists the steps still to do.',
+                        summary: 'Compares what Segreant measured with what the provider billed, day by day, for the declared project.',
+                        rows: d.readiness.missing
+                            .filter((m) => !m.step.startsWith('observe a closed period — route A'))
+                            .map((m) => {
+                            // The server's detail is the terminal spelling. In plain words,
+                            // point at where the dashboard does the same step.
+                            const where = /scope/.test(m.step)
+                                ? 'Close step 1, or "Declare a provider scope" on this map'
+                                : /adopt|import/.test(m.step)
+                                    ? 'Close step 2, or "Adopt a provider export" on this map'
+                                    : m.detail;
+                            return { label: 'Still to do', value: m.step.replace(/^observe a closed period — route B, /, ''), note: isPrecise() ? m.detail : where };
+                        }),
+                    };
+                }
+                const m = threshold();
+                if (m !== undefined && Number.isNaN(m)) {
+                    return { applicable: false, blockedReason: 'That is not a usable amount. Enter dollars, or leave it blank for $0.50.', summary: 'Compares what Segreant measured with what the provider billed.' };
+                }
+                const r = (await api.write.billing({ op: 'reconcile', ...(m === undefined ? {} : { materialityUsd: m }) })).result;
+                if (!r)
+                    return { applicable: false, blockedReason: 'The server returned no comparison.', summary: 'Compares what Segreant measured with what the provider billed.' };
+                const residual = r.unexplainedVarianceMicros;
+                const contradicted = r.snapshotStability === 'changed_across_observations';
+                return {
+                    applicable: !d.demo,
+                    blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : undefined,
+                    summary: isPrecise()
+                        ? 'Previews billing reconcile for the declared scope. Apply appends a reconciliation run; the Billed claim then rests on it.'
+                        : 'This is how the provider’s bill compares with what Segreant measured. Recording it saves the comparison as evidence.',
+                    rows: [
+                        { label: 'Period', value: dayRange(r.periodStartMs, r.periodEndMs) },
+                        { label: 'Billed by the provider', value: usdFromMicros(r.providerReportedMicros) },
+                        { label: 'Measured by Segreant', value: usdFromMicros(r.localCapturedMicros), note: 'list cost (estimate)' },
+                        { label: 'Not explained', value: usdFromMicros(residual), note: r.providerReportedMicros > 0 ? `${share(residual / r.providerReportedMicros, 1)} of the bill` : undefined },
+                        { label: 'Days compared', value: `${count(r.coverage.daysWithBoth)} with both`, note: `${count(r.coverage.providerOnlyDays)} bill only · ${count(r.coverage.localOnlyDays)} ours only` },
+                        { label: 'Days that differ', value: count(r.coverage.materialDays), note: `by more than ${usd(r.materialityUsd)}` },
+                        { label: 'Provider side', value: basisWords(r.providerSourceKind) },
+                    ],
+                    notes: [
+                        residualBoundWords(r.offPathBound, isPrecise()),
+                        ...[quantizationWords(r.localQuantization, isPrecise())].filter((q) => q !== null),
+                        ...(contradicted ? ['The provider reported different figures for the same days at different times. This comparison would be contradicted.'] : []),
+                        ...r.conditions.map((c) => c.replace(/_/g, ' ')),
+                    ],
+                };
+            },
+            commit: async () => {
+                const m = threshold();
+                if (m !== undefined && Number.isNaN(m))
+                    return { ok: false, message: 'That is not a usable amount, so nothing was recorded.' };
+                const r = await api.write.billing({ op: 'reconcile', ...(m === undefined ? {} : { materialityUsd: m }), apply: true });
+                read = null;
+                if (r.ok)
+                    ledgerChanged('billing');
+                return {
+                    ok: r.ok,
+                    message: isPrecise() && r.reconciliationRunId
+                        ? `Recorded reconciliation run ${r.reconciliationRunId}.`
+                        : 'Recorded. The comparison is saved, and the Billed figure on the Close page now rests on it.',
+                };
+            },
+        };
+    },
+    /**
+     * Declare or clear the OpenAI organisation and project: `segreant billing
+     * scope set` and `clear`. The preview is the server's own dry run, so what
+     * the drawer shows is what the declaration would be, not a client guess.
+     */
+    'billing-scope': (cap) => {
+        const clear = signal(false);
+        const account = signal('');
+        const project = signal('');
+        let read = null;
+        const billing = () => (read ??= api.billing());
+        return {
+            capability: cap,
+            command: () => quoted(() => (clear()
+                ? 'segreant billing scope clear --apply'
+                : account().trim()
+                    ? `segreant billing scope set --account-ref ${shellWord(account().trim())}${project().trim() ? ` --project-ref ${shellWord(project().trim())}` : ''} --apply`
+                    : null)),
+            fields: () => h('div', null, h('label', { class: 'drawer-h3', for: 'scope-change' }, 'Change'), h('select', { id: 'scope-change', class: 'drawer-input', onchange: (event) => clear.set(event.target.value === 'clear') }, h('option', { value: 'set', text: 'Declare an organisation and project', selected: true }), h('option', { value: 'clear', text: 'Clear the declaration' })), () => clear()
+                ? null
+                : h('div', null, h('label', { class: 'drawer-h3', for: 'scope-drawer-account' }, 'Organisation id'), h('input', {
+                    id: 'scope-drawer-account', class: 'drawer-input', maxlength: '200', autocomplete: 'off', spellcheck: 'false', placeholder: 'org_…',
+                    // Rebuilt when the change switches back from Clear: show what Apply would send.
+                    value: account.peek(),
+                    oninput: (event) => account.set(event.target.value),
+                }), h('label', { class: 'drawer-h3', for: 'scope-drawer-project' }, 'Project id (optional)'), h('input', {
+                    id: 'scope-drawer-project', class: 'drawer-input', maxlength: '200', autocomplete: 'off', spellcheck: 'false', placeholder: 'proj_…',
+                    value: project.peek(),
+                    'aria-describedby': 'scope-drawer-note',
+                    oninput: (event) => project.set(event.target.value),
+                }), h('p', { id: 'scope-drawer-note', class: 'drawer-note', text: 'These are ids, not keys. Segreant never asks for an OpenAI key here.' }))),
+            preview: async () => {
+                const d = await billing();
+                const active = d.activeScope;
+                const current = active
+                    ? { label: 'Declared now', value: active.providerProjectRef ? `${active.billingAccountRef} / ${active.providerProjectRef}` : active.billingAccountRef, note: `to ${active.upstreamDisplay}` }
+                    : { label: 'Declared now', value: 'nothing' };
+                if (clear()) {
+                    const r = await api.write.billing({ op: 'scope-clear' });
+                    return {
+                        applicable: !d.demo && active != null,
+                        blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : active == null ? 'No project is declared, so there is nothing to clear.' : undefined,
+                        summary: r.message ?? 'Clearing stops matching future OpenAI requests to this project.',
+                        rows: [current, { label: 'Already recorded', value: 'unchanged', note: 'requests and recorded comparisons keep their figures' }],
+                    };
+                }
+                const ref = account().trim();
+                if (!ref) {
+                    return {
+                        applicable: false,
+                        blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : 'Enter the organisation id to see the declaration.',
+                        summary: 'Names the OpenAI organisation, and optionally the project, that requests through Segreant go to from now on.',
+                        rows: [current],
+                    };
+                }
+                const r = await api.write.billing({ op: 'scope', accountRef: ref, ...(project().trim() ? { projectRef: project().trim() } : {}) });
+                const p = r.scopePreview ?? {};
+                return {
+                    applicable: !d.demo,
+                    blockedReason: d.demo ? DEMO_LEDGER_BLOCKED : undefined,
+                    summary: isPrecise()
+                        ? 'Writes an operator_declared_unverified scope. Only future OpenAI proxy rows to the exact configured endpoint are captured.'
+                        : 'Your declaration, not checked with OpenAI. It applies to OpenAI requests that go through Segreant from now on.',
+                    rows: [
+                        current,
+                        { label: 'Will declare', value: project().trim() ? `${ref} / ${project().trim()}` : ref, note: typeof p['upstreamDisplay'] === 'string' ? `to ${p['upstreamDisplay']}` : undefined },
+                        { label: 'Past and imported spend', value: 'unchanged', note: 'it cannot be matched to the bill' },
+                    ],
+                    notes: ['Declaring replaces any earlier declaration for future traffic.'],
+                };
+            },
+            commit: async () => {
+                const result = clear()
+                    ? await api.write.billing({ op: 'scope-clear', apply: true })
+                    : await api.write.billing({ op: 'scope', accountRef: account().trim(), ...(project().trim() ? { projectRef: project().trim() } : {}), apply: true });
+                read = null;
+                if (result.ok)
+                    ledgerChanged('billing');
+                const plain = clear()
+                    ? 'Cleared. Future OpenAI requests through Segreant are no longer matched to a project. Past spend and recorded comparisons are unchanged.'
+                    : 'Declared for future OpenAI requests through Segreant. Past and imported spend is unchanged, and OpenAI has not checked this declaration.';
+                return { ok: result.ok, message: isPrecise() ? result.message ?? plain : plain };
+            },
+        };
+    },
     export: (cap) => ({
         capability: cap,
         preview: async () => ({
@@ -238,9 +942,12 @@ const BUILDERS = {
                 const settings = await api.settings();
                 const current = settings.features ?? {};
                 const target = turnOn() === 'on';
+                const blockedReason = settings.demo
+                    ? DEMO_SETTINGS_BLOCKED
+                    : current[key()] === target ? 'That switch is already set that way, so nothing would change.' : undefined;
                 return {
-                    applicable: current[key()] !== target,
-                    blockedReason: current[key()] === target ? 'That switch is already set that way, so nothing would change.' : undefined,
+                    applicable: blockedReason === undefined,
+                    blockedReason,
                     summary: isPrecise()
                         ? 'Writes one features.<key> boolean to the local config. A switched-off subsystem reports itself disabled wherever its output would appear.'
                         : 'Turns one optional part of Segreant on or off on this machine. Anything switched off says so instead of showing empty results.',
@@ -269,7 +976,9 @@ const BUILDERS = {
                 { label: 'Metadata only', value: settings['metadataOnly'] ? 'yes' : 'no', note: 'prompt and response bodies are never stored when on' },
                 {
                     label: 'Egress mode',
-                    value: settings.egress.mode === 'local_locked' ? 'local locked' : 'controlled cloud',
+                    value: settings.egress.mode === 'local_locked' ? 'local locked'
+                        : settings.egress.mode === 'controlled_cloud' ? 'controlled cloud'
+                            : 'invalid: every cloud request is refused until the egress section of config.json is repaired',
                     note: settings.egress.receipts.ok
                         ? settings.egress.rules.length + ' exact rule(s); ' + settings.egress.receipts.receiptCount + ' receipt(s); chain valid'
                         : 'receipt history INVALID; outbound requests refuse before dial until it is repaired. Restore the history; if the lock is stale, confirm no Segreant writer is active, then remove only that lock and rerun verify: ' + (settings.egress.receipts.errors[0] ?? 'history could not be verified'),
@@ -294,12 +1003,14 @@ export function actionSpec(cap) {
         capability: cap,
         preview: async () => ({
             applicable: false,
-            blockedReason: cap.coverage === 'planned'
-                ? 'This does not have a screen yet — run the command below.'
-                : 'This part is not wired into the GUI yet — run the command below.',
+            // Say what works now, not what might be built: "not built yet" is a
+            // promise, and a shipped screen that promises is a placeholder (L1).
+            // A command with <placeholders> is not runnable as shown: in a POSIX
+            // shell `<kind>` is an input redirection (PR #134 review).
+            blockedReason: `${cap.coverage === 'planned' ? 'This runs' : 'This part runs'} from the command line. ${cap.command.includes('<') ? 'Copy the command below, replace each part in angle brackets with your own value, then run it in a terminal.' : 'Copy the command below into a terminal.'}`,
             summary: cap.consequence === 'read'
-                ? `${cap.plain} Reading this from the GUI is not built yet; the command below does it.`
-                : `${cap.plain} Running this from the GUI is not built yet; the command below does it.`,
+                ? `${cap.plain} You read this from the command line, with the command below.`
+                : `${cap.plain} You do this from the command line, with the command below.`,
             notes: ['The System section lists exactly which capabilities the GUI covers and which it does not.'],
         }),
     };