@calliopelabs/cli 3.7.0 → 3.8.1

package/docs/chatgpt-plan.md

@@ -0,0 +1,109 @@
+# ChatGPT plan access
+
+Experimental in 3.8.0: opt-in access with fixture-based implementation tests.
+Live subscription prompt/tool qualification remains outstanding.
+
+Calliope AI CLI can explicitly select ChatGPT-plan inference instead of an OpenAI
+Platform API key. This uses the open-source Sign in with ChatGPT flow and the public
+Responses API. Availability and usage limits depend on the signed-in account.
+
+```sh
+calliope auth chatgpt login
+calliope auth chatgpt status
+calliope --provider openai
+```
+
+Login opens the system browser with a temporary IPv4 loopback listener. Complete
+consent in that browser. Calliope validates the signed identity before activating
+an account. The initial sign-in registers a client; credentials and a stable host
+ID are saved privately beside the CLI config, under `chatgpt-auth/`.
+
+`status` lists registrations without credentials. Use `login <client-id>` to
+reauthorize a saved registration, `use <client-id>` to select another signed-in
+account, and `logout` to revoke the active renewable session and clear local tokens.
+Logout retains the client/account mapping and host ID. Run `login` without an ID to
+register another account/workspace. Concurrent credential changes fail with a busy
+message; after a crash, remove `chatgpt-auth/lock` only when no Calliope process uses it.
+
+`calliope auth chatgpt api-key` explicitly restores normal OpenAI API-key access.
+An environment API key or configured proxy never overrides selected ChatGPT access.
+Logout and refresh failures never change billing methods automatically. Quota
+failures can use the explicitly configured paid fallback described below.
+
+Models come from the active account's live catalog. The adapter sends the complete
+history with `store: false`, streams through `response.completed`, and returns tool
+calls to Calliope's existing permission and execution loop. Private reasoning state
+is saved with conversation history and bound to the account and model. Outside
+the configured quota fallback, start a new session to change either or switch
+that history back to API-key access.
+
+Subscription requests cannot enforce `max_output_tokens` or API dollar budgets;
+Calliope rejects those requests before inference, including reviewed/bounded runs.
+Token usage is recorded, but USD totals exclude subscription consumption. This does
+not mean the subscription is free or unlimited. Plan limits remain with ChatGPT.
+Cancellation and ordinary Calliope tool permissions still apply.
+
+Implementation tests use synthetic OAuth/JWKS and streamed Responses fixtures.
+They do not prove account eligibility or real subscription inference. Release
+qualification requires a user-operated login, live model discovery and a minimal
+prompt/tool round trip on an eligible account; no credentials belong in captures.
+
+References (checked 2026-11-04):
+- https://developers.openai.com/siwc/token-sharing-open-source/sign-in
+- https://developers.openai.com/siwc/token-sharing-open-source/profiles-and-sessions
+- https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference
+- https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations
+
+## Quota circuit breaking and paid fallback
+
+Quota exhaustion opens an account-specific circuit for one hour; a rate limit
+pauses subscription requests for one minute. The private state survives process
+restarts. `status` shows the circuit and `reset` allows an explicit early probe.
+
+Fallback is disabled by default. After configuring your OpenAI API key, opt in
+with an exact model ID from that key's live model catalog and a shared project
+spending ceiling (USD):
+
+```sh
+calliope auth chatgpt fallback models
+calliope auth chatgpt fallback enable <api-model> <max-project-cost-usd> [max-output-tokens]
+calliope auth chatgpt fallback status
+calliope auth chatgpt fallback reset
+calliope auth chatgpt fallback disable
+```
+
+The `models` command lists the API key's live catalog and endpoint target digest
+without changing your selected billing method or sending inference. Use that
+digest when preparing a reviewed billing profile.
+
+The output cap defaults to 4096 tokens. Existing recorded project spending counts toward
+the ceiling; enabling fallback, starting a new process or resetting the quota
+circuit does not replenish money. A stricter existing project cap still applies.
+Each paid attempt reserves its maximum billable cost before dispatch using the
+native project ledger. Concurrent callers share the same allowance. Failed or
+cancelled requests retain their reservation; missing prices, capabilities or
+limits stop inference. If the provider's model catalog omits these fields,
+configure [reviewed billing metadata](reviewed-provider-metadata.md) for the
+API-key endpoint before using fallback. Paid usage totals use the conservative
+rates from the reservation; the provider's invoice remains authoritative.
+
+On a quota failure before output, the ordinary terminal/headless/ACP turn can
+continue through the API key. A visible warning identifies paid billing and its
+cap. Public conversation and completed tool results are preserved; encrypted
+subscription state is removed. The saved session stays on the paid model even
+when the quota cooldown expires. Start a new session to try the plan again.
+Changing the fallback model or account requires a new session. Disabling fallback
+stops an existing fallback session rather than silently changing its billing.
+
+There is no automatic replay after partial subscription output, cancellation,
+refusal or authentication failure. Paid fallback has no transport retries; an API quota or rate-limit failure stops
+the turn even if the client normally retries errors. It never switches back to an
+exhausted subscription. Native tool permissions remain
+in force. Reviewed task/ledger execution and reviewed Smart routing cannot change
+billing targets this way; approve an API-key run explicitly for those workloads.
+
+### Organization access denied
+
+If OpenAI shows `3p_delegated_access_policy_denied` with “Your organization hasn’t enabled access for this app,” cancel the waiting CLI login and ask the ChatGPT workspace administrator to enable app access. Preserve the request ID for private OpenAI support if the setting is unavailable. Retry only after the policy changes. This is an authorization failure, not a quota event; it does not activate automatic paid fallback. You can explicitly select API-key access separately.
+
+The 3.8.0 operator check reached the browser consent screen but was denied by this organization policy. Live subscription inference and tool execution remain unqualified.

