@beunec/rivine 0.2.1 → 0.3.1

package/README.md

@@ -16,35 +16,35 @@ files it reads and writes are **the ones already on your disk**, in the
 directory you started it in, open in your editor, tracked by your git.
 
 Nothing is uploaded. There is no "attach your repo" step and no sync. The
-engine asks for a file, this client reads it, and the answer goes back — one
+engine asks for a file, this client reads it, and the answer goes back, one
 file at a time, only the ones it actually opens. A 40,000-file monorepo costs
 nothing to start working in, because nothing is copied anywhere.
 
 ## What it does
 
 - Reads, writes and edits files in your working directory
-- Runs commands — your shell, your PATH, your nvm/pyenv shims
-- Delegates to the same sub-agent lanes as the web engine: frontend, backend,
-  integration, security review, CI/CD, deploy
+- Runs commands: your shell, your PATH, your nvm/pyenv shims
+- Runs as one mode, the same five as the web engine: Frontend, Backend,
+  Full Stack, Plan/Ask, or Security
 - Asks you a question when a decision is genuinely yours to make
 - Keeps a per-project memory in `.rivine/`, so tomorrow's session knows what
   yesterday's did
 
 ## Running commands
 
-Commands run in your own shell, in your working directory, streaming — you see
+Commands run in your own shell, in your working directory, streaming. You see
 output as it is produced, not in one block when the command exits. A two-minute
 install and a hung one no longer look the same.
 
 Where the platform allows it the command gets a real terminal (a PTY), which
 means `isatty` is true and tools behave the way they do when you run them by
 hand: colour, progress bars, and the interactive prompts some of them open with.
-If a command asks you something, type the answer and press Enter — while a
+If a command asks you something, type the answer and press Enter. While a
 command is running your input goes to the command, not to the agent. `esc`
 stops it; the agent sees the non-zero exit and decides what to do about it.
 
 The terminal comes from `node-pty`, an optional dependency. If it cannot be
-installed or a PTY cannot be allocated, commands still run and still stream —
+installed or a PTY cannot be allocated, commands still run and still stream,
 just without a terminal. Nothing fails. `RIVINE_NO_PTY=1` forces the pipe path.
 
 What you see and what the model is sent are deliberately different. Escape codes
@@ -56,15 +56,15 @@ cost more per turn than not having one.
 ## Mode and Rate
 
 Two choices, both required, and neither is inferred from what you type. There is
-no router — no keyword matcher, no classifier, no extra model turn that reads
+no router: no keyword matcher, no classifier, no extra model turn that reads
 your request and picks a lane. A wrong guess sends a database migration to the
 frontend agent and you never see the decision that was made for you.
 
-### Mode — which agent runs
+### Mode: what Rivine Code works on
 
-Each Mode is one standalone agent that owns the task end to end: it searches the
-codebase, reads what it needs, writes across as many files as the change
-requires, runs the build and tests, and fixes what the terminal reports.
+Each Mode owns the task end to end: it searches the codebase, reads what it
+needs, writes across as many files as the change requires, runs the build and
+tests, and fixes what the terminal reports.
 
 | Mode | For | How to choose |
 |---|---|---|
@@ -74,47 +74,52 @@ requires, runs the build and tests, and fixes what the terminal reports.
 | `simple` | Plan, ask, document, refresh, ship | `4`, `-m simple`, `--plan` |
 | `security` | Find, verify, and patch vulnerabilities | `5`, `-m security` |
 
-`simple` is the only Mode with live web access — its work is the work that
+`simple` is the only Mode with live web access. Its work is the work that
 depends on the world outside the repository. The build Modes are measured on
 whether the software runs.
 
-### Rate — how edits apply
+### Rate: how edits apply
 
 The engine runs on our servers. The decision about what happens to your machine
-is made **here**, on your machine, before anything runs — never on our servers.
+is made **here**, on your machine, before anything runs, never on our servers.
 
 | Rate | Applies without asking | How to choose |
 |---|---|---|
 | `manual` | Reads and read-only commands. Asks before every write, edit, or delete | `1`, `--rate manual` (default) |
 | `bypass` | Writes and ordinary commands inside this project | `2`, `--rate bypass`, `--bypass` |
 
