@illuminis/comprism 0.1.3 → 0.1.5

package/README.md

@@ -6,23 +6,81 @@ cost, and changes nothing about what your tool does.
 
 ## Install
 
+Three ways, one tool. Pick the one that suits the machine; each gives you the
+same `comprism` command, sign in and settings.
+
+| Option | Pick it when | Install |
+| --- | --- | --- |
+| 1. Install script (recommended) | Nothing needs to be on the machine first: no Node, no Python | `curl -fsSL https://yourco.completionprism.com/install.sh \| sh` |
+| 2. npm | You already use Node 22 or newer | `npm install -g @illuminis/comprism` |
+| 3. Python | You have Python 3.9 or newer and no Node | `pip install comprism-cli` (or `pipx install comprism-cli`) |
+
+On Windows, the install script is one line in PowerShell:
+`irm https://yourco.completionprism.com/install.ps1 | iex`. The address is your
+own workspace, the one you sign in to. A company that allows only its own
+package sources installs the Python option from the workspace:
+`pip install --index-url https://yourco.completionprism.com/pypi/simple/ comprism-cli`.
+
+Then sign in:
+
 ```bash
-npm install -g @illuminis/comprism
 comprism login
 ```
 
 That is the whole install. It configures itself, including the one line it adds
 to your shell profile, and it says what it touched. npm hides that message by
 default, so add `--foreground-scripts` to the install if you want to read it.
+A Python install finishes its setup on the first `comprism login`.
 
 No API key to export. The keys live in your workspace, and every decision is
 made on our servers.
 
+Sign in from an interactive terminal. `comprism login` and its `connect` alias
+exit with status 1 when input is piped or redirected, before asking for credentials
+or contacting the service. Sign in first, then run commands from your script.
+
 ```bash
+comprism status         # which account and company this machine is signed in to
 comprism check          # what this machine still needs, and how to add it
+comprism install        # redo the shell setup, if the install could not
+comprism cost           # what a session cost, and which factors drove it
 comprism uninstall      # takes the line back out
 ```
 
+`comprism check` exits with status 1 while setup is unfinished, so a script can
+test for it. `comprism --version` prints the installed version. `comprism
+update` installs a newer version the same way this one was installed; your sign
+in and the single profile line are kept.
+
+`comprism uninstall` removes the profile line, the generated shell script and
+any old Claude Desktop entry of ours; for an install script install it also
+removes the program. It leaves your sign in and settings in `~/.comprism` and
+says so. Run `comprism logout` first to revoke this machine's key. Then remove
+the tool the way it was installed: nothing more for the install script,
+`npm uninstall -g @illuminis/comprism` for npm, `pip uninstall comprism-cli`
+for Python. Delete `~/.comprism` to remove every trace.
+
+Automatic shell setup covers zsh and bash on macOS and Linux, and PowerShell on
+Windows. The Windows install script also puts the tool on your user PATH, so
+Command Prompt finds it too.
+
+## Where the money went
+
+`comprism cost` breaks down a session without leaving the terminal: what it
+cost, what it would have cost, and the five factors behind the difference, then
+every provider call with its tokens, its price and the decision that chose that
+model.
+
+```bash
+comprism cost                       # the newest session this workspace recorded
+comprism cost srv_69e322469de33b90  # a particular one
+cost                                # inside a session, meaning this one
+```
+
+The figures come from the same service the portal reads, so the two can never
+quote different numbers for one piece of work. A factor nothing measured prints
+blank, never zero: a zero in a cost column reads as a measurement.
+
 ## The coding agent
 
 `comprism work` reads your project, changes files, runs commands, runs your
@@ -124,7 +182,8 @@ reach depends on the keys on your account.
 
 ### Requirements
 
-Node 22 or newer, and a workspace you have signed in to with `comprism login`.
+A workspace you have signed in to with `comprism login`. Node 22 or newer for
+the npm option only; the install script and Python options carry their own.
 
 ---
 

