@paxnax/berliner 0.7.0 → 0.9.0

package/README.md

@@ -21,7 +21,7 @@ With Bun, run `bunx --bun @paxnax/berliner@latest setup`. To install only the co
    npx @paxnax/berliner@latest setup
    ```
 
-   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner upgrade` to update the CLI, the skill and any Berliner hook an older setup installed to the latest release: it shows its plan and asks first, and a second question (or `--no-skill`) keeps your skill as it is.
+   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner upgrade` to update the CLI, the skill and any Berliner hook an older setup installed to the latest release: it shows its plan and asks first, and a second question (or `--no-skill`) keeps your skill as it is. Once a day, the first `berliner` command or agent session start checks for a newer release and says so.
 
 3. From then on, the hooks report each session's cost, model, repository, commits and start and end times after every reply. They also fill in a ticket from a Linear or Jira URL in your prompts while the session has none, and refresh up to 5 open pull requests the Berliner GitHub App doesn't track with your `gh` (skipped when `gh` is missing or signed out). When a session starts, the hook reminds your agent to name the session and report its ticket. Your agent adds the title, ticket, pull requests, coverage and evidence with `berliner report` and `berliner update`, as the skill tells it to. Codex runs a new hook only once you trust it: open `codex` once in a terminal and trust the Berliner hook.
 4. On **Settings**, list the subscriptions you pay for. Overview then compares each one with the sessions that ran on it.
@@ -36,26 +36,26 @@ Setup saves the token and, when it isn't the default, the server address in `${X
 |---|---|---|
 | `BERLINER_TOKEN` | only without setup | An API token, created on the Settings page at https://berliner.app. Without it, the CLI uses the token in the config file. |
 | `BERLINER_URL` | no | The server to report to. Without it, the CLI uses the config file's `url`, then `https://berliner.app`; set it for a local or self-hosted server. |
-| `BERLINER_PLAN` | no | The plan the sessions from this shell run on. It replaces whatever `--plan` the agent passes, and the hooks use it too, so set it when one machine runs several accounts. Empty means unset. See [Several subscriptions](#several-subscriptions). |
+| `BERLINER_VENDOR_SUBSCRIPTION_SLUG` | no | The slug of the subscription the sessions from this shell run on, from Settings → "Third-party vendor subscriptions". A session is put on it when it is created, by `berliner report`, `berliner update` or the hooks, and its plan replaces whatever `--plan` the agent passes, so set it when one machine runs several accounts. A session that already exists never moves to it. Empty means unset. See [Several subscriptions](#several-subscriptions). |
 
 ## Several subscriptions
 
-Berliner compares each subscription only with the sessions that ran on it. A session belongs to a subscription when both match:
+Berliner compares each subscription only with the sessions that ran on it. Each subscription in Settings → "Third-party vendor subscriptions" has a slug, a short name of your choosing such as `work`. Leave it blank and it is `<vendor>-<plan>`, like `anthropic-max_x20` or `openai-pro`. A session belongs to a subscription:
 
-- **The vendor**, which comes from the model: `claude-…` is Claude, and `gpt-…`, `codex-…` or `o3`-style names are OpenAI.
-- **The plan**: your `BERLINER_PLAN` when it is set, otherwise the agent's `--plan`. When there is neither (the hooks never pass `--plan`, and reports inside Claude Code, Codex or OpenCode can leave it out), Berliner gives a new session the plan of your one subscription for its vendor. It is `api` when you list no subscription for that vendor, more than one, or the model is from neither vendor.
+- **When the shell names it** with `BERLINER_VENDOR_SUBSCRIPTION_SLUG` as the session is created, or a report or update passes `--subscription <slug>`, which wins over the variable. The session takes that subscription's plan, whatever `--plan` the agent passed. A session that already exists stays on its subscription unless `--subscription` moves it. The subscription must be for the model's vendor: `claude-…` is Claude, and `gpt-…`, `codex-…` or `o3`-style names are OpenAI.
+- **Otherwise by its plan**: the agent's `--plan`, or, when there is none (the hooks never pass `--plan`, and reports inside Claude Code, Codex or OpenCode can leave it out), the plan of your one subscription for the model's vendor. The session belongs to your one subscription for that vendor and plan, if there is exactly one. The plan is `api` when you list no subscription for that vendor, more than one, or the model is from neither vendor.
 
-An agent usually can't tell which account it's signed in to, so its `--plan` is a guess. If you run a work and a personal profile on one machine, give each one its plan with `BERLINER_PLAN`, one alias per profile. The hooks run inside the tool, so they see it too:
+An agent usually can't tell which account it's signed in to, so its `--plan` is a guess. If you run a work and a personal profile on one machine, name each one's subscription with `BERLINER_VENDOR_SUBSCRIPTION_SLUG`, one alias per profile. The hooks run inside the tool, so they see it too:
 
 ```sh
-alias claude='BERLINER_PLAN=enterprise command claude'
-alias pclaude='CLAUDE_CONFIG_DIR=$HOME/.claude-personal BERLINER_PLAN=max_x20 command claude'
-alias codex='BERLINER_PLAN=pro command codex'
+alias claude='BERLINER_VENDOR_SUBSCRIPTION_SLUG=work command claude'
+alias pclaude='CLAUDE_CONFIG_DIR=$HOME/.claude-personal BERLINER_VENDOR_SUBSCRIPTION_SLUG=personal command claude'
+alias codex='BERLINER_VENDOR_SUBSCRIPTION_SLUG=openai-pro command codex'
 ```
 
-Write `command claude`, not `claude`, inside each alias. Without `command`, `pclaude` expands the `claude` alias too, and its `BERLINER_PLAN=enterprise` wins.
+Write `command claude`, not `claude`, inside each alias. Without `command`, `pclaude` expands the `claude` alias too, and its `BERLINER_VENDOR_SUBSCRIPTION_SLUG=work` wins. Two subscriptions on the same plan work too, as long as their slugs differ. If you rename a slug in Settings, update the aliases that use it.
 
-When `BERLINER_PLAN` is set and the agent passes a different `--plan`, Berliner uses yours and prints a warning. If `BERLINER_PLAN` isn't a valid plan, the session is saved with the agent's `--plan` instead, with a warning. With no `--plan`, as in the hooks, the report is sent without a plan instead, so a new session gets the server's pick and an existing one keeps its plan: `berliner report` prints a warning, and the hook writes one line to `${XDG_STATE_HOME:-~/.local/state}/berliner/hook.log`. Either way a typo never loses a session.
+When the variable is set and the agent passes a different `--plan`, Berliner uses the subscription's plan and prints a warning. If the variable's slug isn't one of your subscriptions, or is for the other vendor, the session is saved with the agent's `--plan` instead, with a warning. With no `--plan`, as in the hooks, the report is sent without a plan instead, so a new session gets the server's pick and an existing one keeps its plan: `berliner report` prints a warning, and the hook writes one line to `${XDG_STATE_HOME:-~/.local/state}/berliner/hook.log`. Either way a typo never loses a session. A bad `--subscription` is different: you typed it, so the report fails with the server's message and nothing is saved.
 
 The plan values:
 
@@ -77,10 +77,16 @@ The plan values:
 | OpenAI | Business (premium seat) | `business_premium` |
 | either | Billed per token | `api` |
 
-Sessions reported before you set `BERLINER_PLAN` keep the plan the agent guessed. To fix one by hand from a shell where the variable is set, clear it for that command:
+Sessions reported before you set the variable keep the plan the agent guessed. To move one to a subscription by hand:
 
 ```sh
-BERLINER_PLAN= berliner update 3f1c2a9e-7b64-4d0a-9a51-2c8f0e6d1b77 --plan enterprise
+berliner update 3f1c2a9e-7b64-4d0a-9a51-2c8f0e6d1b77 --subscription work
+```
+
+While the variable is set, `report` and `update` leave `--plan` out when they change a session that already exists, with a warning, so a guessed plan can't move it off your subscription. To set a plan by hand from such a shell, clear the variable for that command:
+
+```sh
+BERLINER_VENDOR_SUBSCRIPTION_SLUG= berliner update 3f1c2a9e-7b64-4d0a-9a51-2c8f0e6d1b77 --plan pro
 ```
 
 ## Commands
@@ -102,26 +108,26 @@ berliner report \
   --evidence "./shots/after.png::Login page after the fix"
 ```
 
-Reporting again with the same `--session-id` replaces the values, adds PR URLs and skips evidence already uploaded. `--plan` is required unless `BERLINER_PLAN` is set.
+Reporting again with the same `--session-id` replaces the values, adds PR URLs and skips evidence already uploaded. `--plan` is required unless you pass `--subscription <slug>` or `BERLINER_VENDOR_SUBSCRIPTION_SLUG` is set.
 
 Evidence is private: only you can see it, signed in. Add `--public` to also make each `--evidence` file, new or already uploaded, viewable by anyone with its link. The report then prints one line per file to paste into a pull request body: a Markdown image (`![caption](https://berliner.app/v1/public/evidence/<id>)`), or the bare URL for a video, which GitHub does not embed from other hosts. With `--json` they are in `evidence.published`. Browsers and GitHub may keep a copy of a public file for up to 5 minutes after you make it private again.
 
-Inside Claude Code, Codex or OpenCode, leave out `--session-id`, `--repo`, `--cost`, `--model` and `--plan`. The CLI fills in the session id, cost and model from the tool's own records and the repository from git, and ignores an explicit `--session-id`, `--cost` or `--model` with one warning. The plan comes from `BERLINER_PLAN` or your subscriptions, as above. A report there without `--title` keeps the existing title; a new session takes the first line of your first prompt, cut to 80 characters.
+Inside Claude Code, Codex or OpenCode, leave out `--session-id`, `--repo`, `--cost`, `--model` and `--plan`. The CLI fills in the session id, cost and model from the tool's own records and the repository from git, and ignores an explicit `--session-id`, `--cost` or `--model` with one warning. The plan comes from `BERLINER_VENDOR_SUBSCRIPTION_SLUG` or your subscriptions, as above. A report there without `--title` keeps the existing title; a new session takes the first line of your first prompt, cut to 80 characters.
 
 Other commands:
 
 - `berliner setup [--yes] [--no-install] [--no-browser]`: connect this terminal and install the CLI, the skill and the hooks, as in [Quickstart](#quickstart).
-- `berliner update <session-id> [flags]`: change fields of a session without resending everything. The plan changes only when you pass `--plan`. Inside the three tools, leave out the session id.
+- `berliner update <session-id> [flags]`: change fields of a session without resending everything. The plan changes only when you pass `--plan` (left out while `BERLINER_VENDOR_SUBSCRIPTION_SLUG` is set, see [Several subscriptions](#several-subscriptions)), or `--subscription <slug>`, which moves the session to that subscription and its plan; `BERLINER_VENDOR_SUBSCRIPTION_SLUG` only applies when update creates the session, so an old session never moves to the shell's subscription. Inside the three tools, leave out the session id.
 - `berliner sessions [filters]`: list sessions. Filters: `--repo --model --project --ci --merge --since <N>d` or `--from --to`, plus `--limit` and `--json`.
 - `berliner session <session-id>`: show one session.
-- `berliner summary [filters]`: totals for the same filters as `sessions`, then one line per subscription.
+- `berliner summary [filters]`: totals for the same filters as `sessions`, then one line per subscription, labelled with its slug: `Claude Max x20 (work)`.
 - `berliner projects [--json]`: the project names in use, then each repository's default project.
 - `berliner project [<name>] [--none] [--repo owner/name] [--json]`: with no name, show this repository's default project; with a name, save it; `--none` saves that the repository has no project. The repository comes from `git remote get-url origin` unless you pass `--repo`. A session's project is its own `--project`, else its repository's default, else its ticket's prefix (`SMTNC-3268` gives `SMTNC`). Until a repository has a default, `report` and `update` print a `Project: none saved` line, which asks your agent to suggest one to you.
 - `berliner team [<uuid>] [--none]`: with no argument, print the team your sessions report to and where it came from; with a uuid, save it for this machine; `--none` clears it. A session reports to a team, or to your own plan, from the first of these that is set: `--team <uuid>` or `--no-team` on `report` and `update`, `team` in `.berliner.json` at the repository root (`{ "team": "<uuid>" }`, meant to be committed so the whole team shares it), `BERLINER_TEAM`, then the saved setting. `--no-team` beats all of them. Only the report that creates a session sends the team; it stays fixed after that, and a later setting that differs prints a warning. The server refuses a team report with `team_not_found`, `team_not_member`, `team_not_eligible` (the repository's owner is not an organization the team covers) or `team_inactive` (the team has no active plan), and the message says how to fix it. Inside Claude Code, Codex or OpenCode the hook cannot print, so the next `berliner report`, `update`, `session` or `sessions` in that repository prints it once. The team's owner sees every session and file reported to the team; members never see each other's.
 - `berliner delete <session-id>`: delete a session, or one item with `--evidence <id>`. Asks to confirm unless `--yes`.
 - `berliner evidence public <id>`: let anyone with the link view one file, and print its public URL and Markdown line. `berliner evidence private <id>` makes it private again. `berliner session` shows the ids, and the URL of each public file.
 - `berliner skill`: print the agent skill (`SKILL.md`) to install in your agent.
-- `berliner upgrade [--yes] [--no-skill]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command, each skill file and each Berliner hook it updates) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is. It brings a Berliner hook an older setup installed up to date, but never adds one; your token and config are never touched.
+- `berliner upgrade [--yes] [--no-skill] [--no-hooks]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command, each skill file and each Berliner hook it updates) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is, and `--no-hooks` leaves your hooks as they are. It brings a Berliner hook an older setup installed up to date, but never adds one; your token and config are never touched. When it updated a skill or hook, its last line names the tools to start a new session in so they load it.
 - `berliner hook <tool>`: run by the hooks setup installs, with the tool's payload on stdin. It never fails and never makes the agent wait, and prints only the reminder when a session starts; errors go to `${XDG_STATE_HOME:-~/.local/state}/berliner/hook.log`.
 
 `report` and `update` exit 0 even when something fails, printing a warning that starts with `berliner:` to stderr, so reporting never breaks an agent's pipeline. Pass `--strict` to make them exit 1 on failure, including a file that could not be uploaded or made public; the session is still saved. The other commands exit 1 on failure.

package/dist/args.js

@@ -9,6 +9,7 @@ const config = {
         "cost-status": { type: "string" },
         model: { type: "string" },
         plan: { type: "string" },
+        subscription: { type: "string" },
         task: { type: "string" },
         "task-url": { type: "string" },
         project: { type: "string" },
@@ -28,6 +29,7 @@ const config = {
         "no-install": { type: "boolean" },
         "no-browser": { type: "boolean" },
         "no-skill": { type: "boolean" },
+        "no-hooks": { type: "boolean" },
         none: { type: "boolean" },
         all: { type: "boolean" },
         run: { type: "string" },

package/dist/commands/body.js

@@ -21,6 +21,7 @@ export function sessionBody(values) {
         cost_status: values["cost-status"],
         model: values.model,
         plan: values.plan,
+        subscription: values.subscription,
         task_id: values.task,
         task_url: values["task-url"],
         project: values.project,
@@ -58,11 +59,11 @@ export async function fromTool(tool, values, env, command) {
     return filled;
 }
 // Inside a tool: the same fields, minus a derived title, for a session that exists; on a 404 (the first turn, before the hook
-// has reported), the PUT that creates it, at cost 0 while the cost is unknown and on BERLINER_PLAN when no plan is given.
-// Create-only: when another report created the session since the 404 (412), the PATCH after all, so its title and cost stay.
-export async function patchFirst(cfg, path, body, titled, guess, team = null) {
+// has reported), the PUT that creates it, at cost 0 while the cost is unknown. Create-only: when another report created the
+// session since the 404 (412), the PATCH after all, so its title and cost stay.
+export async function patchFirst(cfg, path, body, titled, team = null) {
     const patch = async () => {
-        const res = await saveSession(cfg, "PATCH", path, titled ? body : { ...body, title: undefined }, guess);
+        const res = await saveSession(cfg, "PATCH", path, titled ? body : { ...body, title: undefined });
         return { ...res, json: { created: false, ...res.json } };
     };
     try {
@@ -71,8 +72,8 @@ export async function patchFirst(cfg, path, body, titled, guess, team = null) {
     catch (err) {
         if (!(err instanceof CliError && err.status === 404))
             throw err;
-        const create = { ...body, cost_usd: body.cost_usd ?? 0, plan: body.plan ?? cfg.plan ?? undefined, team: team ?? undefined };
-        return saveSession(cfg, "PUT", path, create, guess, { "If-None-Match": "*" }).catch((err) => {
+        const create = { ...body, cost_usd: body.cost_usd ?? 0, team: team ?? undefined };
+        return saveSession(cfg, "PUT", path, create, { "If-None-Match": "*" }).catch((err) => {
             if (err instanceof CliError && err.status === 412)
                 return patch();
             throw err;
@@ -141,20 +142,27 @@ function prefilterPrs(body) {
     return { body: { ...body, prs: kept.length ? kept : undefined }, dropped };
 }
 // R46/R49: one invalid optional value must not lose the session. Bad PRs are filtered first; on a 422 naming
-// only optional fields, drop them and retry once. A plan from BERLINER_PLAN that the server rejects falls back to
-// `guess`, the agent's --plan, in that same retry; without --plan it is left out, so a new session gets the server's pick.
-// Anything else is thrown as before. Warnings are printed only once the save succeeded, so a failed save never claims
-// fields were dropped.
-export async function saveSession(cfg, method, path, input, guess, headers) {
+// only optional fields, drop them and retry once. Anything else is thrown as before. Warnings are printed only once the
+// save succeeded, so a failed save never claims fields were dropped.
+// A PUT (the report that creates a session) without --subscription is on BERLINER_VENDOR_SUBSCRIPTION_SLUG; a PATCH never
+// is, so an existing session never moves to this shell's subscription. Nor does such a PATCH send --plan: the server would
+// re-link the session by plan, off the subscription the variable gave it. A slug from the variable that the server rejects
+// is left out of the retry, which keeps the agent's --plan; without one, a new session gets the server's pick. An explicit
+// --subscription is never dropped.
+export async function saveSession(cfg, method, path, body, headers) {
+    const aliased = body.subscription === undefined && cfg.subscription !== null;
+    const fromEnv = aliased && method === "PUT";
+    const unplanned = aliased && method === "PATCH" && body.plan !== undefined;
+    const input = fromEnv ? { ...body, subscription: cfg.subscription ?? undefined } : unplanned ? { ...body, plan: undefined } : body;
     const first = prefilterPrs(input);
     const dropped = first.dropped;
-    const fromEnv = cfg.plan !== null && input.plan === cfg.plan && guess !== cfg.plan;
-    let fellBack = false;
+    let rejected;
     const finish = (res) => {
-        if (fellBack)
-            warn(`BERLINER_PLAN "${cfg.plan}" is not a plan; ${guess === undefined ? "sent the report without a plan" : `used --plan ${guess}`}`);
-        else if (fromEnv && guess !== undefined)
-            warn(`--plan ${guess} ignored, BERLINER_PLAN is ${cfg.plan}`);
+        const guess = body.plan;
+        if (rejected !== undefined)
+            warn(`BERLINER_VENDOR_SUBSCRIPTION_SLUG "${cfg.subscription}" isn't used: ${rejected}; ${guess === undefined ? "sent the report without a plan" : `used --plan ${guess}`}`);
+        else if (unplanned || (fromEnv && guess !== undefined && res.json.session.plan !== guess))
+            warn(`--plan ${guess} ignored, BERLINER_VENDOR_SUBSCRIPTION_SLUG is ${cfg.subscription}`);
         for (const d of dropped)
             warn(`${d.field}: ${d.reason}`);
         return { ...res, dropped };
@@ -164,11 +172,14 @@ export async function saveSession(cfg, method, path, input, guess, headers) {
     }
     catch (err) {
         const fieldErrors = err instanceof CliError && err.status === 422 ? err.details?.fieldErrors : undefined;
-        const names = Object.keys(fieldErrors ?? {}).filter((n) => !(n === "plan" && fromEnv));
-        fellBack = fromEnv && fieldErrors?.plan !== undefined;
-        if (!fieldErrors || !(names.length || fellBack) || !names.every((n) => optional.includes(n)))
+        const names = Object.keys(fieldErrors ?? {}).filter((n) => !(n === "subscription" && fromEnv));
+        if (fromEnv && fieldErrors?.subscription !== undefined)
+            rejected = [fieldErrors.subscription].flat().join(", ");
+        if (!fieldErrors || !(names.length || rejected !== undefined) || !names.every((n) => optional.includes(n)))
             throw err;
-        const retry = { ...first.body, ...(fellBack ? { plan: guess } : {}) };
+        const retry = { ...first.body };
+        if (rejected !== undefined)
+            delete retry.subscription;
         for (const field of names) {
             delete retry[field];
             dropped.push({ field, reason: field === "prs" ? `all PRs dropped: ${[fieldErrors[field]].flat().join(", ")}` : [fieldErrors[field]].flat().join(", ") });

package/dist/commands/hook.js

@@ -13,6 +13,7 @@ import { estimateCost, loadPrices } from "../prices.js";
 import { noteRefusal, resolveTeam, teamWarning } from "../team.js";
 import { checkTests } from "../tests/check.js";
 import { nudge } from "../tests/nudge.js";
+import { upgradeNotice } from "../version.js";
 // Same text in the OpenCode plugin (cli/opencode/berliner.js).
 const REMINDER = 'This session reports to Berliner. Once you know the task, name it: berliner update --title "<short title>". When a Linear or Jira ticket comes up, report it: berliner update --task <ID> --task-url <URL>. Before your final message, run berliner report with the PRs.';
 const TOOLS = ["claude-code", "codex", "opencode"];
@@ -103,9 +104,11 @@ async function start(tool, env) {
     }
     else {
         // In the agent's context from the start, whether or not the skill triggers; after a compaction or /clear it may have lost
-        // the task and PRs it hasn't reported yet.
-        if (p.hook_event_name === "SessionStart" && SESSION_STARTS.includes(p.source))
-            return console.log(REMINDER);
+        // the task and PRs it hasn't reported yet. The day's upgrade check goes with it, so the agent can tell the user.
+        if (p.hook_event_name === "SessionStart" && SESSION_STARTS.includes(p.source)) {
+            const notice = await upgradeNotice(env);
+            return console.log(notice ? `${REMINDER}\n${notice}` : REMINDER);
+        }
         if (!REPORT_EVENTS.includes(p.hook_event_name))
             return;
         id = p.session_id;
@@ -237,28 +240,32 @@ async function send(tool, file, env) {
         saved = await request(cfg, "PATCH", path, body);
     }
     catch (err) {
+        if (isRefusal(err))
+            noteRefusal(env, repository, err.message);
         if (!(err instanceof CliError && err.status === 404))
             throw err;
-        // The plan is BERLINER_PLAN from the tool's environment, else the server's pick from the user's subscriptions. A new
-        // session needs a cost: 0 until prices load. Create-only: when an agent report created the session since the 404 (412),
-        // only the machine's fields are sent. A server that ignores the header overwrites the title, as before.
-        const create = (plan) => request(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0, title: derivedTitle(facts.firstPrompt, git), plan, team }, { headers: { "If-None-Match": "*" } }).catch((err) => {
+        // The plan is that of BERLINER_VENDOR_SUBSCRIPTION_SLUG from the tool's environment, else the server's pick from the
+        // user's subscriptions. A new session needs a cost: 0 until prices load. Create-only: when an agent report created the
+        // session since the 404 (412), only the machine's fields are sent. A server that ignores the header overwrites the
+        // title, as before.
+        const create = (subscription) => request(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0, title: derivedTitle(facts.firstPrompt, git), subscription, team }, { headers: { "If-None-Match": "*" } }).catch((err) => {
             if (err instanceof CliError && err.status === 412)
                 return request(cfg, "PATCH", path, body);
             // Never a personal session instead: the next foreground command in this repository prints the refusal.
-            if (err instanceof CliError && err.status === 422 && err.code?.startsWith("team_"))
+            if (isRefusal(err))
                 noteRefusal(env, repository, err.message);
             throw err;
         });
         try {
-            saved = await create(cfg.plan ?? undefined);
+            saved = await create(cfg.subscription ?? undefined);
         }
         catch (err) {
-            // A BERLINER_PLAN the server rejects must not lose the session: the server picks the plan instead.
-            if (!(cfg.plan && err instanceof CliError && err.status === 422 && err.details?.fieldErrors?.plan))
+            // A slug the server rejects must not lose the session: the server picks the plan instead.
+            const rejected = cfg.subscription && err instanceof CliError && err.status === 422 ? err.details?.fieldErrors?.subscription : undefined;
+            if (!rejected)
                 throw err;
             saved = await create(undefined);
-            log(env, `${tool} ${sessionId}: BERLINER_PLAN "${cfg.plan}" is not a plan; the server picked the plan`);
+            log(env, `${tool} ${sessionId}: BERLINER_VENDOR_SUBSCRIPTION_SLUG "${cfg.subscription}" isn't used: ${[rejected].flat().join(", ")}; the server picked the plan`);
         }
     }
     const mismatch = teamWarning(saved.json.session.team, team ?? null);
@@ -266,6 +273,8 @@ async function send(tool, file, env) {
         log(env, `${tool} ${sessionId}: ${mismatch}`);
     await refreshPrs(cfg, path, saved.json.session.prs, env, `${tool} ${sessionId}`);
 }
+// A 422 the user must hear about: no plan, or a team the server refuses.
+const isRefusal = (err) => err instanceof CliError && err.status === 422 && (err.code === "plan_required" || !!err.code?.startsWith("team_"));
 // Untracked PRs keep their last reported state, so the machine's gh refreshes the open ones; the poller owns tracked PRs.
 // In parallel, 5 seconds each, inside the child's deadline. Only changes are sent.
 async function refreshPrs(cfg, path, prs, env, where) {

package/dist/commands/report.js

@@ -14,9 +14,9 @@ export async function report(cfg, values, positionals, env) {
     const titled = values.title !== undefined;
     if (tool)
         values = await fromTool(tool, values, env, "report");
-    // BERLINER_PLAN stands in for --plan. Inside a tool, a report without a plan leaves it to the server, and one without a
-    // cost has no prices to estimate it.
-    const missing = required.filter((flag) => values[flag] === undefined && !(flag === "plan" && cfg.plan) && !(tool && (flag === "plan" || flag === "cost")));
+    // --subscription or BERLINER_VENDOR_SUBSCRIPTION_SLUG stands in for --plan. Inside a tool, a report without a plan leaves it to the server,
+    // and one without a cost has no prices to estimate it.
+    const missing = required.filter((flag) => values[flag] === undefined && !(flag === "plan" && (values.subscription || cfg.subscription)) && !(tool && (flag === "plan" || flag === "cost")));
     if (missing.length)
         throw new CliError(`missing required flag(s): ${missing.map((f) => `--${f}`).join(", ")}`, "usage");
     if (values.public && !values.evidence?.length)
@@ -24,14 +24,14 @@ export async function report(cfg, values, positionals, env) {
     // Parsed before anything is saved, so a bad label saves nothing.
     const evidence = (values.evidence ?? []).map(parseEvidence);
     const team = await resolveTeam(values, process.cwd(), env);
-    const body = { ...sessionBody(values), plan: cfg.plan ?? values.plan };
+    const body = sessionBody(values);
     const id = values["session-id"];
     const path = `/v1/sessions/${encodeURIComponent(id)}`;
     // Inside a tool a report without --title is usually a follow-up: the derived title is only for a new session. A report
     // without a cost must not replace the saved one either.
     const { json: saved, dropped } = await (tool && (!titled || body.cost_usd === undefined)
-        ? patchFirst(cfg, path, body, titled, values.plan, team)
-        : saveSession(cfg, "PUT", path, { ...body, team: team ?? undefined }, values.plan));
+        ? patchFirst(cfg, path, body, titled, team)
+        : saveSession(cfg, "PUT", path, { ...body, team: team ?? undefined }));
     const json = dropped.length ? { ...saved, dropped } : saved;
     const { created, session } = json;
     warnTeam(session, team);

package/dist/commands/summary.js

@@ -19,7 +19,7 @@ export async function summary(cfg, values) {
 function subscriptionLines(c) {
     if (!c)
         return [];
-    const lines = c.rows.map((r) => `${subscriptionLabel(r)}: ${totalLabel(r.spend_usd, r.unpriced_sessions ?? 0)} used of $${r.prorated_usd.toFixed(2)} paid (${r.multiple.toFixed(1)}×), ${r.sessions} session(s)`);
+    const lines = c.rows.map((r) => `${subscriptionLabel(r)} (${r.slug}): ${totalLabel(r.spend_usd, r.unpriced_sessions ?? 0)} used of $${r.prorated_usd.toFixed(2)} paid (${r.multiple.toFixed(1)}×), ${r.sessions} session(s)`);
     if (c.unmatched.sessions > 0)
         lines.push(`On no listed plan: ${totalLabel(c.unmatched.spend_usd, c.unmatched.unpriced_sessions ?? 0)}, ${c.unmatched.sessions} session(s)`);
     return lines;

package/dist/commands/update.js

@@ -18,11 +18,11 @@ export async function update(cfg, values, positionals, env) {
     if (tool)
         values = await fromTool(tool, { ...values, "session-id": positionals[0] ?? values["session-id"] }, env, "update");
     const id = tool ? tool.sessionId : positionals[0];
-    // A plan is only sent when --plan is passed, so an update never changes it unasked; BERLINER_PLAN then replaces it.
-    const body = { ...sessionBody(values), plan: values.plan === undefined ? undefined : (cfg.plan ?? values.plan) };
+    // A plan is only sent when --plan or --subscription is passed, so an update never changes it unasked.
+    const body = sessionBody(values);
     const team = await resolveTeam(values, process.cwd(), env);
     const path = `/v1/sessions/${encodeURIComponent(id)}`;
-    const { json: saved, dropped } = await (tool ? patchFirst(cfg, path, body, titled, values.plan, team) : saveSession(cfg, "PATCH", path, body, values.plan));
+    const { json: saved, dropped } = await (tool ? patchFirst(cfg, path, body, titled, team) : saveSession(cfg, "PATCH", path, body));
     const json = dropped.length ? { ...saved, dropped } : saved;
     warnTeam(json.session, team);
     print({ data: json, text: `Updated session ${json.session.id}. ${json.session.pr_count} PR(s) linked.${projectHint(json.session)}` }, values.json === true);

package/dist/commands/upgrade.js

@@ -6,24 +6,9 @@ import { gunzipSync } from "node:zlib";
 import { CliError } from "../client.js";
 import { hookPath, updatedHooks } from "../setup/hooks.js";
 import { detectTools, skillTargets } from "../setup/targets.js";
+import { currentVersion, latestVersion, newer, registryOf } from "../version.js";
 import { askNudge } from "./nudge.js";
 import { confirm, installCommand, showPlan, tilde } from "./setup.js";
-const registryOf = (env) => (env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
-async function latestVersion(env) {
-    const registry = registryOf(env);
-    try {
-        const res = await fetch(`${registry}/@paxnax/berliner/latest`);
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-        const { version } = (await res.json());
-        if (typeof version !== "string")
-            throw new Error("no version in the reply");
-        return version;
-    }
-    catch (err) {
-        throw new CliError(`Could not look up the latest berliner on ${registry} (${err.message}). Nothing was changed.`, "network");
-    }
-}
 // The skill and the OpenCode plugin come from the release being installed, so the plan's "already up to date" and what is
 // written match it. They are read out of the release tarball as data: running the release (npx) would load the cwd's .npmrc
 // and node_modules.
@@ -63,12 +48,6 @@ async function releaseFiles(version, bundled, env) {
         throw new CliError(`Could not read the skill and OpenCode plugin of berliner ${version} (${err.message}). Nothing was changed.`, "network");
     }
 }
-// Release versions only (x.y.z): the registry's latest tag never points at a prerelease.
-const newer = (a, b) => {
-    const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
-    const i = x.findIndex((n, j) => n !== y[j]);
-    return i >= 0 && x[i] > y[i];
-};
 const sameAs = (path, text) => {
     try {
         return readFileSync(path, "utf8") === text;
@@ -85,7 +64,7 @@ const HOOK_CHANGE = {
 };
 // The command, the skill, and Berliner hooks already installed: the token and config are setup's, as is adding a hook.
 export async function upgrade(env, values) {
-    const current = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    const current = currentVersion();
     const latest = await latestVersion(env);
     // A CLI ahead of the registry (a local build, a release still propagating) is never taken backwards, nor is its skill.
     const installing = newer(latest, current);
@@ -94,11 +73,12 @@ export async function upgrade(env, values) {
     const tools = detectTools(env);
     const targets = values["no-skill"] ? [] : skillTargets(tools, env);
     // The plugin too, so --no-skill still brings it up to date.
-    const release = targets.length || tools.some((t) => t.id === "opencode" && t.found) ? await releaseFiles(target, !installing, env) : null;
+    const plugin = !values["no-hooks"] && tools.some((t) => t.id === "opencode" && t.found);
+    const release = targets.length || plugin ? await releaseFiles(target, !installing, env) : null;
     const skill = release?.skill ?? "";
     let stale = targets.filter((t) => !sameAs(t.path, skill));
     // Computed now, for the plan.
-    const hooks = tools.flatMap((tool) => {
+    const hooks = (values["no-hooks"] ? [] : tools).flatMap((tool) => {
         const path = hookPath(tool.id, env);
         const text = updatedHooks(tool.id, path, release?.plugin);
         return text === null ? [] : [{ ...tool, path, text }];
@@ -126,13 +106,15 @@ export async function upgrade(env, values) {
                     return `${tool.name.padEnd(14)}${where}`;
                 }),
             },
-        ...(hooks.length
-            ? [{ label: "Update the Berliner hook for:", detail: hooks.map((h) => `${h.name.padEnd(14)}${tilde(h.path)} (${HOOK_CHANGE[h.id]})`) }]
-            : []),
+        ...(values["no-hooks"]
+            ? [{ label: "Leave the Berliner hooks as they are (--no-hooks)", detail: [] }]
+            : hooks.length
+                ? [{ label: "Update the Berliner hook for:", detail: hooks.map((h) => `${h.name.padEnd(14)}${tilde(h.path)} (${HOOK_CHANGE[h.id]})`) }]
+                : []),
     ]);
     if (!values.yes) {
         if (!process.stdin.isTTY)
-            throw new CliError("There is no terminal to ask on. Run upgrade again with --yes to continue without asking.", "usage");
+            throw new CliError("There is no terminal to ask on, so nothing was changed. To go ahead without asking, run upgrade again with --yes. If you are an AI agent, show the user this plan and get their approval first.", "usage");
         if (!(await confirm(process.stdin, process.stdout)))
             throw new CliError("Cancelled. Nothing was changed.", "usage");
         // Without an install, the skill is all Continue covered.
@@ -152,12 +134,15 @@ export async function upgrade(env, values) {
     }
     // A file that can't be written (read-only, say) is reported and skipped, so the other tools still get theirs.
     let unwritten = false;
+    // The tools that load what was written, for the reload line.
+    const reload = { skill: new Set(), hooks: new Set() };
     for (const t of stale) {
         const what = `${tools.find((tool) => tool.id === t.tool).name} skill`;
         try {
             mkdirSync(dirname(t.path), { recursive: true });
             writeFileSync(t.path, skill);
             console.log(`✓ ${what}: ${tilde(t.path)}`);
+            reload.skill.add(t.tool);
         }
         catch (err) {
             unwritten = true;
@@ -175,11 +160,16 @@ export async function upgrade(env, values) {
             // In place, so a settings file that is a symlink stays one.
             writeFileSync(h.path, text);
             console.log(`✓ ${h.name} hook: ${tilde(h.path)}`);
+            reload.hooks.add(h.id);
         }
         catch (err) {
             unwritten = true;
             console.error(`✗ ${h.name} hook: ${tilde(h.path)} can't be written (${err.message.split(",")[0]})`);
         }
     }
-    console.log(unwritten ? "\nSome files can't be written. Fix the ones marked ✗ above, then run upgrade again." : "\nDone.");
+    // A running agent keeps the skill and hooks it started with; the command itself is new from the next call.
+    const names = tools.filter((t) => reload.skill.has(t.id) || reload.hooks.has(t.id)).map((t) => t.name);
+    const what = [reload.skill.size && "skill", reload.hooks.size && "hooks"].filter(Boolean).join(" and ");
+    const again = names.length ? ` Start a new session in ${names.join(", ").replace(/, ([^,]*)$/, " and $1")} to load the updated ${what}.` : "";
+    console.log(unwritten ? `\nSome files can't be written. Fix the ones marked ✗ above, then run upgrade again.${again}` : `\nDone.${again}`);
 }

package/dist/config.js

@@ -44,5 +44,9 @@ export function saveConfig(env, value) {
 }
 export function readConfig(env) {
     const file = readConfigFile(env);
-    return { url: env.BERLINER_URL || file?.url || DEFAULT_URL, token: env.BERLINER_TOKEN || file?.token || null, plan: env.BERLINER_PLAN || null };
+    return {
+        url: env.BERLINER_URL || file?.url || DEFAULT_URL,
+        token: env.BERLINER_TOKEN || file?.token || null,
+        subscription: env.BERLINER_VENDOR_SUBSCRIPTION_SLUG || null,
+    };
 }

package/dist/index.js

@@ -19,15 +19,17 @@ import { update } from "./commands/update.js";
 import { upgrade } from "./commands/upgrade.js";
 import { readConfig } from "./config.js";
 import { warn } from "./output.js";
+import { upgradeNotice } from "./version.js";
 const usage = `Usage: berliner <command> [flags]
 
 Commands:
   setup                 connect this terminal, install the CLI and skill [--yes --no-install --no-browser]
-  report --session-id <id> --title <t> --repo <owner/name> --cost <usd> --model <m> --plan <p>
+  report --session-id <id> --title <t> --repo <owner/name> --cost <usd> --model <m> --plan <p> | --subscription <slug>
          [--task --task-url --project --started-at --ended-at --commits --coverage]
          [--pr <url>[,merge=<state>][,ci=<state>]]... [--evidence <path>[::caption]]... [--public] [--json] [--strict]
          inside Claude Code, Codex or OpenCode the session id, cost, model and repo are filled in,
-         and the server picks the plan (BERLINER_PLAN overrides it)
+         and the server picks the plan (BERLINER_VENDOR_SUBSCRIPTION_SLUG overrides it for a new session)
+         --subscription puts the session on that subscription and its plan, over the variable
   update <session-id>   same flags as report, all optional (no session id inside those tools)
   sessions              [--repo --model --project --ci --merge --since <N>d | --from --to] [--limit <n>] [--json]
   session <session-id>  [--json]
@@ -43,11 +45,12 @@ Commands:
   delete <session-id>   [--evidence <id>] [--yes]
   evidence public <id>  let anyone with the link view one file; prints its URL and Markdown [--json]
   evidence private <id> make it viewable only by you again [--json]
-  upgrade               install the latest CLI and skill [--yes --no-skill]
+  upgrade               install the latest CLI, skill and hooks [--yes --no-skill --no-hooks]
   skill                 print the bundled SKILL.md
   hook <tool>           run by the hooks of claude-code, codex or opencode; reads the payload on stdin
 
-Environment: BERLINER_TOKEN, BERLINER_URL, BERLINER_PLAN (replaces --plan), BERLINER_TEAM`;
+Environment: BERLINER_TOKEN, BERLINER_URL, BERLINER_VENDOR_SUBSCRIPTION_SLUG (the subscription of new sessions),
+             BERLINER_TEAM`;
 const args = parse(process.argv.slice(2));
 // Reporting must never fail the agent's own pipeline unless it asks to (anti-goal 1).
 const softFail = (args.command === "report" || args.command === "update") && !args.values.strict;
@@ -114,3 +117,9 @@ catch (err) {
         console.error(usage);
     process.exitCode = softFail ? 0 : 1;
 }
+// The hook carries it in the session-start reminder instead, and upgrade looks for itself.
+if (args.command !== "hook" && args.command !== "upgrade") {
+    const notice = await upgradeNotice(process.env);
+    if (notice)
+        console.error(notice);
+}

package/dist/version.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "./client.js";
+import { stateDir } from "./config.js";
+export const registryOf = (env) => (env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+export const currentVersion = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export async function latestVersion(env, timeoutMs) {
+    const registry = registryOf(env);
+    try {
+        const res = await fetch(`${registry}/@paxnax/berliner/latest`, { signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const { version } = (await res.json());
+        if (typeof version !== "string")
+            throw new Error("no version in the reply");
+        return version;
+    }
+    catch (err) {
+        throw new CliError(`Could not look up the latest berliner on ${registry} (${err.message}). Nothing was changed.`, "network");
+    }
+}
+// Release versions only (x.y.z): the registry's latest tag never points at a prerelease.
+export const newer = (a, b) => {
+    const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
+    const i = x.findIndex((n, j) => n !== y[j]);
+    return i >= 0 && x[i] > y[i];
+};
+const DAY_MS = 24 * 3600_000;
+// Short, as it runs inline: the first command or session start of the day waits for it.
+const CHECK_TIMEOUT_MS = 1500;
+// Once a day per machine: the check file's mtime is when the last check started. A failed check counts too, so an
+// offline machine doesn't wait on every run. Never throws; null unless the registry has a newer release.
+export async function upgradeNotice(env) {
+    const stamp = join(stateDir(env), "version-check");
+    try {
+        if (Date.now() - statSync(stamp).mtimeMs < DAY_MS)
+            return null;
+    }
+    catch {
+        // Never checked on this machine.
+    }
+    try {
+        // Before the lookup, so runs started meanwhile don't check again.
+        mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
+        writeFileSync(stamp, "");
+        const latest = await latestVersion(env, CHECK_TIMEOUT_MS);
+        if (!newer(latest, currentVersion()))
+            return null;
+        return `New berliner CLI version ${latest} is out, run berliner upgrade to update it. If you are an AI agent, bring this to the user for approval instead of taking action yourself.`;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Report coding-agent sessions to Berliner",
   "keywords": [
     "claude-code",

package/skill/SKILL.md

@@ -30,7 +30,7 @@ Hooks installed by `berliner setup` already report the session's cost, model, re
 | `--evidence` | Each screenshot or video. |
 | `--team`, `--no-team` | Only when the user asks for a one-off. See [Teams](#teams). |
 
-Do not pass `--session-id`, `--cost` or `--model`: the CLI fills them in from the tool's own records, and an explicit value is ignored with a warning. `--repo` and `--plan` are not needed either: the plan comes from the user's `BERLINER_PLAN`, or from their subscriptions in Settings. A report without `--title` keeps the session's existing title. `berliner update` ignores a session ID here.
+Do not pass `--session-id`, `--cost` or `--model`: the CLI fills them in from the tool's own records, and an explicit value is ignored with a warning. `--repo` and `--plan` are not needed either: the plan comes from the user's `BERLINER_VENDOR_SUBSCRIPTION_SLUG`, or from their subscriptions in Settings. A report without `--title` keeps the session's existing title. `berliner update` ignores a session ID here.
 
 ## Name the session
 
@@ -137,7 +137,7 @@ Without a hook, `report` needs these flags:
 | `--repo` | `owner/name`, from `git remote get-url origin`. |
 | `--cost` | Estimated USD. Your harness's reported session cost if it shows one, otherwise estimate from token usage at the model's API prices. |
 | `--model` | The primary model ID you ran on. |
-| `--plan` | Your best guess at the plan you run on. Claude: `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`. OpenAI (Codex): `free`, `go`, `plus`, `pro`, `pro_more`, `pro_max`, `business`, `business_premium`. Billed per token: `api`. Always pass it: when the user has set `BERLINER_PLAN`, that value replaces yours. |
+| `--plan` | Your best guess at the plan you run on. Claude: `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`. OpenAI (Codex): `free`, `go`, `plus`, `pro`, `pro_more`, `pro_max`, `business`, `business_premium`. Billed per token: `api`. Always pass it: when the user has set `BERLINER_VENDOR_SUBSCRIPTION_SLUG`, that subscription's plan replaces yours. |
 
 Report again with the same `--session-id` whenever something changes.
 
@@ -167,10 +167,27 @@ After the evidence line, it prints one line per file: `![Login page after the fi
 
 ## Environment
 
-`berliner setup` stores the API token in a config file, so `BERLINER_TOKEN` is only needed to override it (a token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address. `BERLINER_PLAN`, when the user sets it, replaces any `--plan`.
+`berliner setup` stores the API token in a config file, so `BERLINER_TOKEN` is only needed to override it (a token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address. `BERLINER_VENDOR_SUBSCRIPTION_SLUG`, when the user sets it, names their subscription, and its plan replaces any `--plan`.
 
 If the `berliner` command is not found, carry on with your work and say in your final message that `npx @paxnax/berliner@latest setup` needs to run. Do not try to install it yourself.
 
+## When a newer berliner is out
+
+Once a day the CLI checks for a newer release. When there is one, the session-start reminder or a `berliner` command's output says: `New berliner CLI version X.Y.Z is out, run berliner upgrade to update it. If you are an AI agent, bring this to the user for approval instead of taking action yourself.` Never upgrade on your own:
+
+1. Run `berliner upgrade` with no flags. Without a terminal it prints its plan and stops, changing nothing.
+2. Show the user the plan, then ask them to approve each part separately: the berliner command, the skill and the hooks.
+3. If they decline the command, run nothing. Otherwise run the command that matches their answers. It never stops to ask:
+
+| Skill | Hooks | Command |
+|---|---|---|
+| yes | yes | `berliner upgrade --yes` |
+| no | yes | `berliner upgrade --yes --no-skill` |
+| yes | no | `berliner upgrade --yes --no-hooks` |
+| no | no | `berliner upgrade --yes --no-skill --no-hooks` |
+
+4. Pass on the upgrade's last line. When it names tools to start a new session in, tell the user the updated skill or hooks load only in a new session there.
+
 ## Timeouts
 
 The session is saved first, then evidence is uploaded. Allow at least 10 minutes for the command when attaching videos.