@illuminis/comprism 0.1.3 → 0.1.5

package/out/thin.js

@@ -56,7 +56,46 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const ui = __importStar(require("./lib/ui"));
 const version_1 = require("./lib/version");
+const self_1 = require("./lib/self");
 const out = (s = '') => process.stdout.write(s + '\n');
+/** A refusal a script reads: always on standard error (Appendix B). */
+const err = (s = '') => process.stderr.write(s + '\n');
+/**
+ * Piped text, attached as `standard input`, and the terminal to ask approval
+ * questions at (manual 3.9). The attachment line goes to standard error when
+ * standard output is not a terminal, so a script reads only the result.
+ * Null when the text was piped and could not be attached: the request is not
+ * sent without the material it was about.
+ */
+async function attachStdin(piped) {
+    const { attachPiped, openTerminal } = await Promise.resolve().then(() => __importStar(require('./lib/stdin')));
+    const keyboard = process.stdin.isTTY ? null : openTerminal();
+    if (!piped?.trim())
+        return { ids: [], keyboard };
+    const say = process.stdout.isTTY ? out : err;
+    const { readConnection } = await Promise.resolve().then(() => __importStar(require('./lib/connection')));
+    const conn = readConnection();
+    if (!conn?.url || !conn.workspaceKey)
+        return { ids: [], keyboard };
+    const attach = await Promise.resolve().then(() => __importStar(require('./lib/attach')));
+    const { attached, refused } = await attachPiped(piped, conn.url, conn.workspaceKey);
+    for (const line of attach.describe(attached))
+        say(ui.c.dim(`  ${line}`));
+    for (const r of refused)
+        err(ui.c.amber(`  ${r.why}`));
+    if (refused.length > 0) {
+        keyboard?.destroy();
+        err(ui.c.dim('  Nothing was sent.'));
+        return null;
+    }
+    return { ids: attached.map((a) => a.id), keyboard };
+}
+/** Flags `work` takes with a value, and flags it takes on their own. */
+const WORK_VALUES = ['--mode', '--model', '--max-spend', '--max-steps', '--effort', '--resume',
+    '--cwd', '--allow', '--add-folder', '--timeout', '--issue', '--team', '--output', '--worktree',
+    '--schema', '--config', '--max-minutes', '--queued'];
+const WORK_SWITCHES = ['--plan', '--approve-plan', '--pin', '--no-optimize', '--sandbox', '--yes', '--background',
+    '--no-map', '--no-graph', '--quiet', '--no-personal', '--cloud'];
 /**
  * The value after a flag, or undefined when the flag was not given.
  *
@@ -79,25 +118,296 @@ function usage() {
         ['comprism work', 'have it do the work: reads your project, edits, runs your tests'],
         ['comprism login', 'sign in with your email and password'],
         ['comprism', 'start a session and just type your questions'],
+        ['comprism --continue', 'carry on the most recent session in this project'],
+        ['comprism --resume [number]', 'carry on a session; with no number, choose from a list'],
+        ['comprism sessions', 'your recent sessions, newest first; --search to find one'],
         ['comprism keys', 'add a provider key, or point at a file of them'],
         ['comprism model', 'the model your savings are measured against'],
         ['comprism providers', 'every AI vendor and model, and what you can reach'],
-        ['comprism workspace', 'the folder to work in, default is where you are'],
+        ['comprism project', 'the folder to work in, default is where you are'],
+        ['comprism config', 'settings in force and where each came from'],
+        ['comprism instructions', 'the instructions the next job receives'],
+        ['comprism memory', 'this project\'s notes'],
+        ['comprism skills', 'the skills here and where each came from; /name runs one'],
+        ['comprism integrations', 'outside tools the agent can call, and their sign in'],
+        ['comprism plugins', 'packs of skills, helpers, hooks and connections'],
+        ['comprism worktrees', 'separate copies of the repository'],
+        ['comprism privacy', 'what your company keeps about your work'],
+        ['comprism permissions', 'the rules in force here; permissions why <action> "<target>"'],
         ['comprism status', 'is this machine signed in, and to what'],
         ['comprism check', 'what this machine still needs, and how to add it'],
         ['comprism logout', 'sign out, and revoke this machine\'s key'],
-        ['comprism uninstall', 'undo the setup this machine got at install'],
+        ['comprism cost', 'what a session cost, and which factors drove it'],
+        ['comprism schema output', 'the shape of --output json, for scripts'],
+        ['comprism usage', 'your coding allowance left this month, and provider limits'],
+        ['comprism hooks', 'the hooks in force here; hooks test <when> <action> <file> runs them'],
+        ['comprism update', 'check for a newer version and install it; --check only says'],
+        ['comprism changes', 'what the agent changed in a job, apart from your own changes'],
+        ['comprism diff', 'the agent\'s changes, line by line'],
+        ['comprism rewind <job>', 'put the files back; --to-step N or one file'],
+        ['comprism schedule', 'requests that run by themselves; schedule add "<when>" "<request>"'],
+        ['comprism triggers', 'outside events that start a job; triggers add "<request>"'],
+        ['comprism worker', 'run the jobs queued for this machine, or --cloud for any worker'],
+        ['comprism install', 'set up this machine again, if the install could not'],
+        ['comprism uninstall', 'remove comprism from this machine, everything it set up included'],
     ]));
     out();
     out(ui.c.dim(`  v${version_1.COMPRISM_VERSION} · every decision is made on our servers`));
     out();
 }
+/**
+ * Behind a company proxy (manual 1.11): Node uses HTTPS_PROXY and NO_PROXY for
+ * its own requests only when NODE_USE_ENV_PROXY is set as it starts, so the
+ * tool starts itself once more with it set. Nothing changes without a proxy.
+ */
+function throughProxy() {
+    const proxy = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
+    if (!proxy || process.env.NODE_USE_ENV_PROXY)
+        return false;
+    const { spawnSync } = require('child_process');
+    // Node 22 calls its proxy support experimental and says so on every start;
+    // that one notice is not the person's concern.
+    const [cmd, argv] = (0, self_1.selfLaunch)(process.argv.slice(2), ['--disable-warning=UNDICI-EHPA']);
+    const r = spawnSync(cmd, argv, {
+        stdio: 'inherit', env: { ...process.env, NODE_USE_ENV_PROXY: '1', ...((0, self_1.isStandalone)() ? { NODE_NO_WARNINGS: '1' } : {}) },
+    });
+    process.exitCode = r.status ?? (r.signal === 'SIGINT' ? 130 : 1);
+    return true;
+}
 async function main() {
+    // The sandbox's network relay (manual 4.12). Under Node it runs with `-e`;
+    // the ready to run program has no `-e`, so it asks for it by name.
+    if (process.argv[2] === '__relay' && (0, self_1.isStandalone)() && process.env.COMPRISM_RELAY) {
+        new Function('require', 'process', process.env.COMPRISM_RELAY)(require, process);
+        return;
+    }
+    if (throughProxy())
+        return;
+    // `--plain` anywhere means no color and no redrawn lines (manual 6.12). Taken
+    // off the line so no command reads it as a word of its request.
+    const plainAt = process.argv.indexOf('--plain', 2);
+    if (plainAt !== -1)
+        process.argv.splice(plainAt, 1);
+    const { applyLook } = await Promise.resolve().then(() => __importStar(require('./lib/machine')));
+    applyLook(plainAt !== -1);
     const [, , command, ...args] = process.argv;
+    // Carrying on a session (manual 8.4, 8.5). Flags rather than words, so
+    // `comprism --resume` reads as the same product starting, not a command.
+    if (command === '--continue' || command === '-c') {
+        const { runRepl } = await Promise.resolve().then(() => __importStar(require('./commands/repl')));
+        return runRepl({ latest: true });
+    }
+    if (command === '--resume' || command === '-r') {
+        const { runRepl } = await Promise.resolve().then(() => __importStar(require('./commands/repl')));
+        // `--resume --pr 42`: the latest session that worked on that pull request (8.10).
+        const prAt = args.indexOf('--pr');
+        if (prAt !== -1) {
+            const { sessions: ask8, failure } = await Promise.resolve().then(() => __importStar(require('./lib/sessions')));
+            const found = await ask8('by_pr', { pr: args[prAt + 1] ?? '' });
+            const first = found.sessions?.sessions?.[0]?.number;
+            if (!first) {
+                out(found.ok ? (found.sessions?.lines?.[0] ?? '') : ui.fail(failure(found)));
+                process.exitCode = 1;
+                return;
+            }
+            return runRepl({ resume: first });
+        }
+        const id = args.find((a) => a && !a.startsWith('-'));
+        if (id) {
+            // A session a cloud job worked on: its changes come here first (10.18).
+            const { sessions: ask8 } = await Promise.resolve().then(() => __importStar(require('./lib/sessions')));
+            const found = await ask8('resume', { key: id });
+            if (found.ok && found.sessions?.session_id) {
+                const { handBack } = await Promise.resolve().then(() => __importStar(require('./commands/unattended')));
+                await handBack(found.sessions.session_id, process.cwd());
+            }
+        }
+        return runRepl(id ? { resume: id } : { pick: true });
+    }
     switch (command) {
+        case 'sessions': {
+            const { cmdSessions } = await Promise.resolve().then(() => __importStar(require('./lib/sessions')));
+            process.exitCode = await cmdSessions(args);
+            return;
+        }
+        case 'review': {
+            // A read only job whose instruction is held on the service (manual 5.19).
+            const pr = flag(args, '--pr');
+            if (args.includes('--pr') && !/^\d+$/.test(pr ?? '')) {
+                out(ui.fail('--pr takes a pull request number, for example --pr 42.'));
+                process.exitCode = 2;
+                return;
+            }
+            if (args.includes('--post') && !pr) {
+                out(ui.fail('--post needs --pr: findings are posted to a pull request.'));
+                process.exitCode = 2;
+                return;
+            }
+            const { runAgent } = await Promise.resolve().then(() => __importStar(require('./agent/command')));
+            const { randomUUID } = await Promise.resolve().then(() => __importStar(require('node:crypto')));
+            process.exitCode = await runAgent({
+                request: [pr ? `review pull request #${pr}` : 'review my uncommitted changes'],
+                mode: 'read_only',
+                review: { ...(pr ? { pr: Number(pr) } : {}), post: args.includes('--post') },
+                conversationId: randomUUID(),
+                cwd: flag(args, '--cwd') ?? (await Promise.resolve().then(() => __importStar(require('./commands/settings')))).currentWorkspace().path,
+            });
+            return;
+        }
+        case 'integrations': {
+            const { cmdIntegrations } = await Promise.resolve().then(() => __importStar(require('./commands/integrations')));
+            process.exitCode = await cmdIntegrations(args);
+            return;
+        }
+        case 'plugins': {
+            const { cmdPlugins } = await Promise.resolve().then(() => __importStar(require('./commands/plugins')));
+            process.exitCode = await cmdPlugins(args);
+            return;
+        }
+        case 'skills': {
+            const { cmdSkills } = await Promise.resolve().then(() => __importStar(require('./commands/skills')));
+            process.exitCode = await cmdSkills(args);
+            return;
+        }
+        case 'agents': {
+            const { cmdAgents } = await Promise.resolve().then(() => __importStar(require('./commands/agents')));
+            process.exitCode = await cmdAgents(args);
+            return;
+        }
+        case 'jobs': {
+            const { cmdJobs } = await Promise.resolve().then(() => __importStar(require('./commands/jobs')));
+            process.exitCode = await cmdJobs(args);
+            return;
+        }
+        case 'permissions': {
+            const { cmdPermissions } = await Promise.resolve().then(() => __importStar(require('./commands/permissions')));
+            process.exitCode = await cmdPermissions(args);
+            return;
+        }
+        case 'config': {
+            const { cmdConfig } = await Promise.resolve().then(() => __importStar(require('./commands/config')));
+            process.exitCode = await cmdConfig(args);
+            return;
+        }
+        // Every instruction source in force, and your personal ones (manual 2.5 to 2.8).
+        case 'instructions': {
+            const { cmdInstructions } = await Promise.resolve().then(() => __importStar(require('./commands/instructions')));
+            process.exitCode = await cmdInstructions(args);
+            return;
+        }
+        // This project's notes (manual 2.9).
+        case 'memory': {
+            const { cmdMemory } = await Promise.resolve().then(() => __importStar(require('./commands/memory')));
+            process.exitCode = await cmdMemory(args);
+            return;
+        }
+        // What your company keeps about your work (manual 2.13).
+        case 'privacy': {
+            const { cmdPrivacy } = await Promise.resolve().then(() => __importStar(require('./commands/privacy')));
+            process.exitCode = await cmdPrivacy();
+            return;
+        }
+        // Separate copies of the repository (manual 2.11).
+        case 'worktrees': {
+            const { cmdWorktrees } = await Promise.resolve().then(() => __importStar(require('./commands/worktrees')));
+            process.exitCode = await cmdWorktrees(args);
+            return;
+        }
         case 'ask': {
             const { cmdAsk } = await Promise.resolve().then(() => __importStar(require('./commands/ask')));
-            return cmdAsk(args);
+            process.exitCode = await cmdAsk(args);
+            return;
+        }
+        // The newest version, and installing it when asked (manual 1.7).
+        case 'update': {
+            const { cmdUpdate } = await Promise.resolve().then(() => __importStar(require('./commands/update')));
+            process.exitCode = await cmdUpdate(args);
+            return;
+        }
+        // What the agent changed, the diff, and putting files back (manual 7).
+        case 'changes': {
+            const { cmdChanges } = await Promise.resolve().then(() => __importStar(require('./commands/review')));
+            process.exitCode = await cmdChanges(args);
+            return;
+        }
+        case 'diff': {
+            const { cmdDiff } = await Promise.resolve().then(() => __importStar(require('./commands/review')));
+            process.exitCode = await cmdDiff(args);
+            return;
+        }
+        case 'rewind': {
+            const { cmdRewind } = await Promise.resolve().then(() => __importStar(require('./commands/review')));
+            process.exitCode = await cmdRewind(args);
+            return;
+        }
+        // Jobs nobody is sitting at (manual 10.17 to 10.19).
+        case 'schedule': {
+            const { cmdSchedule } = await Promise.resolve().then(() => __importStar(require('./commands/unattended')));
+            process.exitCode = await cmdSchedule(args);
+            return;
+        }
+        case 'triggers': {
+            const { cmdTriggers } = await Promise.resolve().then(() => __importStar(require('./commands/unattended')));
+            process.exitCode = await cmdTriggers(args);
+            return;
+        }
+        case 'worker': {
+            const { cmdWorker } = await Promise.resolve().then(() => __importStar(require('./commands/unattended')));
+            process.exitCode = await cmdWorker(args);
+            return;
+        }
+        // Hooks in force here, and running them now to see what they do (10.10).
+        case 'hooks': {
+            const { cmdHooks } = await Promise.resolve().then(() => __importStar(require('./commands/hooks')));
+            process.exitCode = await cmdHooks(args);
+            return;
+        }
+        // The coding allowance and provider limits, from the service (manual 10.12).
+        case 'ide': {
+            // Which VS Code window this folder is joined to (VS Code manual 9.12).
+            const { findEditor } = await Promise.resolve().then(() => __importStar(require('./lib/ide')));
+            const link = findEditor(process.cwd());
+            out(link
+                ? `  Connected to VS Code for ${link.folder}. Proposed changes open in its diff view.`
+                : '  No VS Code window with CompletionPrism has this folder open. Open the folder in VS Code and run this again.');
+            return;
+        }
+        case 'usage': {
+            const { ask: askGateway } = await Promise.resolve().then(() => __importStar(require('./lib/gateway')));
+            const { exitFor } = await Promise.resolve().then(() => __importStar(require('./lib/output')));
+            const reply = await askGateway({ intent: 'usage', prompt: '', tzMinutes: -new Date().getTimezoneOffset() });
+            const found = reply.usage;
+            if (!reply.ok || reply.served === false || !found?.lines) {
+                err(ui.fail(reply.message || 'Usage could not be read from your workspace.'));
+                process.exitCode = exitFor(reply.httpStatus === 401 ? 'signed_out'
+                    : reply.ok || reply.httpStatus ? 'incomplete' : 'unreachable');
+                return;
+            }
+            out();
+            for (const line of found.lines)
+                out(`  ${line}`);
+            out();
+            return;
+        }
+        // The published shape of `--output json`, from the service (manual 10.3).
+        case 'schema': {
+            if (args[0] !== 'output') {
+                err(ui.fail('comprism schema output prints the shape of --output json.'));
+                process.exitCode = 2;
+                return;
+            }
+            const { ask: askGateway } = await Promise.resolve().then(() => __importStar(require('./lib/gateway')));
+            const reply = await askGateway({ intent: 'schema', prompt: '' });
+            const doc = reply.schema_doc;
+            if (!reply.ok || reply.served === false || !doc?.output) {
+                err(ui.fail(reply.message || 'The schema could not be read from your workspace.'));
+                const { exitFor } = await Promise.resolve().then(() => __importStar(require('./lib/output')));
+                process.exitCode = exitFor(reply.httpStatus === 401 ? 'signed_out'
+                    : reply.ok || reply.httpStatus ? 'incomplete' : 'unreachable');
+                return;
+            }
+            out(JSON.stringify(doc.output, null, 2));
+            return;
         }
         // `work` is the word. `agent` still answers to it, because anybody who
         // learned the old name should not meet "unknown command".
@@ -108,39 +418,205 @@ async function main() {
                 out(AGENT_HELP);
                 return;
             }
+            // Every typing mistake is refused here, before anything is sent, asked
+            // or charged (manual 10.6, exit 2 in Appendix B). A reason goes to
+            // standard error, so a script reading standard output reads nothing.
+            const { outputChoice, readJsonFile, unknownFlag } = await Promise.resolve().then(() => __importStar(require('./lib/output')));
+            const { MODES } = await Promise.resolve().then(() => __importStar(require('./agent/command')));
+            const typo = (why) => {
+                err(ui.fail(why) + ui.c.dim('  Nothing ran and nothing was charged.'));
+                process.exitCode = 2;
+            };
+            const output = outputChoice(args);
+            if ('bad' in output)
+                return typo(output.bad);
+            const stray = unknownFlag(args, WORK_VALUES, WORK_SWITCHES);
+            if (stray)
+                return typo(`${stray} is not an option of comprism work. comprism work --help lists them.`);
+            // `--schema` and `--config` name files read here and judged by the
+            // service (manual 10.5, 10.8). A missing or unreadable file is a typing
+            // mistake.
+            let answerSchema;
+            if (args.includes('--schema')) {
+                const got = readJsonFile(String(flag(args, '--schema') ?? ''), '--schema');
+                if ('bad' in got)
+                    return typo(got.bad);
+                answerSchema = got.value;
+            }
+            let settingsConfig;
+            if (args.includes('--config')) {
+                const got = readJsonFile(String(flag(args, '--config') ?? ''), '--config');
+                if ('bad' in got)
+                    return typo(got.bad);
+                settingsConfig = got.value;
+            }
+            const wantedMode = flag(args, '--mode');
+            if (args.includes('--mode') && !MODES.includes(String(wantedMode))) {
+                return typo(`${wantedMode ?? '(nothing)'} is not a permission mode. One of: ${MODES.join(', ')}.`);
+            }
+            const spend = flag(args, '--max-spend');
+            if (args.includes('--max-spend') && !(Number(spend) > 0)) {
+                return typo('--max-spend takes an amount in dollars, for example --max-spend 2.00.');
+            }
+            // A step limit that is not a whole number is a typing mistake (4.13).
+            if (args.includes('--max-steps')) {
+                const steps = Number(flag(args, '--max-steps'));
+                if (!Number.isInteger(steps) || steps <= 0) {
+                    return typo('--max-steps takes a whole number, for example --max-steps 40.');
+                }
+            }
+            // A time limit is a number of minutes (manual 10.7).
+            if (args.includes('--max-minutes') && !(Number(flag(args, '--max-minutes')) > 0)) {
+                return typo('--max-minutes takes a number of minutes, for example --max-minutes 15.');
+            }
+            // Effort is one of three words (manual 4.18).
+            if (args.includes('--effort') && !['low', 'medium', 'high'].includes(String(flag(args, '--effort')))) {
+                return typo('--effort takes low, medium or high.');
+            }
+            // A time limit that is not a number of seconds is a typing mistake:
+            // nothing runs and nothing is charged (manual 5.12, exit 2).
+            if (args.includes('--issue') && !/^\d+$/.test(flag(args, '--issue') ?? '')) {
+                return typo('--issue takes an issue number, for example --issue 42.');
+            }
+            if (args.includes('--timeout')) {
+                const secs = Number(flag(args, '--timeout'));
+                if (!Number.isInteger(secs) || secs <= 0) {
+                    return typo('--timeout takes a whole number of seconds, for example --timeout 600.');
+                }
+            }
+            // Text piped in is read to its end first: it is material for the job,
+            // never the request and never an answer (manual 3.9).
+            const { readPiped } = await Promise.resolve().then(() => __importStar(require('./lib/stdin')));
+            const piped = await readPiped();
             const { subject, closePrompt } = await Promise.resolve().then(() => __importStar(require('./lib/prompt')));
             // Asked for when it was not given, same as every other command.
-            const request = await subject(args, '  what would you like done? ', ['--mode', '--model', '--max-spend', '--resume', '--cwd', '--allow']);
+            const request = await subject(args, '  what would you like done? ', WORK_VALUES);
             closePrompt();
             if (!request) {
-                out(ui.fail('Nothing was asked for.'));
-                out();
+                if (piped?.trim()) {
+                    return typo('Piped text needs a request with it, for example: '
+                        + 'git diff | comprism work "write a commit message for this"');
+                }
+                // Standard input closed with nothing on it is a missing request.
+                return typo('Nothing was asked for.');
+            }
+            // On a CompletionPrism worker with a copy of the repository (10.18).
+            if (args.includes('--cloud')) {
+                const { submitCloud } = await Promise.resolve().then(() => __importStar(require('./commands/unattended')));
+                process.exitCode = await submitCloud(request, flag(args, '--cwd') ?? process.cwd(), args);
                 return;
             }
-            const spend = flag(args, '--max-spend');
+            // `comprism work /name the rest` runs that skill (manual 9.2). A slash
+            // word the service lists as neither a skill nor a saved command is a
+            // typo, refused before anything is sent or charged, as in a session.
+            const slashWord = /^\/([a-z][a-z0-9-]*)(?:\s|$)/i.exec(request.trim());
+            if (slashWord && !(await Promise.resolve().then(() => __importStar(require('./lib/attach')))).startsWithPath(request.trim())) {
+                const { fetchCommandList } = await Promise.resolve().then(() => __importStar(require('./lib/commandlist')));
+                const { resolveProject } = await Promise.resolve().then(() => __importStar(require('./lib/project')));
+                const where = flag(args, '--cwd') ?? (await Promise.resolve().then(() => __importStar(require('./commands/settings')))).currentWorkspace().path;
+                const list = await fetchCommandList(resolveProject(where).root, []);
+                const name = slashWord[1].toLowerCase();
+                if (list.ok && !list.items.some((i) => i.source !== 'session' && i.name === name)) {
+                    return typo(`\`/${name}\` is neither a skill nor a saved command here. comprism skills lists the skills.`);
+                }
+            }
+            const fromPipe = await attachStdin(piped);
+            if (fromPipe === null) {
+                process.exitCode = 1;
+                return;
+            }
+            // `--resume` takes a session number or a job number and carries on that
+            // session's conversation (manual 8.4). The service resolves it; a job
+            // that belongs to no session is rejoined as before.
+            let resume = flag(args, '--resume');
+            let carry = {};
+            if (resume) {
+                const { sessions } = await Promise.resolve().then(() => __importStar(require('./lib/sessions')));
+                const found = await sessions('resume', { key: resume });
+                if (found.ok && found.sessions?.session_id) {
+                    for (const line of found.sessions.lines)
+                        out(line);
+                    out();
+                    carry = {
+                        conversationId: found.sessions.session_id,
+                        ...(found.sessions.continues_job ? { continuesJob: found.sessions.continues_job } : {}),
+                    };
+                    resume = undefined;
+                }
+                else if (resume.startsWith('s_')) {
+                    out(ui.fail(found.message || 'There is no session with that number you can open.'));
+                    out();
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            // Every job belongs to a session, so it has a number, is listed and can
+            // be resumed (manual 8.1). A job on its own is a session of one job.
+            if (!carry.conversationId && !resume) {
+                const { randomUUID } = await Promise.resolve().then(() => __importStar(require('node:crypto')));
+                carry.conversationId = randomUUID();
+            }
+            // A separate copy of the repository (manual 2.11): made the first time,
+            // and the job runs in it.
+            let workFolder = flag(args, '--cwd')
+                ?? (await Promise.resolve().then(() => __importStar(require('./commands/settings')))).currentWorkspace().path;
+            const worktree = flag(args, '--worktree');
+            if (worktree) {
+                const { checkFolder, resolveProject } = await Promise.resolve().then(() => __importStar(require('./lib/project')));
+                const start = checkFolder(workFolder);
+                if (!start.ok) {
+                    out(ui.fail(start.why));
+                    process.exitCode = 2;
+                    return;
+                }
+                const { ensureWorktree } = await Promise.resolve().then(() => __importStar(require('./commands/worktrees')));
+                const made = await ensureWorktree(resolveProject(start.path), worktree, carry.conversationId ?? 'cli');
+                if (!made) {
+                    process.exitCode = 1;
+                    return;
+                }
+                workFolder = made;
+            }
             process.exitCode = await runAgent({
+                ...carry,
                 request: [request],
                 mode: flag(args, '--mode'),
                 plan: args.includes('--plan'),
                 approvePlan: args.includes('--approve-plan'),
                 model: flag(args, '--model'),
-                pin: args.includes('--pin'),
+                pin: args.includes('--pin') || args.includes('--no-optimize'),
                 ...(args.includes('--max-spend') ? { maxSpend: Number(spend) } : {}),
+                ...(args.includes('--max-steps') ? { maxSteps: Number(flag(args, '--max-steps')) } : {}),
+                ...(args.includes('--max-minutes') ? { maxMinutes: Number(flag(args, '--max-minutes')) } : {}),
+                ...(args.includes('--effort') ? { effort: flag(args, '--effort') } : {}),
+                sandbox: args.includes('--sandbox'),
+                ...(args.includes('--timeout') ? { timeout: Number(flag(args, '--timeout')) } : {}),
+                ...(args.includes('--issue') ? { issue: Number(flag(args, '--issue')) } : {}),
+                ...(args.includes('--team') ? { team: flag(args, '--team') } : {}),
                 allow: args.reduce((acc, a, i) => (args[i - 1] === '--allow' ? [...acc, a] : acc), []),
+                // Repeatable, and the only way a second folder is allowed (manual 2.3).
+                addFolders: args.reduce((acc, a, i) => (args[i - 1] === '--add-folder' ? [...acc, a] : acc), []),
                 yes: args.includes('--yes'),
                 background: args.includes('--background'),
-                resume: flag(args, '--resume'),
+                output,
+                ...(args.includes('--queued') ? { queuedJob: flag(args, '--queued') } : {}),
+                ...(answerSchema ? { answerSchema } : {}),
+                ...(settingsConfig ? { settingsConfig } : {}),
+                noPersonal: args.includes('--no-personal'),
+                resume,
                 // Go without the code map for this one job. Two reasons somebody uses
                 // it: they are measuring, and a run with a map and a run without one
                 // are two different quantities; or they suspect the map and want the
                 // files read directly. Both are legitimate and neither should require
                 // an administrator.
                 noMap: args.includes('--no-map') || args.includes('--no-graph'),
+                attachments: fromPipe.ids,
+                keyboard: fromPipe.keyboard,
                 // The saved working folder when there is one, so `comprism workspace`
                 // is a setting the agent honors rather than a stored string nothing reads.
-                cwd: flag(args, '--cwd')
-                    ?? (await Promise.resolve().then(() => __importStar(require('./commands/settings')))).currentWorkspace().path,
+                cwd: workFolder,
             });
+            fromPipe.keyboard?.destroy();
             return;
         }
         // The map of the project you are standing in: what it holds, and a way to
@@ -193,9 +669,12 @@ async function main() {
             const { cmdProviders } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
             return cmdProviders();
         }
+        // `project` is the word (manual 2.1). `workspace` stays as another name,
+        // because it also means the company account and people learned it first.
+        case 'project':
         case 'workspace': {
-            const { cmdWorkspace } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
-            return cmdWorkspace(args);
+            const { cmdProject } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
+            return cmdProject(args);
         }
         case 'keys': {
             const { cmdKeys } = await Promise.resolve().then(() => __importStar(require('./commands/keys')));
@@ -208,25 +687,59 @@ async function main() {
         // What this machine still needs. Its own word because somebody whose PDF
         // would not read has a question about THIS machine, and the answer should
         // not be buried inside a setup command they have already run.
+        // What a session cost, and what drove it. Its own word because "where did
+        // the money go" is a different question from "what did this answer cost",
+        // and the receipt under an answer only ever answers the second.
+        case 'cost':
+        case 'spend': {
+            const { cmdCost } = await Promise.resolve().then(() => __importStar(require('./commands/cost')));
+            process.exitCode = await cmdCost(args);
+            return;
+        }
         case 'check':
         case 'doctor': {
-            const { check } = await Promise.resolve().then(() => __importStar(require('./lib/readiness')));
-            const machine = check();
+            const { diagnose } = await Promise.resolve().then(() => __importStar(require('./lib/readiness')));
+            const found = await diagnose();
             out();
             out(ui.banner('This machine'));
             out();
-            for (const line of machine.lines)
-                out(line);
-            out();
-            if (machine.ready) {
-                out(ui.ok('Everything the work needs is here.'));
-            }
-            else {
-                out(`  ${ui.c.dim('to add what is missing:')} ${ui.c.bold(machine.fix)}`);
+            for (const f of found) {
+                const mark = f.ok ? ui.c.dim('ok  ') : f.required ? 'no  ' : ui.c.dim('--  ');
+                out(`  ${mark}  ${f.line}${!f.ok && f.fix ? `. ${f.fix}` : ''}`);
             }
             out();
-            out(ui.c.dim('  Word, PowerPoint and PDF documents are built on our servers,'));
-            out(ui.c.dim('  so nothing has to be installed here for those.'));
+            const fixes = [...new Set(found.filter((f) => !f.ok && f.fix).map((f) => f.fix))];
+            if (fixes.length)
+                out(`  ${ui.c.dim('to add what is missing:')} ${ui.c.bold(fixes.join(', then '))}`);
+            out(`  ${ui.c.dim('to check the account and the service:')} ${ui.c.bold('comprism status')}`);
+            out();
+            // Only a required item decides the exit status (manual 1.6).
+            if (found.some((f) => f.required && !f.ok))
+                process.exitCode = 1;
+            return;
+        }
+        // The install's own message, the postinstall fallback and the generated
+        // shell script all tell a person to run this, so it has to exist as a word.
+        case 'install': {
+            const { install } = await Promise.resolve().then(() => __importStar(require('./commands/install')));
+            const report = install();
+            // `--quiet` is the install scripts' form (manual 1.1, Option 1): only the
+            // lines that say what changed, under the script's own heading.
+            const quiet = args.includes('--quiet');
+            if (!quiet) {
+                out();
+                out(ui.banner('Set up this machine'));
+                out();
+            }
+            for (const profile of report.profilesTouched)
+                out(`  added one line to ${profile}`);
+            for (const profile of report.profilesAlreadyHad)
+                out(`  already set up in ${profile}`);
+            if (quiet)
+                return;
+            out(report.enrolled && report.baseUrl
+                ? `  AI tools in a new terminal are measured against ${report.baseUrl}`
+                : `  nothing is measured until this machine signs in: ${ui.c.bold('comprism login')}`);
             out();
             return;
         }
@@ -236,22 +749,56 @@ async function main() {
         // word, so a customer following our own instruction got "there is no
         // command called uninstall" and was left to edit their profile by hand.
         case 'uninstall': {
+            // One command takes everything back out, as one command put it in
+            // (owner, 27 September 2026): the machine's key is revoked, the shell
+            // line and generated script go, the saved settings go, and the program
+            // removes itself. `--keep-settings` keeps the sign in for a reinstall.
+            const keep = args.includes('--keep-settings');
+            const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
+            const { spawnSync, spawn } = await Promise.resolve().then(() => __importStar(require('node:child_process')));
             const { uninstall } = await Promise.resolve().then(() => __importStar(require('./commands/install')));
+            if (!keep) {
+                const { cmdDisconnect } = await Promise.resolve().then(() => __importStar(require('./commands/commands-thin')));
+                await cmdDisconnect().catch(() => undefined);
+            }
             const report = uninstall();
-            out();
             out(ui.banner('Removed from this machine'));
             out();
-            if (report.profilesCleaned.length === 0) {
-                out(ui.c.dim('  Nothing to take out: no shell profile carried our line.'));
+            for (const profile of report.profilesCleaned)
+                out(`  removed our line from ${profile}`);
+            if (report.scriptRemoved)
+                out('  removed the generated shell script');
+            if (report.programRemoved)
+                out('  removed the program from ~/.comprism/bin');
+            if (!keep) {
+                fs.rmSync(report.kept, { recursive: true, force: true });
+                out(`  removed the saved settings in ${report.kept}`);
             }
-            else {
-                for (const profile of report.profilesCleaned) {
-                    out(`  removed our line from ${profile}`);
-                }
+            // The program itself, the way it was installed. On Windows a running
+            // program cannot delete itself, so the removal runs just after we exit.
+            const remover = report.method === 'npm'
+                ? [process.platform === 'win32' ? 'npm.cmd' : 'npm', ['uninstall', '-g', '@illuminis/comprism']]
+                : report.method === 'python'
+                    ? (spawnSync('pipx', ['--version'], { stdio: 'ignore' }).status === 0
+                        ? ['pipx', ['uninstall', 'comprism-cli']]
+                        : [process.platform === 'win32' ? 'python' : 'python3', ['-m', 'pip', 'uninstall', '-y', 'comprism-cli']])
+                    : null;
+            if (remover && process.platform === 'win32') {
+                // Through cmd.exe, which is how npm.cmd and pip run on Windows, with
+                // every value its own argument and no shell string built from them.
+                // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- a fixed removal command, no shell
+                spawn('cmd.exe', ['/d', '/c', remover[0], ...remover[1]], { detached: true, stdio: 'ignore' }).unref();
+                out('  removing the comprism command');
+            }
+            else if (remover) {
+                const done = spawnSync(remover[0], remover[1], { stdio: 'ignore' });
+                out(done.status === 0
+                    ? '  removed the comprism command'
+                    : ui.warn(`  could not remove the command itself; run: ${remover[0]} ${remover[1].join(' ')}`));
             }
             out();
             out(ui.c.dim('  Every AI tool on this machine now talks straight to its provider.'));
-            out(ui.c.dim('  To remove the command itself: npm uninstall -g @illuminis/comprism'));
+            out(ui.c.dim('  Open a new terminal window to finish.'));
             out();
             return;
         }
@@ -271,8 +818,23 @@ async function main() {
             if (command) {
                 out(ui.fail(`There is no command called "${command}".`));
                 out();
+                // A script that mistypes a command must not read it as success. Two is
+                // the manual's number for a wrongly typed command (Appendix B).
+                process.exitCode = 2;
                 return usage();
             }
+            // Text piped into the bare command has nothing to go with (manual 3.9).
+            if (!process.stdin.isTTY) {
+                const { readPiped } = await Promise.resolve().then(() => __importStar(require('./lib/stdin')));
+                const piped = await readPiped();
+                if (piped?.trim()) {
+                    err(ui.fail('Piped text needs a request with it, for example: '
+                        + '... | comprism ask "why is this failing"'));
+                    err(ui.c.dim('  Nothing ran and nothing was charged.'));
+                    process.exitCode = 2;
+                    return;
+                }
+            }
             // The bare command STARTS the product rather than describing it.
             const { runRepl } = await Promise.resolve().then(() => __importStar(require('./commands/repl')));
             return runRepl();