segreant 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,116 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             GamingDragonwastaken (https://github.com/GamingDragonwastaken)
+
+Licensed Work:        Segreant
+                      The Licensed Work is (c) 2026 GamingDragonwastaken.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      including inside a company, for paid work, and as part
+                      of another product or service that you build and sell,
+                      provided that you do not:
+
+                      (a) offer the Licensed Work, or a modified version of
+                          it, to third parties as a hosted, managed or
+                          software-as-a-service offering; or
+
+                      (b) sell, rent, sublicense or otherwise charge a fee for
+                          the Licensed Work itself or a modified version of
+                          it, including a product that is substantially the
+                          Licensed Work offered under another name.
+
+                      Charging for your own product or service that uses or
+                      includes the Licensed Work is permitted when that
+                      product or service is not substantially the Licensed
+                      Work. Running the Licensed Work for your own
+                      organization, its employees and its contractors is not
+                      an offering to third parties.
+
+Change Date:          For each version of the Licensed Work, two years after
+                      the date that version is first publicly distributed.
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor through
+https://github.com/GamingDragonwastaken/Segreant/discussions.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+-----------------------------------------------------------------------------
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/LICENSING.md

@@ -0,0 +1,62 @@
+# Licensing, in plain words
+
+Segreant is published under the [Business Source License 1.1](LICENSE) with an
+Additional Use Grant. The LICENSE file is the binding text; this page explains
+what it means.
+
+## What you can do, free
+
+- **Use it for anything**, as a person or as a company: on your own projects,
+  at work, on paid client work, across your whole organization, with a team
+  server for your own staff.
+- **Change it, share it and contribute** to it.
+- **Build your own product on it and sell that product**, as long as your
+  product is more than Segreant under another name.
+
+No account, key, payment or permission is needed for any of that.
+
+## The two things you may not do
+
+1. **Offer Segreant as a service.** You may not run it, or a modified version
+   of it, as a hosted or managed service for other people or other companies.
+   Running it for your own organization is fine.
+2. **Sell Segreant itself.** You may not sell, rent, sublicense or otherwise
+   charge a fee for Segreant or a modified version of it, including a copy
+   relabelled under another name.
+
+## Every version becomes fully open source
+
+Two years after a version of Segreant is first published, that version
+switches to the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0),
+an Open Source license, and both limits above end for it. Each later version
+follows on its own two-year clock.
+
+Until then, Segreant is *source-available*, not *open source* in the strict
+(OSI) sense. We say so plainly rather than borrow a label it has not earned yet.
+
+## Why these terms
+
+The goal of Segreant is to move AI from paying for tokens to paying for value,
+and that needs as many people and organizations as possible measuring their own
+AI work, building on the measurement and improving it. The only thing these
+terms hold back is someone else turning this project into a paid service or a
+resold copy before it is fully open.
+
+## Something else in mind
+
+If you want to do something the two limits forbid, or you need different
+terms, open a
+[discussion](https://github.com/GamingDragonwastaken/Segreant/discussions).
+
+## Earlier versions
+
+- Commits up to `28dc6dd` on `main` were published under the MIT license and
+  remain available under it.
+- Commits after that and before the change to this license were published
+  under the PolyForm Noncommercial License 1.0.0 (from 2026-10-08 with an
+  individual use permission). Those copies keep the terms they were published
+  with; every later version is under the terms above.
+- The npm package `segreant` 0.1.0 (2026-10-08) is under this license
+  (`BUSL-1.1` in its package metadata and LICENSE file).
+
+*This page explains the license; it is not legal advice.*

package/README.md

@@ -1,3 +1,316 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="web/assets/brand/mark-256.png" alt="The Segreant mark: a gold griffin rearing, on black" width="112" />
+
+# Segreant
+
+**Govern the spend. Not the developer.**
+
+The financial control layer for AI coding agents, running on your own machine.
+Your agents' spend is metered, capped before a loop runs away with it, checked
+against the provider's bill, assigned to the budget it belongs to, and traced to
+the work it produced. And every number tells you exactly how much it can be trusted.
+
+`local-first` · `zero runtime dependencies` · `3,000+ tests` · `Node 24+` · `free to use, including at work (BUSL-1.1)`
+
+[![CI](https://github.com/GamingDragonwastaken/Segreant/actions/workflows/ci.yml/badge.svg)](https://github.com/GamingDragonwastaken/Segreant/actions/workflows/ci.yml)
+
+</div>
+
+---
+
+## The problem
+
+Coding agents bill by the token, and they fail expensively. An agent stuck in a
+loop overnight doesn't raise an error; it sends an invoice. Your monitoring
+can't see it, because a `$0.002` request and a `$0.40` retry loop look
+identical when all you measure is latency and errors.
+
+Then finance asks a simple question, *"what is AI costing us, and is it worth
+it?"*, and every tool answers with one confident number. That number is
+usually an estimate dressed as a bill, or a bill with no owner, or a value
+figure nobody can defend.
+
+## Four numbers, never one
+
+Segreant is built on a single refusal: **it will not collapse four different
+questions into one number.**
+
+| | The question | Where the answer comes from |
+|---|---|---|
+| **Metered usage** | What did the traffic use, at list price? | Segreant's proxy or your tools' own logs, priced from a versioned local rate card |
+| **Provider-billed cost** | What did the provider actually charge? | The provider's cost export or Costs API (OpenAI today), imported and kept separate |
+| **Allocated cost** | Whose budget does it belong to? | Allocation rules you write, reported together with what they left unallocated |
+| **Value** | Did the spend become shipped, kept work? | Outcome evidence from git, tests and your reports |
+
+Every figure on every screen says which of the four it is. When the evidence
+for a number is missing, Segreant shows **unknown**. It never fills in a guess.
+
+## What makes it different
+
+Most cost tools are dashboards. Segreant is an accounting system with an
+evidence model underneath, and it behaves like one.
+
+- **Every row carries its provenance.** Each priced request records the exact
+  rate-card SHA-256 and whether the price was an exact, family or fallback
+  match. Repricing appends a before/after event; nothing is silently
+  overwritten.
+- **Budgets fail closed.** If the budget config is malformed or the ledger
+  can't be read, Segreant stops forwarding. A broken meter never becomes an
+  unlimited one.
+- **Reconciliation shows its residual.** When metered spend and the
+  provider's bill disagree, the gap is reported with the conditions that
+  explain it and what it can and cannot bound. It is never forced to zero.
+- **Allocation conserves money.** Allocated plus unallocated equals the ledger
+  total to the microdollar, checked on every run. A run that doesn't balance
+  is refused.
+- **Model comparisons know when they're confounded.** Cheaper-model trials use
+  anytime-valid intervals, correct for multiple comparisons, and flag
+  themselves when the work sizes differ, the sample spans a price change, or
+  the commits came from too few sessions.
+- **Evidence you can hand to someone else.** Realized work produces
+  ed25519-signed value receipts. The whole evidence ledger exports as a
+  `.segreantpack` that a standalone verifier checks offline, without trusting
+  Segreant.
+- **A kernel that can't be talked into certainty.** Claims live in a small
+  trusted core that tracks four evidence states: unknown, supported, refuted
+  and conflicted. It refuses derivations that would strengthen a claim beyond
+  its evidence, and revoking a source revokes everything built on it.
+- **Zero runtime dependencies.** Node's built-in SQLite and nothing else. CI
+  proves it with a CycloneDX SBOM on every build.
+
+## See it in 30 seconds
+
+No API key, no account, no setup. With Node 24 or newer:
+
+```bash
+npx segreant demo --serve   # labelled synthetic data; opens the dashboard
+```
+
+Open **http://localhost:8091**. You'll see a month's statement with all four
+figures, spend by project and model with each session and what its commits
+came to, caps and alerts, a comparison with a generated provider bill,
+cost-centre splits, and what the spend produced, with a review-only
+cheaper-model comparison. It all runs on an isolated `demo.db` and is
+labelled as synthetic. Clear it with `segreant demo --clear`.
+
+## Use it on your real work
+
+Install the `segreant` command (it has no runtime dependencies):
+
+```bash
+npm install -g segreant
+```
+
+On Windows, a project-local install (`npm install segreant`) inside a folder
+whose path contains `&` cannot start through `npx` or `node_modules\.bin`:
+npm's generated `.cmd` shim does not quote that path. The global install above
+and `npx segreant` from any folder are not affected. For a local install there,
+run `node node_modules/segreant/bin/segreant.mjs` instead.
+
+**Option A: no wiring at all.** If you use Claude Code, Codex or opencode,
+Segreant reads the usage those tools already log on your machine, including
+subscription usage a proxy never sees. Antigravity is read from 0.2.0, which is
+unreleased and not yet on npm:
+
+```bash
+segreant scan            # finds your AI tools and git repos; changes nothing
+segreant scan --setup    # imports that usage and groups it by project
+segreant today           # what today cost, by model, project and tool
+```
+
+**Option B: route traffic through Segreant** to meter it live and enforce budgets:
+
+```bash
+segreant start         # proxy on :8090, dashboard on :8091
+```
+
+```bash
+segreant launch -- claude     # or codex, opencode, aider, ...
+```
+
+`launch` points only that one tool at the proxy, and only while the proxy is
+running. If the proxy is stopped, the tool starts unmetered with a warning, or
+not at all when a budget cap is set. To point a shell at it yourself instead:
+
+```bash
+export ANTHROPIC_BASE_URL="http://localhost:8090"
+export OPENAI_BASE_URL="http://localhost:8090/v1"
+```
+
+A tool pointed at the proxy this way cannot connect while Segreant is stopped.
+
+Requests to OpenAI's and Anthropic's official APIs go through as soon as Segreant
+starts: that traffic was already going to your provider, and Segreant meters it
+on the way. Everything Segreant would send on its own (webhooks, team rollups,
+hosted judging) stays off until you allow it, and another provider or gateway
+needs one rule, which a refused request prints
+([GETTING-STARTED.md](docs/GETTING-STARTED.md)). Then set a cap:
+
+```bash
+segreant budget --daily 25 --soft 18 --runaway 2   # hard cap, warning, loop guard
+```
+
+Caps are opt-in. A fresh install meters but never blocks. Unset the two
+variables and Segreant is out of the path.
+
+Per-tool recipes (Cursor, aider, opencode, Antigravity, your own SDK scripts):
+[docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).
+
+## What you can do with it
+
+- **See the spend.** By day, project, model, tool and developer, in the
+  terminal (`segreant today`, `week`, `month`) or the dashboard. Export CSV for
+  your own BI.
+- **Stop runaway agents.** Daily, per-session and velocity caps on proxied
+  traffic.
+- **Check against the real bill.** Import an OpenAI cost export, or pull
+  OpenAI's Costs API read-only, and reconcile it against what Segreant metered
+  at project-day level. See [PROVIDER-RECONCILIATION.md](docs/PROVIDER-RECONCILIATION.md).
+- **Allocate to cost centres.** Versioned, effective-dated rules, reported as
+  showback. See [ALLOCATION.md](docs/ALLOCATION.md).
+- **Measure what the spend produced.** Return on Intelligence follows each
+  commit through tested, merged, shipped and survived. See
+  [RETURN-ON-INTELLIGENCE.md](docs/RETURN-ON-INTELLIGENCE.md).
+- **Try a cheaper model, carefully.** `segreant frontier` compares models on the
+  same kind of task. It never changes your routing for you.
+- **Keep your data yours.** SQLite on your disk, verified backup and restore,
+  and evidence packs you can sign and verify.
+
+### In the dashboard, without the terminal
+
+`segreant start` serves a local dashboard organised by job:
+
+- **Statement**: one calendar month, side by side. What was measured, what the
+  provider billed, how it was split, and what it produced. The four are never
+  added together, and the month downloads as a CSV.
+- **Spend**: where the measured spend went, by project, model and source.
+- **Protect**: caps and alerts that stop spend before it happens.
+- **Close**: declare the OpenAI project, bring in the cost export, and record
+  the comparison with what Segreant measured.
+- **Allocate**: cost centres, the rules that assign spend to them, and the
+  monthly split, previewed before it is recorded.
+- **Value**: what the spend produced, with the limits stated.
+
+- **Settings**: choose what you see, from density to which jobs sit in the top
+  bar, and a map of everything Segreant can do. Each capability the dashboard
+  runs opens from that map in one click.
+
+Splits, bill comparisons, imports, adoptions and budget changes show a preview
+before anything is saved. The dashboard follows your system's light or dark
+setting, works at phone width, and loads nothing from the internet.
+
+Every command, flag and design detail is in the **[Segreant guide](docs/GUIDE.md)**.
+
+## For teams and enterprises
+
+The same local tool scales up without sending prompts or code to any Segreant-run service:
+
+- **Team rollups.** Each machine signs and pushes per-project value and spend
+  summaries to a team server *you* run. Per-developer views are opt-in,
+  distribution-only and k-anonymous.
+- **Finance-ready output.** Cost-centre allocation with conservation checks,
+  provider-billed evidence with digests and coverage declarations, and a
+  [FOCUS](docs/FOCUS-COMPATIBILITY.md)-compatible billing export.
+- **Identity and storage.** The team server supports OIDC sign-in and
+  PostgreSQL.
+
+The team server is implemented and tested, but it has not yet been validated in
+a production deployment; see [team-server/README.md](team-server/README.md)
+before exposing it to a network.
+
+## What Segreant will not claim
+
+Built to be believed, so it is strict about what it says.
+
+- **A local estimate is not a bill.** Metered amounts are list-price estimates.
+  Provider figures are imported separately, and reconciled cost never feeds
+  budgets or recommendations.
+- **Value is not causation.** The dollar figure in the value view is an
+  **Observed value scenario**: manual-equivalent value under assumptions you
+  set. It is not a causal return. A causal net benefit result is separate and
+  requires a registered randomized study (see
+  [CAUSAL-EVIDENCE-PROTOCOL.md](docs/CAUSAL-EVIDENCE-PROTOCOL.md)).
+- **Attribution labels are declarations, not verified identity.** Each label
+  records how it was obtained, and a missing one stays missing.
+- **Not surveillance.** Personal views are for self-improvement. Team views
+  are opt-in and aggregate-only.
+
+The complete, test-enforced list of what is supported, intended and not
+offered is [CAPABILITY-EVIDENCE-CONTRACT.md](docs/CAPABILITY-EVIDENCE-CONTRACT.md).
+
+## Privacy
+
+Segreant has no hosted service and sends no telemetry by default. The ledger
+lives under `~/.segreant`, and the dashboard loads nothing from third parties:
+no CDNs, fonts or analytics. Requests you route through the proxy still go to
+the AI provider you configured, and your API keys pass through without being
+stored. Segreant also downloads the public price list when it meets a model
+its rate card does not know; that download sends nothing about you, and
+`segreant pricing --auto off` stops it. Every other outbound path (alert
+webhooks, team rollups) is opt-in. The privacy statement is [PRIVACY.md](docs/PRIVACY.md), also
+one click from every dashboard page; every path in detail is in
+[DATA-BOUNDARIES.md](docs/DATA-BOUNDARIES.md).
+
+## Status
+
+Segreant is **pre-release (0.1.0)**, published on npm as `segreant`. CI covers Linux, macOS and Windows, including a packaged-install
+smoke test, real-browser tests and supply-chain checks.
+Reconciliation and outcome measurement are implemented and tested but have not
+yet been validated against real provider accounts or with outside users. That
+is what the first users will prove.
+
+If you try it, what confused you or what broke is the most useful thing you
+can send: [open an issue](https://github.com/GamingDragonwastaken/Segreant/issues)
+or [start a discussion](https://github.com/GamingDragonwastaken/Segreant/discussions).
+
+## Documentation
+
+| Start here | Go deeper | Trust and boundaries |
+|---|---|---|
+| [Getting started](docs/GETTING-STARTED.md) | [Segreant guide](docs/GUIDE.md) | [Data boundaries](docs/DATA-BOUNDARIES.md) |
+| [Integrations](docs/INTEGRATIONS.md) | [Architecture](docs/ARCHITECTURE.md) | [Capability contract](docs/CAPABILITY-EVIDENCE-CONTRACT.md) |
+| [FAQ](docs/FAQ.md) | [Methodology (plain language)](docs/METHODOLOGY.md) | [Threat model](docs/THREAT-MODEL.md) |
+
+The full index is in [docs/README.md](docs/README.md).
+
+## By the numbers
+
+| | |
+|---|---|
+| Product code | ~105,000 lines of strict TypeScript |
+| Tests | ~81,000 lines, 3,000+ test cases across the CLI, dashboard, team server and a real browser |
+| Runtime dependencies | 0 |
+| CI | 14 checks on every pull request: three operating systems, install paths with spaces and `&`, the team server against real PostgreSQL, a packaged install, supply chain, real-browser tests, and exact-head verification |
+
+## Development
+
+```bash
+npm install          # dev-only: typescript + @types/node
+npm run build        # compile to dist/
+npm test             # the full suite
+npm run typecheck    # strict TypeScript
+npm run demo         # rebuilds, then the demo dashboard from this checkout
+npm run start        # rebuilds, then the proxy and dashboard from this checkout
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how changes are verified,
+[GOVERNANCE.md](GOVERNANCE.md) for who decides what, [SECURITY.md](SECURITY.md)
+for reporting a vulnerability, [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)
+for what stays stable, and [docs/RELEASE-PROCESS.md](docs/RELEASE-PROCESS.md)
+for how a release is gated.
+
+## Supporting Segreant
+
+Segreant is built independently and is free to use for everyone, people and
+organizations alike ([LICENSING.md](LICENSING.md)). Paying never unlocks features
+([docs/NEUTRALITY.md](docs/NEUTRALITY.md) makes that a checkable commitment).
+
+## License
+
+[Business Source License 1.1](LICENSE) with an Additional Use Grant: **anyone,
+person or company, may use, change and build on Segreant for free**, including
+selling their own products built on it. The two things not allowed are
+offering Segreant as a hosted service and selling Segreant itself. Two years
+after each version is published, it becomes Apache 2.0 open source. Plain
+words: [LICENSING.md](LICENSING.md).

package/baselines/lift-baselines.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": 1,
+  "curated": "2026-07-10",
+  "unit": "minutes",
+  "source": {
+    "title": "Task-Completion Time Horizons of Frontier AI Models (METR, Time Horizon 1.1)",
+    "url": "https://metr.org/time-horizons/",
+    "arxiv": "https://arxiv.org/abs/2503.14499",
+    "asOf": "2026-05-08",
+    "note": "METR times skilled professional software engineers (~5 years' experience) completing real software tasks, using the geometric mean of successful completion times, then reports the task LENGTH (in that human-timed unit) at which frontier models succeed 50%/80% of the time. As of Time Horizon 1.1 (page updated 2026-05-08, benchmark METR-Horizon-v1.1 released 2026-04-07), the highest 80%-reliability horizon among tested models is ~186 minutes (Claude Mythos Preview Early) — verified against METR's own published benchmark data, not estimated. METR does NOT publish a breakdown of their task suite by category matching this table's task-type taxonomy (feature/fix/refactor/...) — the per-task-type minutes below are this project's own calibration against that published human-timed scale, not a METR output. These values are unchanged from this project's earlier illustrative defaults; the METR anchor (feature=240min sits modestly above the current ~186min frontier-model horizon) is an order-of-magnitude sanity check on them, not a re-derivation from METR data. Treat this as a cited industry anchor, not a precise measurement. Refreshable via `segreant baseline --refresh --url <manifest>` (no default source — you must supply one you trust; see docs/RETURN-ON-INTELLIGENCE.md §7.1) and, per project, blended with your own git history when enough pre-tracking commits exist — see src/value/liftBaseline.ts."
+  },
+  "baselineMinutes": {
+    "feature": 240,
+    "fix": 90,
+    "refactor": 120,
+    "test": 60,
+    "docs": 45,
+    "perf": 120,
+    "chore": 30,
+    "other": 90
+  }
+}