package/docs/claude-plan.md

@@ -0,0 +1,58 @@
+# Local Claude plan delegation
+
+Experimental in 3.8.0: opt-in access with fixture-based implementation tests.
+Live subscription prompt/tool qualification remains outstanding.
+
+Use your existing local Claude agent from Calliope AI CLI:
+
+```sh
+claude auth login
+calliope claude status
+calliope claude -- Review this project
+calliope claude --print -- Summarize the README
+calliope claude --model <model-from-Claude> --permission-mode plan -- Plan the change
+```
+
+Install the official Claude Code CLI first. Authentication remains in that tool;
+Calliope does not extract its tokens, offer its own Claude login, or send those
+credentials to the Anthropic Messages API. Use a recent version supporting
+`auth status` and `--permission-prompts` (2.1.259 or later).
+
+This command delegates the whole agent session. Claude owns tools, permissions,
+conversation state and plan usage. Calliope's native sandbox, reviewed-run ledger,
+token/output bounds and dollar budgets do not apply. Native `--provider anthropic`
+continues to use its existing API-key adapter.
+
+Interactive delegation starts with default permissions unless `plan` is chosen.
+Print mode denies unanswered permission prompts. Only the documented wrapper
+options are accepted; use `--` before a prompt. No permission-bypass flag is added.
+Model names are forwarded explicitly or left to Claude's own selection.
+
+Calliope checks `claude auth status` for a saved `claude.ai` login before starting.
+It removes inherited Anthropic credentials/provider selectors and disables
+user/project settings sources for both the check and the delegated run. Managed
+Claude policy still applies and can prevent launch. These settings mean personal
+Claude configuration may differ from a normal direct launch. Claude's own plan and
+extra-usage settings determine consumption; this is not a promise of unlimited or
+zero-cost requests. Calliope does not silently switch to an API key.
+
+Cancellation is forwarded to the child process; a child that does not terminate
+receives SIGKILL after two seconds. The command returns Claude's exit status.
+
+## Support guidance discrepancy
+
+As checked on 2026-11-04, the support article says signed-in Agent SDK and `claude -p`
+usage continues to draw from subscription limits. The SDK overview separately says
+third-party products need prior approval to offer claude.ai login/rate limits.
+This implementation is an explicit launcher of the user's installed local CLI,
+not an embedded SDK provider or a new login offering. Broader embedded SDK
+subscription support remains subject to clarification of that published guidance.
+
+- https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
+- https://code.claude.com/docs/en/agent-sdk/overview
+- https://code.claude.com/docs/en/cli-reference
+- https://code.claude.com/docs/en/authentication
+
+Automated tests cover argument/environment isolation, auth preflight, cancellation,
+status-output limits and exit propagation. Subscription inference requires an
+eligible user's existing Claude login; tests do not consume a real plan.