-Three things ask in **both** Rates, because they are what you would want to see
+Three things still ask in `manual`, because they are what you would want to see
 even having said "just do it": credentials, anything outside the project
 directory, and commands that are hard to undo (`rm -rf`, `git push --force`, a
-deploy).
+deploy). `bypass` does not ask. A path outside the project is refused there,
+not approved.
 
-The first interactive session asks for Mode, then Rate. `-m …` and `--rate …`
-skip the questions because you already answered them. Shift+Tab toggles the
-Rate.
+The first interactive session asks for Mode, then Rate, before the prompt
+opens, including for a one-shot `rivine "..."`. `-m …` and `--rate …` skip the
+question you already answered on the command line. Shift+Tab toggles the Rate.
+`/mode` and `/rate` reopen either picker later.
+
+Without a terminal to ask on (a pipe, CI, another agent driving this), `-m`
+is required and the run stops with the list rather than guessing.
 
 What stays gated:
 
 - **Anything outside the project.** Refused in `bypass` (set
-  `RIVINE_ALLOW_OUTSIDE_PROJECT=1` if you mean it). Other modes ask. The jail
+  `RIVINE_ALLOW_OUTSIDE_PROJECT=1` if you mean it). Other Rates ask. The jail
   resolves symlinks first, so a link pointing out of the directory is caught
   rather than followed.
-- **Credentials** — every mode except `bypass`. `.env`, `*.pem`, `~/.ssh`,
-  `~/.aws`, service-account JSON. These ask on *read* too — reading one puts
+- **Credentials:** every Rate except `bypass`. `.env`, `*.pem`, `~/.ssh`,
+  `~/.aws`, service-account JSON. These ask on *read* too. Reading one puts
   a live secret into a model prompt.
-- **Commands that are hard to undo** — every mode except `bypass`. `rm -rf`,
+- **Commands that are hard to undo:** every Rate except `bypass`. `rm -rf`,
   `git push`, `--force`, `git reset --hard`, `sudo`, `npm publish`, any
   deploy, `terraform apply`.
-- **Batch writes** — every mode except `bypass`. Judged by their most
+- **Batch writes:** every Rate except `bypass`. Judged by their most
   dangerous entry, so a safe first file cannot clear a whole batch.
 
-One exemption: `.rivine/` — the agent's own notebook for this project, seeded at
-session start and appended to at the end of each turn. It writes without asking
-(except in `plan` mode), for the same reason `.git/` does. It ships with its own
+One exemption: `.rivine/`, the agent's own notebook for this project, seeded at
+session start and appended to at the end of each turn. It writes without asking,
+for the same reason `.git/` does. It ships with its own
 `.gitignore`.
 
 ## Commands