package/out/agent/command.d.ts

@@ -1,6 +1,21 @@
 import { type JobResult } from "./session";
+import { type OutputChoice } from "../lib/output";
 export interface AgentArgs {
     request: string[];
+    /** Inside a session: background processes outlive this job and are stopped
+     *  when the session ends (manual 5.13). */
+    keepProcesses?: boolean;
+    /** Seconds each command may run before it is stopped (manual 5.12). */
+    timeout?: number;
+    /** Start from this GitHub issue (manual 5.20). */
+    issue?: number;
+    /** Lead the team defined under this name (manual 5.27). */
+    team?: string;
+    /** A review, not a request: the instruction is the service's (manual 5.19). */
+    review?: {
+        pr?: number;
+        post?: boolean;
+    };
     /** Start it and hand the terminal back. See `runDetached` for what this can
      *  and cannot do. */
     background?: boolean;
@@ -14,6 +29,14 @@ export interface AgentArgs {
     /** Run `model` and nothing else, whatever the router would prefer. */
     pin?: boolean;
     maxSpend?: number;
+    /** Stop after this many steps (manual 4.13). */
+    maxSteps?: number;
+    /** No new step after this many minutes (manual 10.7). */
+    maxMinutes?: number;
+    /** Reasoning effort: low, medium or high (manual 4.18). */
+    effort?: string;
+    /** Run commands in the operating system's sandbox (manual 4.12). */
+    sandbox?: boolean;
     /** `--allow "python3 grade.py"`, repeatable. Exact commands, pre approved. */
     allow?: string[];
     yes?: boolean;
@@ -31,7 +54,13 @@ export interface AgentArgs {
      *  already said. Not the same as `resume`, which re-enters a job that stopped
      *  part way; this is the ordinary next question in a conversation. */
     continuesJob?: string;
+    /** Which conversation this job belongs to, so the server files it under the
+     *  session the person is actually in rather than under their whole day. */
+    conversationId?: string;
     cwd?: string;
+    /** Other folders the person named with `--add-folder` or `folders add`
+     *  (manual 2.3). Nothing else ever becomes an allowed folder. */
+    addFolders?: string[];
     /**
      * Ask the person a yes or no question.
      *
@@ -44,6 +73,9 @@ export interface AgentArgs {
      * what the standalone command wants.
      */
     confirm?: (question: string) => Promise<boolean>;
+    /** A line of text from the same lent keyboard, for the plan question and the
+     *  agent's questions. Null means Ctrl+C. */
+    prompt?: (question: string) => Promise<string | null>;
     /**
      * Files already uploaded, to be put in front of this question.
      *
@@ -52,6 +84,12 @@ export interface AgentArgs {
      * here would be sending them twice and storing them nowhere useful.
      */
     attachments?: string[];
+    /** Names of files the person named that could not be attached, so the
+     *  agent is told rather than left to guess (manual 3.10). */
+    leftOut?: string[];
+    /** The terminal to ask approval questions at when standard input is a
+     *  pipe (manual 3.9). Never the pipe itself. */
+    keyboard?: NodeJS.ReadableStream | null;
     /**
      * Handed a way to stop the job, as soon as there is one to stop.
      *
@@ -65,10 +103,21 @@ export interface AgentArgs {
      *  to it while it runs. A caller that owns the keyboard needs both, because
      *  a person watching a job go the wrong way at step three should be able to
      *  correct it rather than stop it and start again. */
-    onStarted?: (controls: {
-        cancel: () => void;
-        steer: (text: string) => void;
-    }) => void;
+    onStarted?: (controls: JobControls) => void;
+    /** `--output` and `--quiet`, and whether standard output is a terminal
+     *  (manual 10.2, 10.3). Absent inside a session, which always draws. */
+    output?: OutputChoice;
+    /** `--schema`: the answer must be JSON of this shape (manual 10.5). */
+    answerSchema?: Record<string, unknown>;
+    /** A queued job this runner claimed (10.17 to 10.19); the service holds
+     *  its request, mode and limits. */
+    queuedJob?: string;
+    /** `--config`: settings read as if they were the project file (10.8). */
+    settingsConfig?: Record<string, unknown>;
+    /** `--no-personal`: leave out personal settings and instructions (10.8). */
+    noPersonal?: boolean;
+    /** Start in the full view (manual 6.9), because Ctrl+O was pressed earlier. */
+    fullView?: boolean;
     /**
      * Told what the job cost, once it has finished.
      *
@@ -81,6 +130,28 @@ export interface AgentArgs {
      */
     onFinished?: (result: JobResult) => void;
 }
+export declare const MODES: string[];
+/** What a caller holding the keyboard can do to a running job (manual 6.7 to
+ *  6.9). Every one of them is a message to the service, which decides. */
+export interface JobControls {
+    cancel: () => void;
+    steer: (text: string) => void;
+    pause: () => void;
+    carryOn: (text: string) => void;
+    isPaused: () => boolean;
+    queue: (clear: boolean) => void;
+    setFull: (on: boolean) => void;
+    /** Helpers running now, as the service reported them (manual 5.25). */
+    helpers: () => Array<{
+        id: string;
+        question: string;
+        agent?: string | null;
+    }>;
+    /** `stop h2`: the service stops that helper, the rest carry on. */
+    stopHelper: (id: string) => void;
+    /** The job's id, once the service has issued it. */
+    jobId: () => string | undefined;
+}
 export declare function runAgent(args: AgentArgs): Promise<number>;
 /** The help text. Written to be read by somebody who has not read anything else. */
 export declare const AGENT_HELP: string;

package/out/agent/command.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_HELP = void 0;
+exports.AGENT_HELP = exports.MODES = void 0;
 exports.runAgent = runAgent;
 /**
  * `comprism work` — the coding agent, from a terminal.
@@ -56,8 +56,11 @@ exports.runAgent = runAgent;
 const fs = __importStar(require("fs"));
 const readline = __importStar(require("readline"));
 const connection_1 = require("../lib/connection");
+const project_1 = require("../lib/project");
 const session_1 = require("./session");
 const ui = __importStar(require("./render"));
+const output_1 = require("../lib/output");
+const self_1 = require("../lib/self");
 /** The WebSocket the session needs is a global from Node 22.
  *
  *  Checked here with a message somebody can act on. Without it the failure is
@@ -70,7 +73,7 @@ function requireWebSocket() {
         ui.dim(`  You are on ${process.version}. Upgrade Node and try again.\n`));
     return false;
 }
-const MODES = ["read_only", "approve_writes", "auto_edit", "full_auto"];
+exports.MODES = ["read_only", "approve_writes", "auto_edit", "full_auto"];
 /**
  * Start a job, hand the terminal back, and keep working.
  *
@@ -105,28 +108,83 @@ async function runDetached(args) {
     const log = fs.openSync(logPath, "a");
     // Detached, with its own process group, so closing the terminal does not take
     // the job with it. `unref` is what actually lets this process exit.
-    const child = spawn(process.execPath, [
-        process.argv[1] ?? "", "agent",
+    const child = spawn(...(0, self_1.selfLaunch)([
+        "agent",
         ...args.request,
         "--mode", mode, "--yes",
         ...(args.model ? ["--model", args.model] : []),
         ...(args.pin ? ["--pin"] : []),
         ...(args.maxSpend ? ["--max-spend", String(args.maxSpend)] : []),
+        ...(args.timeout ? ["--timeout", String(args.timeout)] : []),
         ...(args.allow ?? []).flatMap((c) => ["--allow", c]),
         ...(args.cwd ? ["--cwd", args.cwd] : []),
-    ], { detached: true, stdio: ["ignore", log, log], env: { ...process.env, NO_COLOR: "1" } });
+        ...(args.addFolders ?? []).flatMap((f) => ["--add-folder", f]),
+    ]), {
+        detached: true, stdio: ["ignore", log, log],
+        // Marked, so the job is recorded as a background job and its log can be
+        // found again by `comprism jobs attach` (manual 5.14).
+        env: { ...process.env, NO_COLOR: "1", COMPRISM_BACKGROUND: "1", COMPRISM_JOB_LOG: logPath },
+    });
     child.unref();
     process.stdout.write(ui.green(`  Started in the background as process ${child.pid}.\n`)
+        + ui.dim("  comprism jobs lists it; comprism jobs attach <job> watches it.\n")
         + ui.dim(`  Follow it:  tail -f ${logPath}\n`)
         + ui.dim("  It keeps working while you do something else. This machine has "
             + "to stay awake: the files are here, so the work is too.\n"));
     return 0;
 }
 async function runAgent(args) {
+    const output = args.output;
+    const json = output?.format === "json";
+    const streaming = output?.format === "stream";
+    // A stream is lines the service built, printed as they come (manual 10.4).
+    // If the program reading it goes away, the job is stopped and the exit is
+    // 141, with nothing said about it.
+    let pipeClosed = false;
+    let finishedLine = false;
+    let stopJob = null;
+    const emit = (items) => {
+        for (const item of items) {
+            if (pipeClosed)
+                return;
+            if (item.event === "job_finished")
+                finishedLine = true;
+            process.stdout.write(JSON.stringify(item) + "\n");
+        }
+    };
+    if (streaming) {
+        process.stdout.on("error", (e) => {
+            if (e.code !== "EPIPE")
+                return;
+            pipeClosed = true;
+            stopJob?.();
+        });
+    }
+    /** An ending the service never saw: its number, and with --output json the
+     *  result object in its published shape (manual 10.3, Appendix B). */
+    const ended = (reason, why) => {
+        if (json)
+            (0, output_1.printJson)((0, output_1.localResult)(reason, why));
+        if (streaming)
+            emit([{ event: "job_finished", ...(0, output_1.localResult)(reason, why) }]);
+        return (0, output_1.exitFor)(reason);
+    };
+    // A folder that does not exist is refused before anything runs or is charged
+    // (manual 2.1, exit 2 in Appendix B).
+    const folders = [];
+    for (const raw of [args.cwd ?? process.cwd(), ...(args.addFolders ?? [])]) {
+        const found = (0, project_1.checkFolder)(raw);
+        if (!found.ok) {
+            process.stderr.write(ui.red(`  ${found.why}`) + ui.dim("  Nothing ran and nothing was charged.\n"));
+            return 2;
+        }
+        folders.push(found.path);
+    }
+    const [startFolder, ...added] = folders;
     if (!requireWebSocket())
         return 1;
     if (args.background)
-        return runDetached(args);
+        return runDetached({ ...args, cwd: startFolder, addFolders: added });
     const connection = (0, connection_1.readConnection)();
     if (!connection?.url) {
         process.stderr.write(
@@ -135,7 +193,7 @@ async function runAgent(args) {
         // brand new user is given was a dead end.
         ui.red("  Not signed in.") +
             ui.dim("  Run `comprism login` first.\n"));
-        return 1;
+        return ended("signed_out", "Not signed in. Run comprism login first.");
     }
     // The machine credential, not the session token. The session token belongs to
     // a browser sign-in and is short lived; this is the long-lived credential
@@ -146,14 +204,28 @@ async function runAgent(args) {
     if (!credential) {
         process.stderr.write(ui.red("  This machine has no workspace key.") +
             ui.dim("  Run `comprism connect` again to mint one.\n"));
-        return 1;
+        return ended("signed_out", "This machine has no workspace key. Run comprism connect again.");
     }
-    const root = fs.realpathSync(args.cwd ?? process.cwd());
-    const mode = args.mode ?? "approve_writes";
-    if (!MODES.includes(mode)) {
+    const project = (0, project_1.resolveProject)(startFolder, added);
+    const root = project.root;
+    // Absent means the settings decide (manual 2.10): the service resolves the
+    // mode from the local and project settings files and your account.
+    const mode = args.mode;
+    if (mode !== undefined && !exports.MODES.includes(mode)) {
         process.stderr.write(ui.red(`  ${mode} is not a permission mode.`) +
-            ui.dim(`  One of: ${MODES.join(", ")}\n`));
-        return 1;
+            ui.dim(`  One of: ${exports.MODES.join(", ")}\n`));
+        return ended("usage", `${mode} is not a permission mode.`);
+    }
+    // `--sandbox` never runs without one (manual 4.12): refused before anything
+    // runs or is charged.
+    if (args.sandbox) {
+        const { availability } = await Promise.resolve().then(() => __importStar(require("../executor/sandbox")));
+        const found = availability();
+        if (!found.system) {
+            process.stderr.write(ui.red(`  --sandbox cannot start: ${found.why}.`)
+                + ui.dim("  Nothing ran and nothing was charged.\n"));
+            return 1;
+        }
     }
     const request = args.request.join(" ").trim();
     if (!request && !args.resume) {
@@ -163,33 +235,99 @@ async function runAgent(args) {
     // Headless when asked for, and also when there is no terminal at all: piped
     // into a script, nobody is there to answer an approval, and pretending
     // otherwise would hang the pipeline until it timed out.
-    const headless = Boolean(args.yes) || !process.stdin.isTTY;
+    //
+    // Standard input that is a pipe is material, never answers (manual 3.9):
+    // questions then go to the terminal the caller opened, and with none the
+    // job is unattended.
+    const questions = process.stdin.isTTY
+        ? process.stdin : args.keyboard ?? null;
+    const headless = Boolean(args.yes) || !questions;
+    // ONE reader for the whole job when nobody lent a keyboard: it carries what
+    // is typed while the agent works, and it answers questions and approvals.
+    // Two readers on one keyboard divide the typing, so an answer also arrived
+    // as a correction to the job.
+    let steering = null;
+    let waiting = null;
+    const ownPrompt = (question) => new Promise((resolve) => {
+        process.stdout.write(`  ${question} `);
+        waiting = resolve;
+    });
+    const lent = args.confirm || headless ? {} : {
+        prompt: ownPrompt,
+        confirm: async (question) => /^y(es)?$/i.test(((await ownPrompt(question)) ?? "").trim()),
+    };
+    // With standard output going to a script, everything the job says on the
+    // way goes to standard error, and only the result goes to standard output
+    // (manual 10.2). `--quiet` drops the progress altogether.
+    const toErr = output ? (0, output_1.progressToErr)(output) : false;
+    const write = output?.quiet || streaming ? () => undefined
+        : toErr ? (s) => { process.stderr.write(s); } : (s) => { process.stdout.write(s); };
     const session = new session_1.TerminalSession({
         baseUrl: connection.url,
         credential,
         root,
+        project,
         permissionMode: mode,
         planOnly: Boolean(args.plan),
         planApproved: Boolean(args.approvePlan),
         model: args.model,
         pinModel: Boolean(args.pin),
         maxSpendUsd: args.maxSpend,
+        maxSteps: args.maxSteps,
+        maxMinutes: args.maxMinutes,
+        effort: args.effort,
+        sandbox: Boolean(args.sandbox),
+        commandTimeoutS: args.timeout,
+        issue: args.issue,
+        team: args.team,
+        review: args.review,
+        keepProcesses: Boolean(args.keepProcesses),
         approvedCommands: args.allow ?? [],
         attachmentIds: args.attachments ?? [],
+        leftOut: args.leftOut ?? [],
         headless,
         confirm: args.confirm,
+        prompt: args.prompt,
+        ...lent,
         resumeJobId: args.resume,
         continuesJob: args.continuesJob,
+        conversationId: args.conversationId,
         withoutMap: Boolean(args.noMap),
-    });
+        ...(args.answerSchema ? { answerSchema: args.answerSchema } : {}),
+        ...(args.queuedJob ? { queuedJob: args.queuedJob } : {}),
+        ...(args.settingsConfig ? { settingsConfig: args.settingsConfig } : {}),
+        noPersonal: Boolean(args.noPersonal),
+        ...(streaming ? { onStream: emit } : {}),
+    }, write);
+    stopJob = () => session.cancel();
     // Ctrl+C stops the JOB, not the process. Killing the process would leave the
     // job running on the server with nothing watching it, and whatever the agent
     // had started on this machine would carry on unsupervised.
-    const onInterrupt = () => session.cancel();
+    let interrupted = false;
+    const onInterrupt = () => {
+        interrupted = true;
+        // Ctrl+C at a question answers it as stopped, then stops the job.
+        const w = waiting;
+        waiting = null;
+        if (w) {
+            process.stdout.write("\n");
+            w(null);
+        }
+        session.cancel();
+    };
     process.on("SIGINT", onInterrupt);
+    session.full = Boolean(args.fullView);
     args.onStarted?.({
         cancel: () => session.cancel(),
         steer: (text) => session.steer(text),
+        pause: () => session.pause(),
+        carryOn: (text) => session.carryOn(text),
+        isPaused: () => session.paused,
+        queue: (clear) => session.queue(clear),
+        setFull: (on) => { session.full = on; },
+        jobId: () => session.jobId,
+        helpers: () => [...session.helpers.values()],
+        stopHelper: (id) => session.stopHelper(id),
     });
     // Anything typed while it works. Not a prompt, deliberately: the run is
     // printing, and a prompt competing with it for the same lines is unreadable.
@@ -198,10 +336,15 @@ async function runAgent(args) {
     // `confirm` is that one component owns the terminal; opening a reader here as
     // well would put the same two owners back on it by another door, and the
     // caller is the one already reading what gets typed.
-    let steering = null;
     if (!headless && !args.confirm) {
-        steering = readline.createInterface({ input: process.stdin, terminal: false });
+        steering = readline.createInterface({ input: questions, terminal: false });
         steering.on("line", (line) => {
+            const w = waiting;
+            if (w) {
+                waiting = null;
+                w(line);
+                return;
+            }
             const text = line.trim();
             if (text)
                 session.steer(text);
@@ -210,14 +353,54 @@ async function runAgent(args) {
     try {
         const result = await session.run(request);
         args.onFinished?.(result);
-        // A shell needs to know whether it worked. Anything other than finishing
-        // cleanly is a non-zero exit, so `comprism work ... && next-thing` behaves
-        // the way a person expects.
-        return result.outcome === "finished" ? 0 : 1;
+        // A job on its own is its session, and it has ended (manual 7.3).
+        if (!args.keepProcesses && args.conversationId) {
+            const { review } = await Promise.resolve().then(() => __importStar(require("../commands/review")));
+            await review("session_ended", { session_id: args.conversationId }).catch(() => undefined);
+        }
+        // How it ended is the service's reason word; the number comes from the
+        // table the service sent with it (manual 10.6, Appendix B). The only
+        // endings decided here are the ones the service could not see: a dropped
+        // connection with an action in doubt (8.9), Ctrl+C, and never reaching it.
+        const reason = result.outcome === "unknown" ? "unknown"
+            : interrupted ? "interrupted"
+                : result.ending?.reason ?? result.refusalReason
+                    ?? (result.outcome === "finished" ? "done" : "incomplete");
+        if (pipeClosed)
+            return (0, output_1.exitFor)("output_closed", result.exitStatus);
+        const code = (0, output_1.exitFor)(reason, result.exitStatus);
+        if (streaming) {
+            // A job refused before it started has sent no stream, so its end is
+            // the service's result for the refusal.
+            if (!finishedLine) {
+                emit([{ event: "job_finished", ...(result.result ?? (0, output_1.localResult)(reason, result.detail ?? reason)) }]);
+            }
+            if (code !== 0)
+                process.stderr.write(`  ${result.ending?.line ?? result.detail ?? reason}\n`);
+        }
+        else if (json) {
+            (0, output_1.printJson)(result.result && reason !== "unknown" && !interrupted
+                ? result.result : (0, output_1.localResult)(reason, result.detail ?? reason));
+        }
+        else if (toErr) {
+            // The final summary, and nothing else, on standard output (10.2).
+            const summary = result.ending?.line ?? result.detail ?? "";
+            if (summary)
+                process.stdout.write(`${summary}\n`);
+            if (result.text.trim() && result.text.trim() !== summary)
+                process.stdout.write(`${result.text.trim()}\n`);
+        }
+        if (code !== 0 && output?.quiet) {
+            // A number other than 0 comes with a one line reason on standard error.
+            process.stderr.write(`  ${result.ending?.line ?? result.detail ?? reason}\n`);
+        }
+        return code;
     }
     catch (err) {
+        // The live connection never opened: the service could not be reached
+        // (manual 10.14, exit 6).
         process.stderr.write(ui.red(`  ${err.message}\n`));
-        return 1;
+        return ended("unreachable", err.message);
     }
     finally {
         process.off("SIGINT", onInterrupt);
@@ -231,26 +414,38 @@ ${ui.bold("comprism work")} — a coding agent in your terminal
   comprism work "add a test for the parser and make it pass"
 
 ${ui.bold("What it does")}
-  Reads your project, changes files, runs commands and runs your tests, and
-  shows you every change before it makes it. Each step is routed to whichever
+  Reads your project, changes files, runs commands and runs your tests. It
+  shows you every change as it makes it, asks before deleting a file or
+  running a command, and can undo the whole job. Each step is routed to whichever
   model finishes the work for least, and the receipt at the end says what it
   cost.
 
 ${ui.bold("Options")}
   --mode <mode>      read_only, approve_writes (default), auto_edit, full_auto
+  --worktree <name>  work in a separate copy of the repository on its own branch
   --plan             work out what it would do and change nothing
   --approve-plan     you read the plan and want it built. Files change without
                      being asked about one at a time; commands still ask
   --model <id>       tell it which model you are running, so the receipt can
                      price the saving against it. It may still move you up
-  --pin              run --model and nothing else, whatever it would prefer
+  --no-optimize      Optimize off: run --model and nothing else (also --pin)
   --max-spend <usd>  stop at this much rather than running on
+  --max-steps <n>    stop after this many steps
+  --max-minutes <n>  start no new step after this many minutes
+  --effort <level>   low, medium or high: how carefully the model thinks
+  --sandbox          run commands in the operating system's sandbox
+  --timeout <secs>   time limit for each command, two minutes unless set
+  --issue <n>        start from GitHub issue n; its text is information only
+  --team <name>      lead the team defined in .completionprism/teams/<name>.md
   --allow "<cmd>"    approve one exact command up front, repeatable. The only
                      way an unattended run can verify its own work
   --yes              never ask; anything needing approval is refused instead
   --background       start it and get your terminal back; it keeps working
   --resume <job>     carry on from a job you already started
   --cwd <path>       work in this folder rather than the current one
+  --cloud            run it on a CompletionPrism worker with a copy of the
+                     repository; comprism --resume <session> brings it back
+  --add-folder <path>  also allow this folder, repeatable
   --no-map           do not use the code map for this job; read the files
 
 ${ui.bold("While it runs")}