package/docs/delegation-ledger.md

@@ -50,11 +50,23 @@ authority binding. Child credentials retain that binding. A sibling owner endpoi
 cannot accept the token, and reservations, settlements and revocations enforce the
 selected subtree. Each new request also checks the target account's native admission,
 stop/escalation state, explicit reviewed provider/model choices and the host's
-output cap. The provider/model check uses the current admitted graph and runs
+output cap. Smart agents also enforce their reviewed initial pool. Task-bound
+hosts derive escalation eligibility from that task's retained native failed-check
+evidence; account-only hosts cannot select an escalation pool. Explicit reviewed
+pins retain the same precedence as local Smart routing. The provider/model check
+uses the current admitted graph and runs
 again under the ledger writer lock before a new reservation commits. Existing requests can still settle
 after owner cancellation; grant revocation and token expiry retain their existing
 semantics.
 
+Reviewed host capabilities additionally advertise `endpointBinding: 1`. Hosting
+captures the owner's configured provider target hashes in the native budget approval
+and token audience. New reservations must match that target for their provider;
+changing an owner's endpoint fences existing hosts and changes newly issued tokens.
+Restarting with unchanged endpoint configuration preserves credentials and allowance.
+API key rotation does not change target identity. Child-side endpoint overrides cannot
+widen this authority. Target hashes contain no API keys or raw endpoint strings.
+
 The HTTP grant operation only returns credentials for an **exact, already admitted**
 native child grant. It cannot create a proposal, approve children, bypass native
 depth/count limits or promote an interrupted ledger grant into the execution graph.
@@ -69,10 +81,48 @@ that history requires verified restoration or an explicit owner-managed credenti
 rotation; opening it never silently treats missing revocations as an empty history.
 
 This is reviewed ledger hosting, not automatic Cykick/Astrolift enrollment. Remote
-workspace identity, dispatcher credential delivery, task-attempt ownership, transport
+workspace identity, dispatcher credential delivery, exclusive task ownership, transport
 reachability and any narrower Cykick file-mutation policy still need their native
 bindings. A loopback listener does not make a desktop reachable from a remote pod.
 