@@ -138,10 +143,11 @@ rivine mcp login <name>         sign in to a remote MCP server
 rivine --output-format json     one JSON object on stdout, for CI
 ```
 
-In a session: type `/` and press Tab. `/help` `/agent` `/mode` `/plan` `/accept`
+In a session: type `/` and press Tab. `/help` `/mode` `/rate` `/plan` `/accept`
 `/status` `/diff` `/pr` `/mcp` `/credits` `/clear` `/exit`. Startup asks for
-**Mode** (which agent) then **Rate** (Manual or Bypass). `/agent` and `/mode`
-reopen those pickers. Shift+Tab toggles Manual ⇄ Bypass. Ctrl+C quits cleanly.
+**Mode** (what Rivine Code works on) then **Rate** (Manual or Bypass); `/mode`
+and `/rate` reopen those pickers. Shift+Tab toggles Manual ⇄ Bypass. Ctrl+C
+quits cleanly.
 
 `/diff` shows what changed in the working tree. `/pr` prepares a pull request
 through your own `gh` CLI. It **never pushes without being asked**: on a
@@ -152,11 +158,11 @@ form that writes to the remote. It also refuses on `main`, and refuses if
 There is no `/compact` or `/summarize`. Context is compacted on the server as
 part of how the engine runs, so there is nothing here to trigger by hand.
 Opening `rivine` in a directory you have used before continues that
-directory's thread — earlier turns are still in context, and the session says
+directory's thread. Earlier turns are still in context, and the session says
 so on startup.
 
 Answers are single keys, and the keys are always printed: `y` allow, `n` skip,
-`a` allow all this session, `esc` cancel. Choices are numbered — press the
+`a` allow all this session, `esc` cancel. Choices are numbered. Press the
 number. Nothing here makes you type a word to answer a question.
 
 `a` is offered for ordinary writes only. Credentials, paths outside the project
@@ -166,7 +172,7 @@ ones where per-operation consent still means something.
 ### Without a terminal
 
 Piped, redirected, in CI, or driven by another tool, there is no keyboard to
-read — so `rivine -p "..."` switches to a plain renderer with no cursor
+read, so `rivine -p "..."` switches to a plain renderer with no cursor
 movement and no repaint, safe to redirect to a log.
 
 Anything that would prompt is **refused**, not auto-approved, and the refusal
@@ -182,7 +188,7 @@ rivine -m fullstack --rate bypass -p "..."   # CI, on a machine you accept chang
 
 Authorization Code with PKCE over a loopback redirect. Your browser opens to
 `aselius.beunec.com/cli/authorize`, which recognises your existing session and
-asks you to confirm this terminal, then redirects to `127.0.0.1:1455` — a port
+asks you to confirm this terminal, then redirects to `127.0.0.1:1455`, a port
 only a process on your own machine can listen on.
 
 Device code (`--device`) exists for headless machines and is not the default,
@@ -199,19 +205,19 @@ is in use. In CI, set `RIVINE_TOKEN` and neither is touched.
 **It is the same Aselius account, not a second one.** Auth0 only answers "who
 is this person"; your cloudhandle, your BCID and your wallet live in Beunec's
 own systems and are looked up from that answer. The terminal signs in through a
-different OAuth client than the website, which is why you approve it separately
-— but it resolves to the same identity, the same taskspaces and the same
+different OAuth client than the website, which is why you approve it separately,
+but it resolves to the same identity, the same taskspaces and the same
 credits. Sign in as the account you use on aselius.beunec.com and it is
 literally the same you.
 
 `rivine status` shows a `Renews:` line. If it says `no`, your session cannot
-refresh itself and ends when the token expires — sign in again when it does.
+refresh itself and ends when the token expires. Sign in again when it does.
 That depends on a tenant setting, not on anything you can change locally.
 
 ## MCP servers
 
 Rivine hosts MCP servers **from your machine**, the same way Claude Code and
-Codex do — not from our cloud.
+Codex do, not from our cloud.
 
 ```
 rivine mcp add playwright npx @playwright/mcp@latest
@@ -223,7 +229,7 @@ rivine mcp remove <name>
 
 In a session, `/mcp` shows what connected and what didn't.
 
-**Why on your machine.** A stdio server *is* a local process — `npx`, `uvx`, a
+**Why on your machine.** A stdio server *is* a local process: `npx`, `uvx`, a
 docker container, a bridge to your own database. Nothing running in our cloud
 can spawn it. And for remote servers, calling from here means your tokens stay
 on your machine instead of in our infrastructure, and tool results never transit
@@ -235,7 +241,7 @@ as it asks it to read a file.
 
 | File | For |
 |---|---|
-| `<project>/.rivine/mcp.json` | servers this repo needs — committable, so teammates get them |
+| `<project>/.rivine/mcp.json` | servers this repo needs, committable, so teammates get them |
 | `~/.rivine/mcp.json` | servers you use everywhere (`--user`) |
 
 Project wins on a name collision. Secrets are never stored: `env` values written
@@ -244,9 +250,8 @@ remote server's token is referenced by variable name (`--token-env`), never by
 value.
 
 **Permissions.** An MCP tool can read a database, drive a browser or post to an
