segreant 0.1.0 → 0.2.0

package/dist/cli/allocCmd.js

@@ -7,14 +7,17 @@
  * a local rate-card estimate is legitimate and allocating one while implying it
  * is settled cost is not.
  */
-import { dbPath } from '../config.js';
+import { writeFileSync } from 'node:fs';
+import { dbPath, isDemo } from '../config.js';
+import { allocationRunToCsv } from '../export/allocationCsv.js';
 import { Store } from '../store/db.js';
 import { formatUsdMicros } from '../billing/types.js';
 import { displayUsd } from '../billing/reconcile.js';
 import { MATCH_FIELDS } from '../alloc/rules.js';
 import { color, C, printJson } from './ui.js';
+import { recordedTime } from '../util/time.js';
 function usage() {
-    console.error('  Usage: segreant alloc <centres|centre|rules|rule|revoke|run> [options]');
+    console.error('  Usage: segreant alloc <centres|centre|rules|rule|revoke|run|runs|export> [options]');
     console.error('         segreant alloc centre <id> --name "<name>" [--owner <who>]   add or update a cost centre');
     console.error('         segreant alloc centre <id> --archive                          retain it, stop it receiving');
     console.error('         segreant alloc rule <id> --method <direct|fixed_split|proportional_to_direct> \\');
@@ -24,6 +27,8 @@ function usage() {
     console.error('             a proportional_to_direct rule derives its split, so its centre takes ratio 0');
     console.error('         segreant alloc revoke <rule-id>');
     console.error('         segreant alloc run --from <ISO> --to <ISO> [--apply] [--json]');
+    console.error('         segreant alloc runs [--json]                                  recorded splits, newest first');
+    console.error('         segreant alloc export <run-id> [--out <file>]                 one recorded split as CSV');
     console.error('  Allocation is derived: it never modifies a request row, and never feeds budgets or RoI.');
 }
 function parseTs(value, label) {
@@ -81,7 +86,7 @@ function printRun(result, applied, tty) {
     if (result.byCostCentre.length === 0) {
         console.log(color(tty, C.gray, lost
             ? '  No spend that SURVIVES in this period reached a cost centre — rows before '
-                + `${day(lost.prunedBeforeMs ?? 0)} were deleted by retention, and whether they did cannot be read from here.`
+                + `${recordedTime(lost.prunedBeforeMs, true)} were deleted by retention, and whether they did cannot be read from here.`
             : '  No spend reached a cost centre in this period.'));
     }
     else {
@@ -101,7 +106,7 @@ function printRun(result, applied, tty) {
         // percentage moves for a reason that has nothing to do with the rules --
         // measured at 76.2% becoming 100.0% on a period 95% of whose spend went.
         console.log(color(tty, C.yellow, '  Retention deleted request rows from inside this period '
-            + `(before ${day(lost.prunedBeforeMs ?? 0)}), so the total above is what SURVIVES and the`));
+            + `(before ${recordedTime(lost.prunedBeforeMs, true)}), so the total above is what SURVIVES and the`));
         console.log(color(tty, C.yellow, '  percentages beside it are shares of that, not of what the period cost.'));
     }
     if (result.unallocated.length > 0) {
@@ -139,6 +144,70 @@ export function cmdAlloc(flags) {
     const action = typeof flags._[0] === 'string' ? flags._[0] : 'run';
     const store = new Store(dbPath());
     try {
+        if (action === 'runs') {
+            const runs = store.allocationRuns(50);
+            if (flags.json) {
+                return void printJson({
+                    runs: runs.map((r) => ({
+                        allocationRunId: r.allocationRunId,
+                        computedAtMs: r.computedAtMs,
+                        periodStartMs: r.result.periodStartMs,
+                        periodEndMs: r.result.periodEndMs,
+                        totalMicros: r.result.totalMicros,
+                        allocatedMicros: r.result.allocatedMicros,
+                        unallocatedMicros: r.result.unallocatedMicros,
+                    })),
+                });
+            }
+            console.log('');
+            if (runs.length === 0)
+                console.log(color(tty, C.gray, '  No recorded splits. Record one: segreant alloc run --from <ISO> --to <ISO> --apply'));
+            for (const r of runs) {
+                // A bound that is not midnight UTC keeps its time: printing the date
+                // alone made a split ending at 06:48 read as covering the whole day,
+                // and re-running those dates gave a different total.
+                const bound = (ms) => {
+                    const iso = new Date(ms).toISOString();
+                    // Every nonzero part of the time is kept: allocation includes rows by
+                    // the exact millisecond, so a bound shown to the minute could not be
+                    // copied back to reproduce the split (PR #142 review).
+                    if (iso.slice(11, 23) === '00:00:00.000')
+                        return iso.slice(0, 10);
+                    const time = iso.slice(17, 23) === '00.000' ? iso.slice(11, 16) : iso.slice(20, 23) === '000' ? iso.slice(11, 19) : iso.slice(11, 23);
+                    return `${iso.slice(0, 10)} ${time}Z`;
+                };
+                const period = `${bound(r.result.periodStartMs)} → ${bound(r.result.periodEndMs)} (end exclusive)`;
+                const share = r.result.totalMicros > 0 ? `${((r.result.allocatedMicros / r.result.totalMicros) * 100).toFixed(1)}% allocated` : 'nothing to allocate';
+                console.log(`  ${r.allocationRunId}  ${period}  ${displayUsd(r.result.totalMicros)}  ${color(tty, C.gray, share)}`);
+            }
+            if (runs.length > 0)
+                console.log(color(tty, C.gray, '\n  Export one as CSV: segreant alloc export <run-id> --out split.csv'));
+            return;
+        }
+        if (action === 'export') {
+            const id = typeof flags._[1] === 'string' ? flags._[1] : '';
+            if (id === '') {
+                console.error('  alloc export needs the run id: segreant alloc runs lists them.');
+                process.exitCode = 2;
+                return;
+            }
+            const run = store.allocationRunById(id);
+            if (run === null) {
+                console.error(`  No recorded allocation run has the id "${id}". segreant alloc runs lists them.`);
+                process.exitCode = 1;
+                return;
+            }
+            const names = new Map(store.costCentres().map((c) => [c.costCentreId, c.name]));
+            const csv = allocationRunToCsv(run, (costCentreId) => names.get(costCentreId) ?? costCentreId, isDemo());
+            if (typeof flags.out === 'string') {
+                writeFileSync(flags.out, csv);
+                console.error(color(tty, C.green, `  Exported the split for ${new Date(run.result.periodStartMs).toISOString().slice(0, 10)} → ${flags.out}`));
+            }
+            else {
+                process.stdout.write(csv);
+            }
+            return;
+        }
         if (action === 'centres') {
             const centres = store.costCentres();
             if (flags.json)

package/dist/cli/askModelPrices.js

@@ -0,0 +1,59 @@
+/**
+ * Ask once, at the end of an interactive `scan --setup`, for a price for the
+ * costliest models still priced by a guess: after the card and the public price
+ * list have had their turn, the person is the only one who knows what a private,
+ * fine-tuned or local model costs. Interactive terminals only, Enter skips, and
+ * at most five models, so a long tail never turns setup into a questionnaire.
+ */
+import { C, color, usd, num } from './ui.js';
+import { existsSync } from 'node:fs';
+import { dbPath } from '../config.js';
+import { unknownModels } from '../cost/declarations.js';
+import { Store } from '../store/db.js';
+import { promptForUnknownModels } from './pricingDeclareCmd.js';
+const MAX_ASKED = 5;
+/** Below this, a guess cannot move a total enough to be worth a question. */
+const MIN_COST_USD = 0.5;
+export async function askModelPrices(tty, io = {
+    input: process.stdin, output: process.stdout, interactive: process.stdin.isTTY === true,
+}) {
+    if (!io.interactive)
+        return 0;
+    if (!existsSync(dbPath()))
+        return 0;
+    const store = new Store(dbPath());
+    let all;
+    try {
+        all = unknownModels(store);
+    }
+    finally {
+        store.close();
+    }
+    const guessed = all.filter((m) => m.costUsd >= MIN_COST_USD);
+    if (guessed.length === 0)
+        return 0;
+    const asked = guessed.slice(0, MAX_ASKED);
+    const write = (line) => io.output.write(`${line}\n`);
+    write(color(tty, C.bold, '  Models priced by a guess') + color(tty, C.gray, '   not on the rate card (Enter skips)'));
+    for (const m of asked) {
+        const how = m.rateMatchKind === 'fallback' ? 'generic rate' : 'nearest model on the card';
+        write(color(tty, C.gray, `    ${m.model}: ${num(m.requests)} requests, ${usd(m.costUsd)} recorded (estimated, ${how})`));
+    }
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: io.input, output: io.output, terminal: false });
+    let made = 0;
+    try {
+        made = (await promptForUnknownModels(asked, {
+            ask: (question) => rl.question(`    ${question}: `),
+            print: (line) => write(color(tty, C.gray, `  ${line}`)),
+        })).length;
+    }
+    finally {
+        rl.close();
+    }
+    if (guessed.length > asked.length)
+        write(color(tty, C.gray, `    ${num(guessed.length - asked.length)} more: segreant pricing unknown`));
+    if (made > 0)
+        write(color(tty, C.gray, '  Recorded requests keep their estimate until you re-price them: segreant reprice (a preview), then --apply'));
+    return made;
+}

package/dist/cli/backupCmd.js

@@ -14,7 +14,8 @@ function requiredPath(flags, name) {
 }
 function emit(result, flags, action) {
     if (flags.json) {
-        printJson({ action, ...result });
+        const { schemaVersion: ledgerSchemaVersion, ...details } = result;
+        printJson({ action, ...details, ledgerSchemaVersion });
         if (!result.ok)
             process.exitCode = 1;
         return;

package/dist/cli/basisLines.js

@@ -0,0 +1,45 @@
+/**
+ * The lines that say how a CLI total was priced. Every command that prints a
+ * total with more than one part prints these under it, so the parts read the
+ * same everywhere (`today`, `week`, `month`, the first-run summary).
+ */
+import { cohortModels } from '../cost/basis.js';
+import { num, usd } from './ui.js';
+export function basisLines(basis, indent = '              ') {
+    const out = [];
+    for (const c of basis.cohorts) {
+        if (c.id === 'unpriced') {
+            out.push(`${indent}${num(c.requests)} requests not priced: ${cohortModels(c)} (no rate applies)`);
+            continue;
+        }
+        if (c.id === 'not_sent') {
+            out.push(`${indent}${''.padStart(10)}  ${num(c.requests)} requests refused before reaching the provider (no charge)`);
+            continue;
+        }
+        if (c.id === 'tool_reported' && c.costUsd < 0.005) {
+            // A free model is a real answer ("the tool said $0"), not a missing price.
+            out.push(`${indent}${''.padStart(10)}  ${num(c.requests)} requests the tool reported at no charge: ${cohortModels(c)}`);
+            continue;
+        }
+        if (c.id === 'user_free') {
+            out.push(`${indent}${''.padStart(10)}  ${num(c.requests)} requests on models you marked free: ${cohortModels(c)}`);
+            continue;
+        }
+        const models = c.id === 'fallback' || c.id === 'list_family' || c.id === 'user_declared' || c.id === 'unrecorded'
+            ? `: ${cohortModels(c)}`
+            : '';
+        out.push(`${indent}${usd(c.costUsd).padStart(10)}  ${c.label}${models}`);
+    }
+    if (basis.cohorts.some((c) => c.id === 'fallback')) {
+        out.push(`${indent}            fallback = the model was not on the rate card when imported; a generic rate, a rough estimate`);
+        out.push(`${indent}            segreant reprice  previews new prices for models the card has learned since (nothing changes without --apply)`);
+    }
+    if (basis.cohorts.some((c) => c.id === 'user_declared')) {
+        out.push(`${indent}            your price = set with segreant pricing set; not checked against a price list`);
+    }
+    if (basis.cohorts.some((c) => c.id === 'tool_reported')) {
+        out.push(`${indent}            tool-reported = what the tool recorded; not checked against any rate card or bill`);
+    }
+    out.push(`${indent}None of these is your bill.`);
+    return out;
+}

package/dist/cli/billingCmd.js

@@ -4,20 +4,29 @@
  * a least-privilege provider connector, but it cannot establish reconciliation.
  */
 import { writeFileSync } from 'node:fs';
-import { dbPath, loadConfig } from '../config.js';
+import { dbPath, isDemo, loadConfig } from '../config.js';
 import { OpenAiCostsPullError, previewOpenAiCosts, pullOpenAiCosts, } from '../billing/openaiCosts.js';
 import { newOpenAiScopeDeclaration } from '../billing/scope.js';
 import { assessAssumptionFragility } from '../epistemic/countermodel.js';
 import { reconciliationCountermodels } from '../billing/countermodels.js';
-import { describeOffPathBound, displayUsd, signedUsd } from '../billing/reconcile.js';
+import { describeLocalQuantization, describeOffPathBound, displayUsd, signedUsd } from '../billing/reconcile.js';
 import { reconciliationReadiness } from '../billing/readiness.js';
 import { formatUsdMicros } from '../billing/types.js';
 import { readBillingImportFile } from '../billing/importer.js';
 import { billingEvidenceToCsv } from '../export/billingCsv.js';
 import { Store } from '../store/db.js';
-import { printJson } from './ui.js';
+import { printJson as printJsonRaw, cliJsonResponse } from './ui.js';
+/**
+ * Billing JSON names sample data in the payload itself. The bill the demo
+ * carries is generated, and a comparison or export lifted out of the terminal
+ * must still say so; the dashboard's banner does not travel with it.
+ */
+function printJson(value) {
+    printJsonRaw(isDemo() && value !== null && typeof value === 'object' && !Array.isArray(value) ? { demo: true, ...value } : value);
+}
 import { stringifyJson } from '../util/json.js';
 import { moneyToJson } from '../economics/money.js';
+import { recordedTime } from '../util/time.js';
 function billingEgressRepairAction(failureCode) {
     return failureCode === 'egress_receipt_integrity_failed' || failureCode === 'egress_receipt_persistence_failed'
         ? 'Repair or restore the local receipt history before retrying; if the lock is stale, confirm no Segreant writer is active, then remove only that lock and rerun verify.'
@@ -66,12 +75,12 @@ function printCostsCoverage(coverage) {
     console.log(`  Snapshot      ${coverage.observation.observationRunId}`);
     console.log(`  Period        ${new Date(coverage.observation.periodStartMs).toISOString().slice(0, 10)} → ${new Date(coverage.observation.periodEndMs).toISOString().slice(0, 10)} (UTC, exclusive end)`);
     console.log(`  Provider rows ${coverage.observation.providerLineCount} (${coverage.observation.currencies.join(', ') || 'none'}); values intentionally not summed here`);
-    console.log(`  Declared route ${captured.requestCount} live proxy request(s), $${formatLocalEstimate(captured.costUsd)} local rate-card estimate (${captured.estimatedRequestCount} estimated)`);
+    console.log(`  Declared route ${captured.requestCount} live proxy request(s), $${formatLocalEstimate(captured.costUsd)} local estimate, not the bill (${captured.estimatedRequestCount} priced by a guess; the rest at list prices or prices you set)`);
     // Directly under the number it falsifies, and not in `Blockers`, which lists
     // the conditions that hold always (D-185). A zero here is what an operator
     // uses to decide whether minting an Admin credential is worth it.
     if (coverage.localLedgerRetention.truncated) {
-        const before = new Date(coverage.localLedgerRetention.prunedBeforeMs ?? 0).toISOString().slice(0, 10);
+        const before = recordedTime(coverage.localLedgerRetention.prunedBeforeMs, true);
         console.log(`  Local ledger  TRUNCATED — retention deleted rows before ${before}, inside the period above.`);
         console.log('                Every local count on this screen is what SURVIVES, so an empty declared');
         console.log('                route here is not evidence that the route captured nothing.');
@@ -93,7 +102,7 @@ function printReadiness(readiness) {
     // null. A guard that goes quiet leaves nothing on the screen to be wrong,
     // which is why the silence itself has to be reported (D-186).
     if (readiness.localLedgerRetention.truncated) {
-        const before = new Date(readiness.localLedgerRetention.prunedBeforeMs ?? 0).toISOString().slice(0, 10);
+        const before = recordedTime(readiness.localLedgerRetention.prunedBeforeMs, true);
         console.log('');
         if (c === null) {
             console.log(`  NO OPENAI SPEND SURVIVES HERE, and retention deleted rows before ${before}.`);
@@ -210,6 +219,10 @@ function printReconciliation(result, applied) {
     for (const line of wrapText(describeOffPathBound(result.offPathBound), 74)) {
         console.log(`    ${line}`);
     }
+    const rounding = describeLocalQuantization(result.localQuantization);
+    if (rounding)
+        for (const line of wrapText(rounding, 74))
+            console.log(`    ${line}`);
     console.log('');
     console.log(`  Coverage      ${result.coverage.daysWithBoth} day(s) with both sides · ${result.coverage.providerOnlyDays} provider-only · ${result.coverage.localOnlyDays} local-only`);
     console.log(`  Material      ${result.coverage.materialDays} day(s) differ by more than $${result.materialityUsd.toFixed(2)}`);
@@ -829,9 +842,32 @@ function wrapText(text, width) {
         lines.push(current);
     return lines;
 }
+/**
+ * A part's share of a whole, as a percentage label. Only the whole itself
+ * reads 100 and only nothing reads 0: rounding 99.6% up to 100% told the user
+ * the comparison covered everything when it did not (PR #142 review).
+ */
+export function coveragePercent(part, whole) {
+    if (part >= whole)
+        return '100';
+    if (part <= 0)
+        return '0';
+    const share = (part / whole) * 100;
+    if (share < 0.1)
+        return '<0.1';
+    if (share < 1)
+        return share.toFixed(1);
+    if (share >= 99.5)
+        return Math.min(99.9, Math.floor(share * 10) / 10).toFixed(1);
+    return String(Math.round(share));
+}
 /** `segreant billing` — immutable local provider-cost evidence, never an implicit reconciliation. */
 export async function cmdBilling(flags) {
     const action = typeof flags._[0] === 'string' ? flags._[0] : 'status';
+    // The same mark `show` and `home` print: everything below is generated.
+    if (isDemo() && !flags.json && !(action === 'export' && !flags.out)) {
+        console.log('  \u25CF DEMO DATA \u2014 synthetic, isolated in demo.db; this bill and comparison were generated, not received from a provider');
+    }
     if (action === 'scope') {
         cmdScope(flags);
         return;
@@ -919,7 +955,30 @@ export async function cmdBilling(flags) {
                 console.log(`  Imports       ${summary.importCount}`);
                 console.log(`  Charge lines  ${summary.recordCount}`);
                 console.log(`  Declared USD  $${formatUsdMicros(summary.providerReportedUsdMicros)}`);
-                console.log('  Reconcile     not_reconciled — imported reports and local request estimates are not yet scope-comparable.');
+                // A recorded comparison is the answer to "has this been reconciled?";
+                // the status line used to say not_reconciled whatever the ledger held.
+                const latest = store.reconciliationRuns(20);
+                if (latest.length === 0) {
+                    console.log('  Reconcile     not_reconciled — no comparison recorded yet. Preview one: segreant billing reconcile');
+                }
+                else {
+                    const run = latest[0].result;
+                    const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+                    console.log(`  Reconcile     ${latest.length === 20 ? '20+' : latest.length} recorded comparison(s); latest: ${run.providerProjectRef}, ${day(run.periodStartMs)} → ${day(run.periodEndMs)} (UTC, end exclusive)`);
+                    console.log(`                provider $${formatUsdMicros(run.providerReportedMicros)} · metered $${formatUsdMicros(run.localCapturedMicros)} · unexplained ${signedUsd(run.unexplainedVarianceMicros)} — scope-conditional, not a clean reconciliation`);
+                    // How much of what Segreant metered in that period the comparison
+                    // actually covers: one project's bill is not the month's spend.
+                    // Same day quantization as the comparison itself, so the share
+                    // cannot exceed the whole (PR #142 review).
+                    const metered = store.meteredMicrosLikeReconciliation(run.periodStartMs, run.periodEndMs, run.declaredScopeId);
+                    if (metered !== null && metered.onRouteMicros !== run.localCapturedMicros) {
+                        console.log('                coverage withheld: the ledger has changed for that period since this comparison was recorded; re-run segreant billing reconcile');
+                    }
+                    else if (metered !== null && metered.allMicros > 0) {
+                        console.log(`                covers $${formatUsdMicros(run.localCapturedMicros)} of the $${formatUsdMicros(metered.allMicros)} Segreant metered across all providers in that period (${coveragePercent(run.localCapturedMicros, metered.allMicros)}%)`);
+                    }
+                    console.log('                Details: segreant billing reconcile');
+                }
                 if (summary.lastImportedAtMs !== null)
                     console.log(`  Last import   ${new Date(summary.lastImportedAtMs).toISOString()}`);
                 if (imports.length > 0)
@@ -932,10 +991,10 @@ export async function cmdBilling(flags) {
             const records = store.billingEvidenceRecords();
             const summary = store.billingSummary();
             if (flags.json) {
-                writeOrPrint(stringifyJson({ summary, records }) + '\n', flags.out);
+                writeOrPrint(stringifyJson(cliJsonResponse({ ...(isDemo() ? { demo: true } : {}), summary, records })) + '\n', flags.out);
             }
             else {
-                writeOrPrint(billingEvidenceToCsv(records), flags.out);
+                writeOrPrint(billingEvidenceToCsv(records, isDemo()), flags.out);
             }
             return;
         }

package/dist/cli/capitalCmd.js

@@ -36,7 +36,8 @@ function usage() {
 function emit(payload, flags) {
     // Keep the JSON path canonical; --json is accepted for parity with other
     // review commands and the human form remains machine-readable by design.
-    void flags;
+    // Reading it marks it as used, so the dispatcher does not report it.
+    void flags.json;
     printJson(payload);
 }
 export function cmdCapital(flags) {

package/dist/cli/connectCmd.js

@@ -4,6 +4,7 @@
  * from cli.ts in the per-command-module split; only cmdConnect is exported,
  * the per-tool flows stay module-internal.
  */
+import { isBuiltInProviderUpstream, providerRuleCommand } from '../egress/policy.js';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
@@ -123,8 +124,8 @@ function wrapOpencodeFlow(cfg, flags, tty, providerName, path) {
         console.log(color(tty, C.green, `  ✓ Wrapped "${providerName}". opencode now routes through Segreant.`));
         console.log(color(tty, C.gray, `    opencode config: ${path}  (backup at ${path}.bak)`));
         console.log(color(tty, C.gray, `    Segreant upstreams.openai → ${res.originalBaseUrl}`));
-        console.log(color(tty, C.gray, `    Egress remains ${cfg.egress.mode}; this connection never grants cloud permission.`));
-        console.log(color(tty, C.gray, `    Review the provider's exact rule with: segreant egress plan ...`));
+        const forwarding = upstreamForwarding(res.originalBaseUrl);
+        console.log(color(tty, forwarding.ok ? C.gray : C.yellow, `    ${forwarding.text}`));
         console.log(color(tty, C.gray, '    JSON comments were reformatted away; your settings + keys are preserved.'));
         console.log('');
         console.log(color(tty, C.gray, '  Restart Segreant (segreant start), run opencode, then:  segreant sources'));
@@ -258,10 +259,11 @@ function connectOpencode(cfg, flags, tty) {
     finishConnectOpencode(tty);
 }
 /**
- * Antigravity's BUILT-IN Gemini agent routes through Google's own servers — a
- * managed backend no cooperative proxy can meter (same class as opencode Zen).
- * But Antigravity supports CUSTOM OpenAI-compatible providers (base URL + key),
- * and those we meter fully: provider → proxy → the upstream of your choice.
+ * Antigravity's BUILT-IN agent routes through Google's own servers, which no
+ * cooperative proxy sits in front of; its usage is read instead from the
+ * conversation databases Antigravity keeps locally (`segreant import
+ * antigravity`, src/connect/antigravity.ts). Its CUSTOM OpenAI-compatible
+ * providers can also be routed through the proxy: provider → proxy → upstream.
  * `--write` points the proxy's OpenAI upstream at Gemini's OpenAI-compatible
  * endpoint, the free-tier test path; the user's key passes through untouched.
  */
@@ -277,8 +279,10 @@ function connectAntigravity(cfg, flags, tty) {
     console.log('');
     console.log(color(tty, C.bold, '  Connect Google Antigravity as a source'));
     console.log(color(tty, C.gray, '  ' + '─'.repeat(52)));
-    console.log(color(tty, C.gray, '  Antigravity’s built-in Gemini agent runs on Google’s servers — unmeterable'));
-    console.log(color(tty, C.gray, '  by any cooperative proxy. Its CUSTOM providers, however, meter fully:'));
+    console.log(color(tty, C.gray, '  Antigravity’s built-in agent runs on Google’s servers, so no proxy sits in front'));
+    console.log(color(tty, C.gray, '  of it. Its usage is read from the logs it keeps on this machine instead:'));
+    console.log(color(tty, C.green, '       segreant import antigravity'));
+    console.log(color(tty, C.gray, '  Custom providers can also go through the proxy, live:'));
     console.log('');
     console.log(`  1) ${color(tty, C.bold, 'Choose the upstream')} the proxy forwards to. For the Gemini free tier:`);
     console.log(color(tty, C.green, '       segreant connect antigravity --write'));
@@ -359,6 +363,18 @@ function connectGenericApi(cfg, flags, tty) {
     console.log(color(tty, C.gray, '  The header wins if you send both. Either way it is your declaration, recorded'));
     console.log(color(tty, C.gray, '  as such — Segreant does not verify that the label is true.'));
     console.log('');
+    // The recipe covered the client side only; a user pointing scripts at another
+    // OpenAI-compatible provider had to find the other half in the docs.
+    console.log(color(tty, C.gray, `  Segreant forwards these requests to ${cfg.upstreams.openai}. For another`));
+    console.log(color(tty, C.gray, '  OpenAI-compatible provider (OpenRouter, Azure, a local server), set'));
+    console.log(color(tty, C.gray, '  "upstreams": { "openai": "<base URL>" } in config.json; docs/INTEGRATIONS.md has examples.'));
+    // The proxy appends the client's path to the upstream base, so a version
+    // segment in both places doubles it (/v1/v1/chat/completions) and 404s.
+    console.log(color(tty, C.gray, '  If that base URL already ends in its version (an Ollama base ending in /v1),'));
+    console.log(color(tty, C.gray, `  point the client at http://localhost:${port} without /v1. A remote upstream also`));
+    console.log(color(tty, C.gray, '  other than the official OpenAI and Anthropic APIs needs one egress rule; a refused'));
+    console.log(color(tty, C.gray, '  request prints the exact command.'));
+    console.log('');
     console.log(color(tty, C.gray, '  Run it, then check:'));
     console.log(color(tty, C.green, '    segreant sources'));
     console.log(color(tty, C.gray, '    segreant project --coverage   # what the spend is attributed to, and how'));
@@ -369,6 +385,31 @@ function connectGenericApi(cfg, flags, tty) {
  * No tool (or --list) shows the menu; opencode writes/prints its provider block;
  * `api` prints the generic env + header recipe (with an optional custom source name).
  */
+/**
+ * What forwarding to an upstream needs. Four cases: the official provider APIs
+ * are built in; plain HTTP on this machine is always allowed; any other HTTPS
+ * address needs the one rule printed; plain HTTP elsewhere cannot be allowed at
+ * all. The last case used to be told it was the official API (independent
+ * review, 2026-10-18).
+ */
+export function upstreamForwarding(url) {
+    if (isBuiltInProviderUpstream(url))
+        return { ok: true, text: 'Requests to the official provider API go out with no extra step.' };
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return { ok: false, text: `${url} is not a valid address.` };
+    }
+    if (target.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(target.hostname)) {
+        return { ok: true, text: 'A model on this machine is reached directly; no rule is needed.' };
+    }
+    const allow = providerRuleCommand(url);
+    return allow
+        ? { ok: false, text: `${url} is not a built-in provider API. Allow Segreant to forward there with:\n      ${allow}` }
+        : { ok: false, text: `${url} cannot be allowed as it is: Segreant forwards only to HTTPS, or to plain HTTP on this machine (localhost, 127.0.0.1). Use the gateway's https:// address.` };
+}
 export function cmdConnect(flags) {
     const tty = process.stdout.isTTY ?? false;
     const cfg = loadConfig();
@@ -387,7 +428,7 @@ export function cmdConnect(flags) {
         console.log(color(tty, C.gray, '          segreant connect opencode --write  apply it for you (backs up first)'));
         console.log('');
         console.log(color(tty, C.gray, '  No base URL to wire? Meter subscription tools natively — no routing, no key:'));
-        console.log(color(tty, C.green, '          segreant import claude-code | opencode | codex | all   ') + color(tty, C.gray, '(--watch = live)'));
+        console.log(color(tty, C.green, '          segreant import claude-code | opencode | codex | antigravity | all   ') + color(tty, C.gray, '(--watch = live)'));
         console.log('');
         return;
     }

package/dist/cli/egressCmd.js

@@ -32,11 +32,12 @@ function ruleFromFlags(flags) {
 function printUsage(tty) {
     console.log('');
     console.log(color(tty, C.bold, '  Segreant egress — process-scoped high-assurance transport'));
-    console.log(color(tty, C.gray, '  Default is local_locked: literal loopback only. No remote probe is made by this command.'));
+    console.log(color(tty, C.gray, "  Built in, in every mode: loopback, Segreant's public price list, and your requests to the"));
+    console.log(color(tty, C.gray, '  official OpenAI and Anthropic APIs. Anything else needs a rule. No remote probe is made here.'));
     console.log('');
     console.log(color(tty, C.gray, '  segreant egress status'));
-    console.log(color(tty, C.gray, '  segreant egress plan --mode controlled_cloud --id openai-main --purpose provider_inference --data-class provider_request --method POST --origin https://api.openai.com --path-prefix /v1/'));
-    console.log(color(tty, C.gray, '  segreant egress apply --apply --mode controlled_cloud --id openai-main --purpose provider_inference --data-class provider_request --method POST --origin https://api.openai.com --path-prefix /v1/'));
+    console.log(color(tty, C.gray, '  segreant egress plan --mode controlled_cloud --id openrouter --purpose provider_inference --data-class provider_request --method POST --origin https://openrouter.ai --path-prefix /api/'));
+    console.log(color(tty, C.gray, '  segreant egress apply --apply --mode controlled_cloud --id openrouter --purpose provider_inference --data-class provider_request --method POST --origin https://openrouter.ai --path-prefix /api/'));
     console.log(color(tty, C.gray, '  segreant egress apply --apply --mode local_locked'));
     console.log(color(tty, C.gray, '  segreant egress receipts | segreant egress verify'));
     console.log('');
@@ -109,6 +110,10 @@ export function cmdEgress(flags) {
             console.log('');
             console.log(color(tty, C.bold, '  Segreant egress status'));
             console.log('  Mode: ' + payload.mode);
+            if (payload.mode === 'invalid') {
+                console.log('  The egress section of config.json is malformed, so every cloud request is refused,');
+                console.log('  your provider included. Repair: segreant egress apply --apply --mode local_locked');
+            }
             const rules = payload.rules;
             console.log('  Rules: ' + (rules.length ? rules.map((rule) => rule.id + ' (' + (rule.enabled ? 'enabled' : 'disabled') + ')').join(', ') : 'none'));
             const receipts = payload.receipts;
@@ -171,6 +176,13 @@ export function cmdEgress(flags) {
         const failures = validateEgressRule(candidate);
         if (failures.length) {
             console.error('  Rule refused: ' + failures.join('; '));
+            // Git Bash (MSYS) rewrites an argument that starts with "/" into a Windows
+            // path before Segreant sees it, so "/v1/" arrives as "C:/Program Files/Git/v1/".
+            const prefix = flags['path-prefix'];
+            if (typeof prefix === 'string' && /^[A-Za-z]:[\\/]/.test(prefix)) {
+                console.error('  --path-prefix arrived as "' + prefix + '". Git Bash turns arguments that start with / into Windows paths.');
+                console.error('  Put MSYS_NO_PATHCONV=1 in front of the command, or run it from PowerShell or cmd.');
+            }
             process.exitCode = 1;
             return;
         }

package/dist/cli/evidenceCmd.js

@@ -4,6 +4,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { dbPath } from '../config.js';
 import { Store } from '../store/db.js';
+import { printJson } from './ui.js';
 import { buildGithubActionsOutcome, importGithubActionsOutcome, signGithubActionsOutcome, } from '../githubActionsEvidence.js';
 import { readBoundedUtf8File, RESOURCE_LIMITS } from '../util/resource-limits.js';
 import { buildEpistemicUxBundle } from '../epistemic/ux.js';
@@ -35,11 +36,13 @@ function cmdUx(flags) {
         throw new Error('epistemic UX options must be a JSON object');
     }
     const bundle = buildEpistemicUxBundle(supplied);
-    process.stdout.write(JSON.stringify({
+    // Always JSON; reading --json marks it as used so the dispatcher does not report it.
+    void flags.json;
+    printJson({
         operation: 'epistemic_ux_bundle',
         bundle,
         boundary: 'Review-only epistemic UX bundle; no claim issuance, strengthening, authorization, routing, or external truth inference.',
-    }, null, 2) + '\n');
+    });
 }
 function readJsonArtifact(path) {
     try {
@@ -124,7 +127,7 @@ async function cmdGithubImport(flags) {
         if (!result.ok)
             throw new Error(`evidence rejected: ${result.reason}`);
         if (flags.json) {
-            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            printJson(result);
         }
         else {
             console.log(`  Imported verified signed-CI tested=${artifact.body.verdict} evidence for ${result.commit.slice(0, 12)}.`);