+## Serve one active native task attempt
+
+```sh
+calliope ledger serve-task --run RUN_ID --task TASK_ID --attempt 1 \
+  --max-output-tokens 1024 --project /path/to/project \
+  --token-file /private/task.token
+```
+
+`prepareReviewedTaskLedger(cwd, runId, taskId, attempt, maxOutputTokens, options)`
+derives the agent, session, immutable start-event ID/hash and native owner from
+the current attributed `task_started` journal event. Pending, legacy unattributed,
+stopped, completed and stale attempts cannot open this host. The private token's
+audience binds that task, owner and output cap as well as the reviewed run.
+Another task, changed owner, different cap or account-only host rejects the token.
+This endpoint advertises reviewed capability version 2 with `taskBinding: 1`.
+
+Its operations are only `hello`, `journal`, `task-execution`, `reserve` and `settle`.
+There is no legacy `execution` fallback or child-grant mutation. Current clients
+negotiate `task-execution`, validate its version 2 binding and automatically carry
+the exact attribution and output cap into the shared execution guard. Older clients
+refuse the missing legacy operation before inference. Each new reservation verifies
+the attribution, agent, output cap and still-active native owner/attempt, including
+under the ledger writer lock. Existing admissions may replay or settle after the
+attempt ends; the original token expiry and accounting still apply.
+
+Task-bound sessions retain version 2 restrictions with the start-event provenance.
+A different task/attempt or an account-only connection cannot resume them. Reopening
+the same active attempt preserves its token, allowance, history and deadline.
+This does not dispatch work, acquire an exclusive process lease, implement Astrolift enrollment. A trusted scheduler still
+owns those actions and the delivery of the private credential.
+
+Run `CALLIOPE_REVIEWED_HOST_TASKS=1 npm run test:reviewed-host` for the real-process
+task-host qualification. It checks two concurrent headless children, native ACP
+session binding, exact request attribution, host restart, completed-attempt refusal, an active sibling
+and run cancellation against a local deterministic provider with no paid requests.
+The current reverse exec tunnel retains its child-grant contract; this task-host
+mode is qualified through direct native HTTP transport.
+
 ## Run a delegated child
 
 A host (Cy, an Astrolift task) grants the child, writes its scoped token to a private file and
@@ -102,6 +152,7 @@ undelegated fallback.
 | `hello` | any | protocol and operations |
 | `journal` | any | the full hash-chained history (`manifest`, `events`) |
 | `execution` | account owner | verify `{agentId, project: {root, key}}` against the retained owner grant and return its native workspace binding |
+| `task-execution` | task owner, task endpoint only | verify the account/workspace and return the immutable native start provenance and output cap |
 | `reserve` | owner of `reservation.agentId` | charge before dispatch; same id replays the original admission |
 | `settle` | owner of the reserved request | record usage or an outcome; same settlement replays |
 | `grant` | parent, or a child for its own accounts | allocate child accounts; returns the child's scoped token |
@@ -169,10 +220,60 @@ Reservation errors optionally report `admission: refused` when the server has
 verified non-admission after the local operation ends, or `unknown` otherwise.
 Clients retain capacity when talking to older v1 servers that omit this evidence.
 
+## Portable project identity
+
+A manifest creator may add `project.portable = {version: 1, roots, origin}` to a
+version 1 manifest. `roots` are the sorted root commits of `HEAD`'s history (1 to
+16), and `origin` is a digest of the normalized `remote.origin.url` (`host/path`,
+without scheme, credentials, port or trailing `.git`; the raw URL is never stored).
+The field is optional and only the creator can set it: it is part of the manifest
+hash, and `ReservationLedger.create` still checks the creator's own mount exactly
+and rejects a declaration that mount does not derive. Library callers opt in with
+`portableProjectIdentity(dir)` from `src/execution/portable-identity.ts`; the CLI
+has no flag because it builds no execution manifests.
+
+**The portable identity identifies a repository and authenticates nothing.** Any
+checkout with the same root commits and origin matches, including a fresh clone at
+the creator's path, and anyone who can edit `.git/config` controls the origin it
+reports. Authority still comes from the ledger token and owner, never from this
+value. It is not a replacement for the owner-bound workspace grant, which stays
+exact and cannot carry `portable`.
+
+Where it applies:
+
+- Local ledger reads, reservations, settlements and `ExecutionGuard` accept a
+  matching checkout. Every path grant resolves against the realpath of the local
+  `cwd`, never the manifest's recorded root, so a `src/**` grant cannot reach the
+  creator's checkout or anything outside the local one.
+- While the portable identity is in use, writes under `.git` are denied, so an
+  agent cannot rewrite the origin it is matched on. The guard derives the identity
+  once, at construction.
+- A manifest without the field behaves exactly as before. Its hash is unchanged.
+
+The identity is unavailable, so the check fails closed with "Execution belongs to a
+different or replaced project.", when any of these hold: not a git project, `cwd`
+is not the repository top level, `.git` is a file (linked worktree or submodule),
+shallow clone, no commits, no `origin`, an `origin` that is a local path or
+`file://` URL, more than 16 root commits, a missing git binary or a git error.
+A project without git keeps the path-and-inode binding.
+
+Limits in this release:
+
+- Manifests with a `parent` and the remote ledger protocol still compare the exact
+  `{root, key}`; a remote parent refuses a second mount until the ledger checks
+  accept the portable identity.
+- The `goals/*`, `improvement/*` and `orchestration/*` call sites that read
+  `manifest.project.root` literally are not supported from a second mount.
+- Brain locators keyed to the creator's project key are denied on the second mount.
+- Approvals (`describeApproval`) keep their local path-and-inode binding.
+
 ## Owner-bound remote workspaces
 