-API — closer to running a command than reading a file, so it is gated like one.
-Every call asks; `plan` mode refuses them outright, because a tool's schema does
-not say whether it writes. "Allow all this session" is scoped to **one server**:
+API, closer to running a command than reading a file, so it is gated like one.
+Every call asks, because a tool's schema does not say whether it writes. "Allow all this session" is scoped to **one server**:
 approving Playwright never silently approves a database server that connects
 later.
 
@@ -255,20 +260,20 @@ startup. The others still connect and their tools are still offered.
 
 **Only the tools a turn needs.** Rivine does not put every connected tool in
 front of the model on every turn. Servers are scored against your prompt, and an
-unrelated request gets none of them — asking to fix a typo does not hand the
+unrelated request gets none of them. Asking to fix a typo does not hand the
 model a browser. Naming a server always includes it (`use playwright to…`), and
 a server comes in as a whole set, because a browser you can open but not drive
 is worse than no browser. The session line tells you which servers were used and
 which were skipped.
 
-That is not only a cost control, though it is one — every tool definition is
+That is not only a cost control, though it is one. Every tool definition is
 tokens you pay for on every turn. It is mostly a quality control: a model
 holding a capability tends to find a reason to use it.
 
 ### Remote servers that need a sign-in
 
 `--token-env` covers servers with a static API key. For hosted servers that
-authenticate per user, there is nothing to paste — the credential does not
+authenticate per user, there is nothing to paste. The credential does not
 exist until you consent:
 
 ```bash
@@ -279,18 +284,18 @@ rivine mcp logout notion   # forget it again
 
 This opens your browser, runs the standard OAuth loopback flow against the
 server's **own** authorization server, and stores the token in your OS
-keychain — never in `.rivine/mcp.json`, which is a file people commit. If a
+keychain, never in `.rivine/mcp.json`, which is a file people commit. If a
 server publishes no OAuth metadata the command says so rather than guessing at
 endpoints.
 
 ## In CI
 
 ```bash
-rivine --output-format json -m bypass -p "fix the failing type errors"
+rivine --output-format json -m fullstack --rate bypass -p "fix the failing type errors"
 ```
 
-In `json` mode **stdout carries exactly one object** and everything else —
-tokens, notices, command output — goes to stderr, so the stream stays safe to
+In `json` mode **stdout carries exactly one object** and everything else,
+tokens, notices, and command output, goes to stderr, so the stream stays safe to
 pipe into `jq`:
 
 ```json
@@ -298,7 +303,7 @@ pipe into `jq`:
 ```
 
 Exit codes are `0` success, `1` error, `2` out of credits (also if you run
-`rivine` with no prompt and no terminal), and `3` nothing could be done —
+`rivine` with no prompt and no terminal), and `3` nothing could be done:
 every operation needed approval and there was no terminal to give it. `3`
 exists because that run still costs a turn: without it the step would go
 green having changed nothing. The result object carries `refused` alongside
@@ -313,12 +318,14 @@ There is a composite action in `action.yml`:
     RIVINE_TOKEN: ${{ secrets.RIVINE_TOKEN }}
   with:
     prompt: fix the failing type errors
+    mode: fullstack
 ```
 
-`mode` defaults to `bypass` because a workflow has no terminal to approve
-anything on, and the headless renderer **refuses** rather than auto-approves —
-so any other mode stops at the first write. Run it on a checkout you are
-willing to have changed, and review the diff before merging.
+`rate` defaults to `bypass` because a workflow has no terminal to approve
+anything on, and the headless renderer **refuses** rather than auto-approves,
+so `manual` stops at the first write. `mode` is required: frontend, backend,
+fullstack, simple, or security. Run it on a checkout you are willing to have
+changed, and review the diff before merging.
 
 One turn has to finish inside the engine's **15-minute ceiling**. Local
 commands stream and are not the constraint; a single request that needs longer
@@ -327,19 +334,19 @@ than that is. Split the work across steps rather than raising the timeout.
 ## What the server stores
 
 File operations travel through a mailbox table so the engine and your terminal
-can hand work back and forth. Those rows carry real source — a write payload is
+can hand work back and forth. Those rows carry real source. A write payload is
 the file being written.
 
 Each session generates an **AES-256 key on your machine**. It is sent once per
 turn in the request body and held in memory for the length of that turn. It is