-A copied checkout has a different path and filesystem identity. It cannot use a
-parent grant just because its files look the same. The ledger owner may issue a
+By default a copied checkout has a different path and filesystem identity, and
+it cannot use a parent grant just because its files look the same. A manifest
+whose creator opts in to a portable project identity (see the next section) also
+accepts another checkout of the same repository on the local ledger. Without that
+field, the exact path-and-inode check applies. The ledger owner may issue a
 version 2 child grant with `project: {root, key}`, captured using the CLI's
 `projectIdentity()` on the intended child host. The existing proposal hash,
 review revision and native run manifest references remain part of that immutable
@@ -323,9 +424,83 @@ The executable reports its tested artifact type and invariant results as JSON.
 This is a local HTTP host example, not a deployed Astrolift acceptance test.
 Use `delegation-ledger/v1`, reviewed host capability version 1 and the headless
 capability tuple above; a matching package version alone is insufficient.
-The current CLI entry point requests a 4096-token output limit, so the reviewed
+The account-only CLI entry point requests a 4096-token output limit, so the reviewed
 host and discovered model must both permit that bound. Lower output caps are
 available to library callers through `DelegatedExecutionOptions.maxOutputTokens`.
 The existing ledger, workspace and session suites cover nested grants, lost
 acknowledgments, rollback and approval/session replay; those are separate from
 this example's process-level assertions.
+
+### Native reviewed runs funded by a remote parent
+
+The source API also accepts `RunActionOptions.parentBudget` version 2 when first
+preparing a native run. This is distinct from attaching an ACP session: the child
+still executes its own reviewed plan through `executeReviewedRun`, including
+native task outcomes, questions, verification and supervision.
+
+The link contains `url`, an absolute private `tokenFile`, an absolute private
+`checkpointRoot`, `runId`, `budgetManifestHash`, `agentId`, `accountMap`, and the
+owner's `reviewedContext`. Obtain that context from `prepareReviewedLedger`; it
+binds the owner run manifest, approval revision, endpoint authority and bounded
+run ancestry. The token and checkpoint must remain outside the worker workspace.
+Never derive these fields from task text or model preferences.
+
+Before preparing the child, the parent must admit the external workspace and its
+accounts through native reviewed child admission. `accountMap` maps every child
+account to a distinct, already admitted parent account. Parent relationships,
+workspace, scopes, absolute deadlines and allowances must agree. A later child
+grant also needs matching parent admissions; an embedded host cannot create an
+independent root allowance by starting another coordinator. Reopening an existing
+child preserves its original parent link.
+
+`remoteParentBudgetCapabilities()` describes link version 2, execution manifest
+version 2, execution event version 13 and reservation event version 6. The parent
+must advertise `task-admit` and `task-release` alongside its reviewed ledger
+context. Task-bound worker endpoints do not advertise these operations. Older
+runtimes must reject unsupported records or capabilities instead of falling back
+to unlinked execution.
+
+Before a worker, controller or reviewer runs, the native child acquires a parent
+execution slot bound to its run, manifest, start event, session, task/attempt or
+review role/round. The parent's execution journal serializes these slots with
+local workers and supervision. Nested funding propagates the same work identity
+to every ancestor. Requests carry the admitted identity, while reservation and
+settlement still use the existing parent-first budget chain.
+
+Disconnection, a lost acknowledgement or elapsed time does not release a slot.
+Replay the identical admission to recover its outcome. Once work has stopped,
+release that exact admission; release is idempotent and propagates through the
+funding chain. A restarted owner retains active slots. An unresolved dead worker
+therefore needs authoritative reconciliation; starting another run or deleting a
+checkpoint is not recovery. Cancellation blocks new work while recorded usage
+can still settle. Expired or revoked credentials cannot be reused for recovery.
+
+The source regression examples are `tests/remote-parent-budget.test.ts`,
+`tests/remote-task-capacity.test.ts` and `tests/remote-parent-process.test.ts`.
+The process suite compiles the current source into an isolated package and runs
+separate native coordinators through real HTTP, including mixed local/remote
+funding, owner restart, cancellation, worker death and retained-charge exhaustion. They exercise actual native coordinators,
+HTTP ledgers and deterministic inference without paid provider requests. These
+source checks do not establish published-release compatibility or disposable
+Astrolift deployment acceptance.
+
+Run the remote-parent process qualification with:
+
+```sh
+npx vitest run tests/remote-parent-process.test.ts --maxWorkers=1
+```
+
+It uses the normal `run resume` command in separate Node CLI processes. To run
+those same scenarios against a standalone binary built from this source:
+
+```sh
+npm run build
+bun packaging/build-binary.mjs --native
+CALLIOPE_REMOTE_PARENT_BINARY="$PWD/packaging/dist/calliope-native" \
+  npx vitest run tests/remote-parent-process.test.ts --maxWorkers=1
+```
+
+Both modes use disposable configuration, real HTTP and deterministic local
+inference. The worker-death case leaves its parent slot and charge unresolved;
+the exhaustion case releases only the verified dead process's slot and proves
+that its unknown provider charge still prevents another inference request.

package/docs/improvement-cycles.md

@@ -50,6 +50,11 @@ external feedback or reinforcement-learning interface.
 
 ## Host review requests
 
+Explicit host contract version 2 additionally exposes the
+[reviewed task feedback](task-feedback.md) record/inspect/history API. Version 1
+discovery remains unchanged. Feedback receipts do not award rewards or enable
+cross-run learning.
+
 The separately negotiated `improvementReviewCapabilities()` API (version 1,
 `improvement.review-capabilities`) advertises `requestImprovementReview`,
 `inspectImprovementReviews` and `dismissImprovementReview`. It is request-only;

package/docs/releases/3.8.0.md

@@ -0,0 +1,65 @@
+# Calliope CLI 3.8.0
+
+This release adds explicit subscription access, native task-bound delegation and
+reviewed feedback. It also tightens reviewed inference authority and reads
+Mimwell portable knowledge graphs.
+
+## Experimental subscription access
+
+`calliope auth chatgpt login` selects ChatGPT-plan access for the OpenAI provider.
+Account selection, private credential storage, refresh/revocation and live model
+discovery are separate from API-key access. Streamed Responses and tool calls use
+Calliope's existing permission loop. Expired sessions stop; quota exhaustion can
+use an explicitly configured paid API-key fallback. Subscription requests refuse output-token
+and USD enforcement that the service cannot provide; USD totals exclude this
+consumption. See [ChatGPT plan access](../chatgpt-plan.md).
+
+Quota and rate-limit circuits persist across processes. Opt-in API-key fallback
+reserves every paid request against a shared project ceiling, preserves public
+conversation/tool context and strips encrypted subscription state. Paid sessions
+stay on their selected model; partial output, cancellation, logout and reviewed
+execution stop automatic transitions. A depleted API account stops without
+retrying or switching back. Missing live/reviewed billing bounds refuse payment.
+
+`calliope claude -- <prompt>` delegates a complete session to the installed,
+authenticated official Claude Code CLI. `calliope claude status` checks that local
+setup. Claude owns permissions, tools, sessions and plan usage; Calliope's native
+sandbox and budgets do not govern the delegated session. See
+[local Claude plan delegation](../claude-plan.md).
+
+These integrations ship as opt-in experimental features. Tests use synthetic
+authentication and response fixtures; live account eligibility and subscription
+prompt/tool round trips remain unqualified. Complete the user-operated checks in
+the linked guides before relying on either route for unattended work.
+
+## Reviewed task authority and feedback
+
+Delegated headless and ACP execution can bind to an exact native task attempt,
+including its owner, output cap and original accounting across host restarts.
+Completed or mismatched attempts refuse new inference. Reviewed Smart routing
+pools and provider endpoints now constrain new reservations; an endpoint change
+requires new review, while prior admissions retain replay and settlement.
+See [delegation ledger](../delegation-ledger.md).
+
+Version-2 improvement host discovery exposes reviewed task feedback. Receipts bind
+an assessment to the exact observed completed attempt and retain private journal
+evidence. They neither mark a task accepted nor activate a learned policy. See
+[task feedback](../task-feedback.md). External placement and disposable remote
+parent/child acceptance remain tracked in #415; cross-run learned strategy
+selection remains tracked in #413.
+
+## Compatibility and runtime
+
+- `brain import` accepts `mimwell-kg/v1` alongside existing graph formats; exports
+  continue using `calliope-kg/v1`.
+- OpenAI SDK 7 stream capture handling now recognizes delivered completion events.
+  Runtime SDKs, Conf, Ink and supporting dependencies are updated; container builds
+  include the metadata builder.
+- Node 24 or later is required. The stable ACP wire protocol remains version 1.
+- Mistral/Hugging Face SDK 7 live qualification follow-up remains in #457; xAI is
+  explicitly deferred by the existing publication gate.
+
+Performance budgets from #210 remain enforced for cold start, keystroke rendering
+and retained-session heap growth. See [performance measurements](../performance.md).
+
+Refs: #474, #467, #468, #415, #455, #463, #457.