-never written to disk here and never written to storage there — so no database
+never written to disk here and never written to storage there, so no database
 we keep, and no backup, replica or restore of one, contains the material needed
 to open those rows. Rows are also deleted as soon as the engine has read them.
 
 **This is not end-to-end encryption, and we will not call it that.** The engine
 has to read your code to reason about it, so plaintext exists in server memory
 while a turn is running. What the session key removes is every path that goes
-through storage rather than through a live process — a restored snapshot, a
+through storage rather than through a live process: a restored snapshot, a
 backup bucket, a replica, a support query. That is the larger and longer-lived
 half of the exposure, not all of it.
 
@@ -366,10 +373,10 @@ deployments:
 |---|---|
 | `RIVINE_API_URL` | `https://workspace.beunec.com` |
 | `RIVINE_SITE_URL` | `https://aselius.beunec.com` |
-| `RIVINE_TOKEN` | unset — a pre-issued token for CI |
-| `RIVINE_NO_PTY` | unset — set to `1` to run commands without a PTY |
-| `RIVINE_ALLOW_OUTSIDE_PROJECT` | unset — set to `1` only if `bypass` should be allowed to leave the project directory |
-| `RIVINE_ASCII` | unset — set to `1` for ASCII glyphs (narrow panes, no Unicode) |
+| `RIVINE_TOKEN` | unset. A pre-issued token for CI |
+| `RIVINE_NO_PTY` | unset. Set to `1` to run commands without a PTY |
+| `RIVINE_ALLOW_OUTSIDE_PROJECT` | unset. Set to `1` only if `bypass` should be allowed to leave the project directory |
+| `RIVINE_ASCII` | unset. Set to `1` for ASCII glyphs (narrow panes, no Unicode) |
 
 Auth0 parameters are fetched from `GET /api/cli/config` at sign-in, so this
 package carries no tenant configuration and a client-id change never requires