package/docs/releases/3.8.1.md

@@ -0,0 +1,40 @@
+# Calliope CLI 3.8.1
+
+This patch makes generic headless reasoning effort explicit and distinguishes
+missing provider usage from reported zero in the execution journal.
+
+## Headless reasoning effort
+
+Use `--reasoning-effort medium` or `CALLIOPE_REASONING_EFFORT=medium` for headless
+execution. The flag overrides the environment default. Missing, invalid and
+duplicate flag values exit 2. The shared runtime retains the selected effort
+through model requests and tool continuations; existing live provider/model
+capability and protocol checks refuse unsupported effort rather than silently
+using a default. Calls without an effort keep their previous behavior.
+
+Node and native artifact smoke tests exercise the actual SDK request against a
+synthetic local Anthropic transport, including a real file-tool turn. They verify
+effort forwarding and refusal before model dispatch when metadata does not
+confirm support. This is packaging/transport qualification, not evidence of live
+account eligibility or a completed paid factory run.
+
+## Usage presence
+
+Assistant journal events now include optional `usageReported`. `false` means the
+provider omitted usage even if legacy numeric counters are zero; `true` preserves
+a genuinely reported zero. Consumers must retain unknown telemetry as unknown
+and keep subscription consumption separate from API estimates and actual charges.
+Older journals without the field remain readable.
+
+## Remote admission deadlines
+
+A remote task admission that expires in transport now returns the typed deadline
+refusal, matching a deadline reached before dispatch. Authorization and parent
+budget bounds still apply first; an expired request allocates no execution slot
+or budget charge. A deterministic HTTP regression covers this boundary.
+
+Node 24 or later remains required. Experimental subscription integrations retain
+their existing limitations; this patch does not qualify a remote subscription
+factory route or provision accounts, mailboxes, credentials or grants.
+
+Refs: #502, #503, #505, #507.

package/docs/reviewed-provider-metadata.md

@@ -0,0 +1,84 @@
+# Reviewed metadata for bounded provider calls
+
+Some providers discover model IDs without publishing capabilities, limits or
+prices through their models API. An operator can supply the missing evidence for
+bounded execution in a private billing file. This does not enable Smart routing,
+change a provider/model pin, or add models to discovery. The selected model and
+endpoint must still match recent live discovery.
+
+Use `~/.calliope-cli/billing.json` or `CALLIOPE_BILLING_FILE`, outside the worker
+project. Protect it with `chmod 600`. The existing reader rejects aliases,
+symlinks, hardlinks, group/world write access, files over 128 KiB and more than
+64 profiles. Profiles are operator authority; workers must never generate or
+install them from their outputs.
+
+```json
+{
+  "version": 2,
+  "profiles": [{
+    "version": 2,
+    "provider": "deepseek",
+    "model": "<exact live-discovered model ID>",
+    "target": "<configured providerTarget(provider).key digest>",
+    "checkedAt": 0,
+    "expiresAt": 0,
+    "sources": ["https://api-docs.deepseek.com/quick_start/pricing/"],
+    "prices": {"input": 0, "output": 0},
+    "capabilities": {"chat": true, "tools": true, "streaming": true},
+    "limits": {"contextLength": 0, "maxOutputTokens": 0},
+    "admission": "reviewed-full-context-v1"
+  }]
+}
+```
+
+The placeholders are intentionally invalid. Set positive token limits from
+current provider documentation and epoch-millisecond timestamps, with expiry at
+most seven days after review. Review the exact endpoint's billing terms: a
+gateway may charge differently from its upstream provider. Prices are USD per
+million tokens and must upper-bound applicable cache, reasoning and time/tier
+rates on the adapter path. URL presence alone does not verify metadata. Include
+no keys, private prompts or response content; source URLs must be HTTPS without
+credentials, queries or fragments. Every configured provider can use this schema;
+the CLI bundles no model or pricing catalogue.
+
+## Conservative admission
+
+Each request reserves the larger of reviewed and live input capacity, plus its
+requested maximum output. This is a full-capacity allowance, not a tokenizer
+estimate or consumed tokens. A tiny prompt to a large-context model may therefore
+need substantial token headroom before dispatch; do not reduce the reviewed
+capacity to make a budget fit. Successful usage reporting settles the reservation
+to reported usage at the reserved rates. Failures, cancellation and missing usage
+retain the reservation, and overruns stop subsequent requests.
+
+The output maximum is the smaller of the reviewed and live limits. Prices use
+the larger rate for each input/output direction. Reviewed capabilities fill only
+unknown live fields; a live rejection always vetoes the request. Unknown required
+capabilities in both sources fail closed. Live routing metadata remains unchanged,
+including unknown prices used by Smart ranking. This profile does not request
+Anthropic token counting, accept supplied input counts or admit multimodal input.
+
+The provider/model/endpoint binding, original run/agent/project budgets, policy,
+deadlines and cancellation checks still apply. The profile is re-read before
+reservation and before dispatch; deletion, edits or expiry revoke admission.
+Revocation after a durable reservation retains that reservation conservatively.
+No automatic paid probe or retry can replenish the original allowance.
+
+## Versioning and recovery
+
+Version-2 billing files can contain these profiles together with unchanged
+[legacy counted profiles](counted-admission.md). Version-1 files retain their
+original format and hashes; no file or historical journal is migrated.
+
+New quotes carry `quoteEvidence.version = 2`, including the reviewed profile and
+digest, quote time, live observations and required capabilities. Execution
+reservations carrying that proof use reservation event version 4, also supporting
+existing request attribution. Replay reconstructs the conservative bounds from
+the recorded proof and rejects inconsistent prices, limits or event versions.
+Historical replay checks validity at quote time, without fetching metadata or
+requiring a now-expired profile to be renewed.
+
+Ordinary project-capped turns include the same proof in their existing hash-linked
+policy audit event. Execution journals retain it with the reservation. Neither
+contains prompt bytes, tool arguments or credentials. The outer headless JSON
+envelope and existing ledger projections retain their versions.