@@ -388,8 +395,8 @@ reads ./src/app.ts
        ◀─── SSE tokens ────────  answer streams back
 ```
 
-The engine's file operations arrive as distinct verbs — `read`, `write`,
-`edit`, `execute` — rather than as shell commands. That is what lets this
+The engine's file operations arrive as distinct verbs, `read`, `write`,
+`edit`, and `execute`, rather than as shell commands. That is what lets this
 client tell a read from a write and apply the right policy, and it is why
 nothing here needs Python on your machine.
 
@@ -411,15 +418,15 @@ tokens faster than any terminal can usefully repaint:
 - Nothing is ever wider than your window. Paths truncate in the middle, keeping
   both ends; command output keeps its tail, because that is where the error is.
 - Colour degrades: TrueColor, 256, or 16, and `NO_COLOR` is honoured. Colour is
-  never the only signal — every line kind has its own glyph, so the transcript
+  never the only signal. Every line kind has its own glyph, so the transcript
   reads correctly in monochrome and for colour-blind readers. `RIVINE_ASCII=1`
   swaps the glyphs and wordmark for pure ASCII.
-- Exits restore the cursor and raw-mode state, including the abnormal ones — a
+- Exits restore the cursor and raw-mode state, including the abnormal ones: a
   kill, or an uncaught error. You should never need to run `reset`.
 
 ## Your identity
 
-The status bar shows your **cloudhandle** — the identity you recognise. Your
+The status bar shows your **cloudhandle**, the identity you recognise. Your
 account key is shown only as `••••••••••••` and the CLI never receives its
 value.
 
@@ -437,7 +444,7 @@ leak.
 - File reads are capped at 2 MB. Larger files are reported rather than
   truncated silently.
 - `ls`, `glob` and `grep` skip `node_modules`, `.git`, `dist`, `.next`,
-  `target`, `venv` and similar — for cost, not secrecy.
+  `target`, `venv` and similar, for cost, not secrecy.
 - Command output is capped at 120,000 characters, keeping the tail, because a
   failing build puts its error at the end.
 
@@ -453,11 +460,11 @@ npm run typecheck
 This package ships compiled JavaScript only; the TypeScript sources are not
 redistributed. For maintainers working in the repository, the interesting
 code is in `src/protocol/`: `permissions.ts` decides,
-`fsExecutor.ts` acts, `runner.ts` coordinates one turn. `src/ui/` only renders
-— nothing with a consequence lives there.
+`fsExecutor.ts` acts, `runner.ts` coordinates one turn. `src/ui/` only renders.
+Nothing with a consequence lives there.
 
 ---
 
-Rivine Code CLI — licensed and owned by **Beunec Technologies, Inc.**
+Rivine Code CLI, licensed and owned by **Beunec Technologies, Inc.**
 Proprietary software. Not open source. Use is governed by the licence
 agreement accompanying it.

package/dist/api/workspace.js

@@ -28,16 +28,26 @@ async function authHeaders() {
 export function projectKey(cwd) {
     return createHash('sha256').update(cwd).digest('hex').slice(0, 40);
 }
+export class OnboardingRequired extends Error {
+    url;
+    constructor(message, url) {
+        super(message);
+        this.url = url;
+        this.name = 'OnboardingRequired';
+    }
+}
 export async function bootstrap(cwd, label) {
     const url = new URL(`${apiUrl()}/api/cli/bootstrap`);
     url.searchParams.set('project_key', projectKey(cwd));
     url.searchParams.set('label', label);
     const res = await fetch(url, { headers: await authHeaders() });
     if (!res.ok) {
-        const detail = await res
-            .json()
-            .then((b) => String(b?.error ?? b?.detail ?? '').trim())
-            .catch(() => '');
+        const body = await res.json().catch(() => null);
+        const reason = body?.detail ?? body?.error;
+        if (res.status === 403 && reason && typeof reason === 'object' && reason.code === 'onboarding_required') {
+            throw new OnboardingRequired(String(reason.message || 'Finish setting up your Aselius account to use Rivine Code.'), String(reason.onboarding_url || 'https://aselius.beunec.com/onboarding'));
+        }
+        const detail = typeof reason === 'string' ? reason.trim() : '';
         if (res.status === 401) {
             throw new Error('Your session is no longer valid. Run `rivine login`.');
         }
@@ -120,12 +130,20 @@ export async function resumeTurn(args) {
             decision: args.approved ? 'approved' : 'rejected',
             feedback: args.feedback ?? '',
             modified_args: args.modifiedArgs ?? null,
+            code_mode: args.codeMode ?? null,
+            code_rate: args.codeRate ?? null,
             cli_session_key: args.sessionKey ?? null,
             cli_session_id: args.sessionId,
         }),
     });
     if (!res.ok) {
-        throw new Error(`Could not resume the turn (HTTP ${res.status}).`);
+        const detail = await res
+            .json()
+            .then((b) => String(b?.detail ?? b?.error ?? '').trim())
+            .catch(() => '');
+        throw new Error(detail
+            ? `Could not resume the turn (HTTP ${res.status}): ${detail}`
+            : `Could not resume the turn (HTTP ${res.status}).`);
     }
     return (await res.json());
 }
@@ -139,6 +157,24 @@ export async function closeSession(sessionId) {
     catch {
     }
 }
+export async function getTurnStatus(workspaceId, chatSpaceId) {
+    const res = await fetch(`${apiUrl()}/api/workspaces/${workspaceId}/chats/${chatSpaceId}/turn-status`, {
+        headers: await authHeaders(),
+    });
+    if (!res.ok)
+        throw new Error(`turn-status returned ${res.status}`);
+    return (await res.json());
+}
+export async function cancelTurn(workspaceId, chatSpaceId) {
+    try {
+        await fetch(`${apiUrl()}/api/workspaces/${workspaceId}/chats/${chatSpaceId}/turns/cancel`, {
+            method: 'POST',
+            headers: await authHeaders(),
+        });
+    }
+    catch {
+    }
+}
 export async function fetchCredits(creditsUrl) {
     if (!creditsUrl)
         return null;

package/dist/index.js

@@ -10,6 +10,7 @@
  * redistribution or derivative works.
  */
 import { readFileSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { render } from 'ink';
@@ -18,6 +19,7 @@ import { Command } from 'commander';
 import { App } from './ui/App.js';
 import { runHeadless } from './runHeadless.js';
 import { isInteractiveTerminal, installTeardown } from './ui/headless.js';
+import { emitNotice } from './ui/notices.js';
 import { login, logout, status } from './auth/session.js';
 import { openBrowser } from './auth/pkce.js';
 import { apiUrl, siteUrl } from './config.js';
@@ -262,14 +264,15 @@ function collect(value, previous) {
 program
     .argument('[prompt...]', 'send one prompt and exit')
     .option('-p, --print <prompt>', 'send one prompt, print the answer, and exit')
-    .option('-m, --mode <mode>', `which agent runs: ${CODE_MODES.join(' | ')}`)
+    .option('-m, --mode <mode>', `what Rivine Code works on: ${CODE_MODES.join(' | ')}`)
     .option('--rate <rate>', `how edits apply: ${RATES.join(' | ')}`)
     .option('--plan', 'shorthand for --mode simple (Plan/Ask Only)')
     .option('--bypass', 'never ask for approval — for CI only, on a machine you are willing to have changed')
     .option('-C, --cwd <dir>', 'run against a different directory')
     .option('--output-format <format>', 'text | json — json puts one object on stdout and everything else on stderr', 'text')
     .action(async (prompt, options) => {
-    const cwd = options.cwd ? resolvePath(options.cwd) : process.cwd();
+    const requested = options.cwd ? resolvePath(options.cwd) : process.cwd();
+    const cwd = await realpath(requested).catch(() => requested);
     const oneShot = options.print ?? (prompt.length ? prompt.join(' ') : undefined);
     const { mode, explicit: modeExplicit } = resolveMode(options);
     const codeMode = resolveCodeMode(options);
@@ -298,19 +301,29 @@ program
         return;
     }
     if (format === 'json' && oneShot) {
-        process.exitCode = await runHeadless({
-            cwd, mode, codeMode: codeMode ?? 'fullstack', prompt: oneShot, format,
-        });
+        if (!codeMode) {
+            console.error('\n  --mode is required with --output-format json.\n' +
+                `  Choose one of: ${CODE_MODES.join(', ')}\n` +
+                '  e.g. rivine -m backend --output-format json -p "add tests for auth.ts"\n');
+            process.exitCode = 2;
+            return;
+        }
+        process.exitCode = await runHeadless({ cwd, mode, codeMode, prompt: oneShot, format });
         return;
     }
     const { waitUntilExit } = render(React.createElement(App, {
         cwd,
         initialMode: mode,
         askForMode: !modeExplicit && !oneShot,
-        initialCodeMode: codeMode ?? (oneShot ? 'fullstack' : undefined),
+        initialCodeMode: codeMode ?? undefined,
         oneShot,
     }), { exitOnCtrlC: false });
-    const removeTeardown = installTeardown(() => { });
+    const removeTeardown = installTeardown(() => { }, {
+        onRejection: (err) => {
+            const message = err?.message ?? String(err);
+            emitNotice(`Background task failed: ${message}`);
+        },
+    });
     try {
         await waitUntilExit();
     }

package/dist/protocol/permissions.js

@@ -47,7 +47,6 @@ export function parseCodeMode(raw) {
     return table[key] ?? null;
 }
 export const PERMISSION_MODES = ['plan', 'default', 'acceptEdits', 'bypass'];
-export const CYCLE_MODES = ['plan', 'default', 'acceptEdits'];
 export function isBatchable(category) {
     return category === 'write' || category === 'mcp';
 }
@@ -251,9 +250,6 @@ export function nextMode(current) {
         ? rateToPermissionMode('manual')
         : rateToPermissionMode('bypass');
 }
-export function nextRate(current) {
-    return current === 'bypass' ? 'manual' : 'bypass';
-}
 export function modeName(mode) {
     switch (mode) {
         case 'plan':