@source-repo/rpc-cli 4.5.0 → 5.0.0

package/dist/grants.js

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import { openAiGrants, validateAiGrants } from '@source-repo/rpc';
+/**
+ * The AI grants document, read from a file rather than assembled from flags.
+ *
+ * A path and not a set of options, for the reason the document exists at all: it is declarative
+ * data with a revision, so that a console can render it and a reviewer can diff it. Something built
+ * out of `--grant ai.tool.write --to bench --until …` would be neither - there would be nothing to
+ * diff, and the revision would have nowhere to live.
+ *
+ * Not a secret, either, which is why it is only ever a path and never written inline in a task
+ * file the way `sign` and `auth` may be. The revision field is there so policy can be replaced on
+ * its own cadence; burying the document inside another file that changes for unrelated reasons
+ * takes that away.
+ */
+export const loadAiGrants = (path) => {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`cannot read grants from ${path}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    try {
+        // validateAiGrants throws with the reason. A node that starts holding an unreadable security
+        // policy is the failure the document exists to prevent, so this is never softened into a
+        // warning: the operator meant to grant something, and carrying on with nothing granted would
+        // be a quiet answer to a loud problem.
+        return validateAiGrants(document);
+    }
+    catch (e) {
+        throw new Error(`${path}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+};
+const describeEntry = (entry) => {
+    const bounds = [
+        entry.to?.length ? `to ${entry.to.join(', ')}` : undefined,
+        entry.roles?.length ? `roles ${entry.roles.join(', ')}` : undefined,
+        // Said out loud because it is the one an operator is most likely to have meant to set and
+        // not set: an unbounded grant is a real choice and should not read like an oversight.
+        entry.expiresAt === undefined ? 'no expiry' : `until ${new Date(entry.expiresAt).toISOString()}`,
+        entry.maxGeneration === undefined ? undefined : `generation ${entry.maxGeneration}`
+    ].filter(Boolean);
+    return bounds.length ? bounds.join(', ') : 'every AI principal of that provenance';
+};
+/**
+ * What this node has open, in the order a person would ask it.
+ *
+ * Printed at startup because closed-by-default means "it is running" and "it can do something" are
+ * separately true, and an operator who has just written a grants file is entitled to see whether
+ * the thing they wrote is the thing that took effect. An expired grant is simply absent here, which
+ * is the honest answer and not the same as it having been removed from the file.
+ */
+export const grantLines = (grants, now = Date.now()) => {
+    if (!grants)
+        return ['no grants document, so AI principals may observe and nothing else'];
+    const open = openAiGrants(grants, now);
+    if (!open.length)
+        return [`grants revision ${grants.revision}: nothing open, so AI principals may observe and nothing else`];
+    return [`grants revision ${grants.revision}:`, ...open.map(({ grant, ...entry }) => `  ${grant} — ${describeEntry(entry)}`)];
+};
+//# sourceMappingURL=grants.js.map

package/dist/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { basename, resolve } from 'node:path';
-import { createHmacSigner, createHmacVerifier, createTokenAuthenticator, defaultSecureWebPort, defaultSecureWebSocketPort, defaultWebPort, defaultWebSocketPort, namespaceProblems, readableNameFor } from '@source-repo/rpc';
+import { createDerivedAuthenticator, createTokenAuthenticator, firstAuthenticator, defaultSecureWebPort, defaultSecureWebSocketPort, defaultWebPort, defaultWebSocketPort, namespaceProblems, readableNameFor } from '@source-repo/rpc';
 import { extractSchema } from './extract.js';
 import { startConsole } from './console.js';
 import { startBroker } from './broker.js';
@@ -15,6 +15,9 @@ import { startFake } from './fake.js';
 import { replaySession, startRecording } from './record.js';
 import { checkPeer, diffPeers } from './conform.js';
 import { bench, benchArguments } from './bench.js';
+import { loadAuthFile, loadSigningKeys, loadTls, scriptCredentials } from './credentials.js';
+import { grantLines, loadAiGrants } from './grants.js';
+import { defaultTaskFile, startTaskFile, taskFileSkeleton, taskFileSkeletonNotes } from './tasks.js';
 /**
  * msgrpc extract  - read the contract out of TypeScript source and write it to a file
  * msgrpc check    - compare the source against a written contract and report breaking changes
@@ -32,6 +35,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
   console   browse a live network in a browser: peers, what they expose, calls and events
   broker    run a WebSocket bus: relays between the peers that connect to it, until Ctrl-C
   node      make this machine scriptable from another one, and nothing else, until Ctrl-C
+  run       start console, node and serve roles together from one JSON task file, until Ctrl-C
+            with no file named it runs ./source-rpc.tasks.json; --init writes one to start from
   mcp       serve the network to an MCP client over stdio: list peers, describe them, call them
             stdio carries the protocol, so it is not for interactive use; --port opens a second
             door over streamable HTTP, so two clients can share one node
@@ -70,6 +75,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   peers / describe / call / watch
     --broker <url>              an MQTT network, e.g. mqtt://localhost:1883
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network, e.g. http://hub:7843
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -86,6 +93,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   console
     --broker <url>              an MQTT network, e.g. mqtt://localhost:1883
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network, e.g. http://hub:7843
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -102,6 +111,8 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
 
   mcp
     --broker <url>              an MQTT network
+                                SOURCE_RPC_MQTT_USERNAME and SOURCE_RPC_MQTT_PASSWORD are used
+                                as broker credentials when set
     --hub <url>                 a socket.io network
                                 one of --broker and --hub is required; both watches both
     --prefix <topic>            topic namespace, default the transport's own
@@ -122,6 +133,7 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
                                 nothing can script it. The peer must authenticate as that name,
                                 so the key it presents reaches it out of band - deliberately not
                                 something this bus can hand over
+    --grants <file>             what an AI principal may do here; see node --grants above
     --port <n>                  serve streamable HTTP here as a second door beside stdio, so a
                                 second client shares this node's scripts, fakes and watches
                                 rather than forking them. No default: absent means stdio only
@@ -162,6 +174,19 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
                                 on a broker, --sign at both ends is what makes the grant work:
                                 without it nothing can prove who a caller is and every call is
                                 refused
+    --grants <file>             what an AI principal may do here, as a grants document. Without one
+                                a badged principal may observe and nothing else, which is the
+                                default everywhere. SIGHUP re-reads it, so a grant can be closed
+                                without stopping the node
+
+  run [<file.json>]             defaults to ./source-rpc.tasks.json, in this directory only
+    shared network settings and console, node or serve tasks; relative paths are resolved from the
+    task file. Each task's credentials are its own: a key file under 'sign', an auth file under
+    'auth', or the same secrets written inline in either. Full format:
+    https://source-repo.github.io/rpc/tools/cli#task-files
+    --init                      write a task file to start from, with three roles and fresh signing
+                                secrets, and refuse to write over one that exists. --broker, --hub
+                                and --scriptable-by fill in what they name
 
   strip <file…>
     --out <dir>                 where each decorator-free twin lands, under the same file name.
@@ -191,7 +216,12 @@ const usage = `source-rpc <command> [options]          --version prints the CLI
     { "token": "…",             presented when this command dials a hub that authenticates
       "tokens": {               accepted when this command is the bus: token -> the peer it admits
         "…": "plantServer",
-        "…": { "name": "hmi", "roles": ["operator"] } } }
+        "…": { "name": "hmi", "roles": ["operator"] } },
+      "derive": "…",            on a node: the secret it mints credentials with for the scripts it
+                                starts, so each one connects as itself and the node's own token
+                                never reaches a script's environment
+      "issuers": {              on a bus: which nodes it lets vouch for the programs they start
+        "node-a": "…" } }       issuer peer name -> the same secret that node derives with
     SOURCE_RPC_TOKEN            the same "token", for a container
     SOURCE_RPC_TOKENS           the same "tokens" as JSON, for a container
                                 never a flag: ps is readable by everyone on the box
@@ -247,30 +277,110 @@ const withHistory = (next, previous) => {
     }
     return next;
 };
+/**
+ * HMAC keys for the console, read from a file rather than a flag: a secret on the command line is
+ * visible to anyone who can run ps.
+ *
+ *   { "name": "console-1", "secret": "…", "peers": { "plantServer": "…" } }
+ *
+ * `peers` is optional. Supplying it makes the console check signatures on what it receives too,
+ * which means an unsigned peer's frames are then dropped.
+ */
 const readSigningKeys = (path, command) => {
-    let keys;
     try {
-        keys = JSON.parse(readFileSync(path, 'utf8'));
+        const signing = loadSigningKeys(path);
+        if (signing.readableByOthers)
+            process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
+        return signing;
     }
     catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read keys from ${path}: ${e.message}\n`);
-        process.exit(1);
-    }
-    if (typeof keys.secret !== 'string' || !keys.secret) {
-        process.stderr.write(`source-rpc ${command}: ${path} has no "secret"\n`);
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
+};
+/**
+ * Bearer tokens, read from a file or the environment. Never a flag, for the same reason the signing
+ * secret is not one: `ps` is readable by everyone on the box.
+ *
+ *   { "token": "…", "tokens": { "…": "plantServer", "…": { "name": "hmi", "roles": ["operator"] } } }
+ *
+ * `token` is what this command presents when it dials a bus that authenticates. `tokens` is what
+ * `broker` accepts, each mapping to the one peer name it admits. A file may carry either or both -
+ * a broker joining an upstream needs both, since it is a bus to one side and a peer to the other.
+ *
+ * `SOURCE_RPC_TOKEN` and `SOURCE_RPC_TOKENS` say the same two things, for a container where a file
+ * is a mount and an environment variable is a line in the compose file. `--auth` names a path
+ * rather than a secret, so it is explicit and wins over both.
+ */
+/**
+ * Builds the per-script credential minter for a node that has a signing secret, or undefined.
+ *
+ * Undefined is a real answer rather than a failure: a bench with no authentication needs no
+ * credentials, and the thing that must never happen - a script inheriting the node's own token -
+ * is now impossible either way. Lifetimes are short and renewal does not exist, so stopping the
+ * node means its scripts' credentials expire on their own; immediate revocation is the grants
+ * work, not this.
+ *
+ * The minting itself lives in credentials.ts, because `run` mints the same credentials from a task
+ * file and two implementations of a credential are two things to get subtly different.
+ */
+const scriptCredentialsFor = (auth, issuer, command) => scriptCredentials(auth, issuer, (message) => process.stderr.write(`source-rpc ${command}: ${message}\n`));
+const readAiGrants = (path, command) => {
     try {
-        // Worth saying out loud: this file is the console's identity on the network.
-        if (statSync(path).mode & 0o077)
-            process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
+        return loadAiGrants(path);
     }
-    catch {
-        // Not worth failing over if the mode cannot be read.
+    catch (e) {
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
     }
-    const sign = createHmacSigner(keys.secret);
-    const verify = keys.peers ? createHmacVerifier((peer) => keys.peers?.[peer]) : undefined;
-    return { keys, sign, verify };
+};
+/**
+ * Refusals reach the operator; permitted calls do not.
+ *
+ * Both are audit, and both belong in the fleet-side sink rather than here - but of the two, a
+ * refusal is the one somebody is standing at a terminal wondering about, and printing every allowed
+ * call would bury it. The sentence the library supplies is the whole line: it already says which
+ * grant was wanted and why the answer was no.
+ */
+const aiDecisionReporter = (command) => (record) => {
+    if (!record.allowed)
+        process.stderr.write(`source-rpc ${command}: refused ${record.source} calling ${record.method}: ${record.reason}\n`);
+};
+/**
+ * Re-read the grants document on SIGHUP, so a grant can be closed without restarting the node.
+ *
+ * A signal rather than a file watcher, deliberately. A watcher fires on a half-written file and
+ * has to be taught what an atomic replace looks like on three platforms; a signal is an operator
+ * saying *now*, which is the same instinct as everything else here - a change in what is permitted
+ * is something somebody states rather than something that happens when a file is touched.
+ *
+ * A failed reload keeps the document that was already in force. The alternative - falling back to
+ * no document - reads as "closed, therefore safe" and is in fact the node quietly disagreeing with
+ * the policy its operator believes is loaded.
+ */
+const reloadGrantsOnHangUp = (path, initial, apply, command) => {
+    // Not every platform has SIGHUP, and Windows has none of this. Nothing else is affected.
+    if (process.platform === 'win32')
+        return;
+    let current = initial;
+    process.on('SIGHUP', () => {
+        let next;
+        try {
+            next = loadAiGrants(path);
+        }
+        catch (e) {
+            process.stderr.write(`source-rpc ${command}: grants unchanged, ${e instanceof Error ? e.message : String(e)}\n`);
+            return;
+        }
+        // The revision exists so a rollback is visible. Applied anyway - an operator may be
+        // deliberately reverting - but never silently, since the other cause is a stale file.
+        if (current && next.revision < current.revision)
+            process.stderr.write(`source-rpc ${command}: grants revision went backwards, ${current.revision} to ${next.revision}\n`);
+        current = next;
+        apply(next);
+        for (const line of grantLines(next))
+            process.stderr.write(`source-rpc ${command}: ${line}\n`);
+    });
 };
 /**
  * Certificate and key for a server this command opens, or undefined for plain HTTP.
@@ -291,10 +401,10 @@ const readTls = (argv, command) => {
         process.exit(1);
     }
     try {
-        return { cert: readFileSync(cert), key: readFileSync(key) };
+        return loadTls(cert, key);
     }
     catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read the certificate or key: ${e.message}\n`);
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
 };
@@ -325,29 +435,17 @@ const readAuth = (argv, command) => {
             ...(tokens ? { tokens } : {})
         };
     }
-    let auth;
-    try {
-        auth = JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch (e) {
-        process.stderr.write(`source-rpc ${command}: cannot read tokens from ${path}: ${e.message}\n`);
-        process.exit(1);
-    }
-    if (!auth.token && !auth.tokens) {
-        // An empty file is the failure that looks like success: the command starts, and the bus it
-        // meant to gate is open. Better to refuse than to run unauthenticated on request.
-        process.stderr.write(`source-rpc ${command}: ${path} has neither "token" nor "tokens"\n`);
-        process.exit(1);
-    }
     try {
+        const loaded = loadAuthFile(path);
         // Worth saying out loud: whoever can read this file can be these peers.
-        if (statSync(path).mode & 0o077)
+        if (loaded.readableByOthers)
             process.stderr.write(`source-rpc ${command}: ${path} is readable by other users\n`);
+        return loaded.auth;
     }
-    catch {
-        // Not worth failing over if the mode cannot be read.
+    catch (e) {
+        process.stderr.write(`source-rpc ${command}: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
     }
-    return auth;
 };
 /**
  * The flags every command that joins a network takes, read once.
@@ -774,7 +872,11 @@ const runBroker = async (argv) => {
     const auth = readAuth(argv, 'broker');
     let authenticate;
     try {
-        authenticate = auth.tokens ? createTokenAuthenticator(auth.tokens) : undefined;
+        const byToken = auth.tokens ? createTokenAuthenticator(auth.tokens) : undefined;
+        const byDerivation = auth.issuers ? createDerivedAuthenticator({ issuers: auth.issuers }) : undefined;
+        // Operators hold tokens; nodes vouch for the programs they start. A bus configured with
+        // both admits both, and one configured with neither admits nobody, as before.
+        authenticate = byToken && byDerivation ? firstAuthenticator(byToken, byDerivation) : (byToken ?? byDerivation);
     }
     catch (e) {
         // Every way of getting this wrong - a blank token, a grant with no name, an empty map -
@@ -853,15 +955,24 @@ const runMcp = async (argv) => {
             process.exit(1);
         }
     }
+    const credentialFor = scriptsDir ? scriptCredentialsFor(readAuth(argv, 'mcp'), network.name, 'mcp') : undefined;
+    const grantsPath = argument(argv, '--grants', '');
+    const aiGrants = grantsPath ? readAiGrants(grantsPath, 'mcp') : undefined;
     const running = await startMcp({ ...network, ...(contracts ? { contracts: resolve(contracts) } : {}), ...(argv.includes('--allow-exec') ? { allowExec: true } : {}),
         ...(scriptsDir ? { scripts: resolve(scriptsDir) } : {}),
+        ...(credentialFor ? { credentialFor } : {}),
         ...(scriptableBy.length ? { scriptableBy } : {}),
+        ...(aiGrants ? { aiGrants } : {}),
+        onAiDecision: aiDecisionReporter('mcp'),
         ...(doorPort ? { port: doorPort, host: doorHost, ...(doorToken ? { doorToken } : {}) } : {}) }).catch((e) => {
         // The refusal a wide bind without a token earns arrives here, with its sentence intact.
         process.stderr.write(`source-rpc ${e.message}\n`);
         process.exit(1);
     });
     // Nothing is written to stdout here: it carries the protocol. See mcp.ts.
+    if (scriptsDir || aiGrants)
+        for (const line of grantLines(aiGrants))
+            process.stderr.write(`source-rpc mcp: ${line}\n`);
     const stop = () => void running
         .close()
         .then(() => process.exit(0))
@@ -881,7 +992,17 @@ const runNode = async (argv) => {
         process.stderr.write('source-rpc node: needs --scripts <dir> and at least one --scriptable-by <peer>, or it offers nothing to anybody\n');
         process.exit(1);
     }
-    const running = await startNode({ ...network, scripts: resolve(scriptsDir), scriptableBy }).catch((e) => {
+    const credentialFor = scriptCredentialsFor(readAuth(argv, 'node'), network.name, 'node');
+    const grantsPath = argument(argv, '--grants', '');
+    const aiGrants = grantsPath ? readAiGrants(grantsPath, 'node') : undefined;
+    const running = await startNode({
+        ...network,
+        scripts: resolve(scriptsDir),
+        scriptableBy,
+        ...(credentialFor ? { credentialFor } : {}),
+        ...(aiGrants ? { aiGrants } : {}),
+        onAiDecision: aiDecisionReporter('node')
+    }).catch((e) => {
         process.stderr.write(`source-rpc node: cannot start: ${e.message}\n`);
         process.exit(1);
     });
@@ -898,6 +1019,12 @@ const runNode = async (argv) => {
         // node is unreachable for the thing it exists to do. Said now rather than discovered as a
         // Forbidden on the other machine.
         process.stderr.write('source-rpc node: on a broker without --sign nothing can prove who a caller is, so every scripting call will be refused. Give both ends keys.\n');
+    // Said whether or not a document was given, because closed-by-default means "it is running" and
+    // "it can do something" are separately true, and this node's scripts carry `ai-program`.
+    for (const line of grantLines(aiGrants))
+        process.stderr.write(`source-rpc node: ${line}\n`);
+    if (grantsPath)
+        reloadGrantsOnHangUp(grantsPath, aiGrants, running.setAiGrants, 'node');
     const stop = () => void running
         .close()
         .then(() => process.exit(0))
@@ -937,6 +1064,79 @@ const runConsole = async (argv) => {
     process.on('SIGINT', stop);
     process.on('SIGTERM', stop);
 };
+const taskStartedLine = (task) => {
+    if (task.type === 'console')
+        return `${task.id}: console ${task.name} on ${task.url}`;
+    if (task.type === 'node')
+        return `${task.id}: node ${task.name}`;
+    return `${task.id}: serve ${task.name} answering ${task.namespaces?.join(', ')}`;
+};
+/**
+ * Writes a task file to start from, and refuses to write over one that is already there.
+ *
+ * Refusing matters more here than it usually does: the file it would replace holds signing secrets,
+ * and overwriting it does not lose a configuration that can be typed again - it loses the identity
+ * every other machine on the network was told to expect, and does it silently.
+ */
+const initTaskFile = (argv, file) => {
+    const skeleton = taskFileSkeleton({
+        ...(argument(argv, '--broker', '') ? { broker: argument(argv, '--broker', '') } : {}),
+        ...(argument(argv, '--hub', '') ? { hub: argument(argv, '--hub', '') } : {}),
+        ...(argument(argv, '--scriptable-by', '') ? { controller: argument(argv, '--scriptable-by', '') } : {})
+    });
+    try {
+        // wx rather than a check and a write: between the two there is a window, and the thing in it
+        // is a key file.
+        writeFileSync(file, `${JSON.stringify(skeleton, undefined, 4)}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    catch (e) {
+        const already = e.code === 'EEXIST';
+        process.stderr.write(`source-rpc run: ${already ? `${file} already exists, and it may hold this host's signing secrets - name a new file or move that one aside` : `cannot write ${file}: ${e.message}`}\n`);
+        process.exit(1);
+    }
+    for (const note of taskFileSkeletonNotes(file, argument(argv, '--scriptable-by', 'controller')))
+        process.stdout.write(`source-rpc run: ${note}\n`);
+};
+const runTasks = async (argv) => {
+    const [, named, ...extra] = positionals(argv);
+    if (extra.length) {
+        process.stderr.write(`source-rpc run: give it one task file, or none to use ./${defaultTaskFile}\n`);
+        process.exit(1);
+    }
+    const file = named ?? defaultTaskFile;
+    if (argv.includes('--init'))
+        return initTaskFile(argv, file);
+    // Checked before startTaskFile so that the answer to "run" with nothing set up is the thing to
+    // do next, rather than an ENOENT for a file the operator never mentioned.
+    if (!named && !existsSync(file)) {
+        process.stderr.write(`source-rpc run: no ${defaultTaskFile} here, and no task file named. Write one with 'source-rpc run --init', or name one.\n`);
+        process.exit(1);
+    }
+    const running = await startTaskFile(file, {
+        started: (task) => process.stdout.write(`source-rpc run: started ${taskStartedLine(task)}\n`),
+        warning: (message) => process.stderr.write(`source-rpc run: ${message}\n`)
+    });
+    process.stdout.write(`source-rpc run: ${running.tasks.length} tasks running from ${running.file}\n`);
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void running
+            .close()
+            .then(() => process.exit(0))
+            .catch((e) => {
+            process.stderr.write(`source-rpc run: shutdown failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exit(1);
+        });
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    // The same hang-up that re-reads a node's grants, for every node this file started.
+    if (process.platform !== 'win32')
+        process.on('SIGHUP', () => running.reloadGrants());
+    await new Promise(() => { });
+};
 const main = () => {
     // `source-rpc describe plantServer | head -4` closes stdout while there is still output to
     // write, and Node turns that into an unhandled 'error' event: a stack trace where a command
@@ -968,7 +1168,10 @@ const main = () => {
         process.exit(1);
     };
     if (command === 'strip') {
-        const files = positionals(argv);
+        // Past the command word, as every other verb here does. Without the slice the first file
+        // to be stripped is one called `strip`, which fails as a missing file rather than saying
+        // no file was named - and it means the command has never worked from the command line.
+        const files = positionals(argv).slice(1);
         const out = argument(argv, '--out', '');
         if (!files.length || !out) {
             process.stderr.write('source-rpc strip: give it one or more .ts files and --out <dir>, e.g. strip scripts/hello.ts --out scripts/stripped\n');
@@ -1004,6 +1207,10 @@ const main = () => {
         void runNode(argv).catch(fail);
         return;
     }
+    if (command === 'run') {
+        void runTasks(argv).catch(fail);
+        return;
+    }
     if (command === 'console') {
         void runConsole(argv).catch(fail);
         return;
@@ -1054,6 +1261,12 @@ const main = () => {
     }
     if (command !== 'extract' && command !== 'check') {
         process.stderr.write(usage);
+        // Pointed at rather than started. Typing the bare command is what someone does to see what
+        // this is, and answering that by joining a bus under whatever identities happen to be in
+        // this directory - and opening a console, and possibly making the machine scriptable -
+        // would be a great deal to have happen while reading the help.
+        if (!command && existsSync(defaultTaskFile))
+            process.stderr.write(`\nthere is a ${defaultTaskFile} here: 'source-rpc run' starts it\n`);
         process.exit(command ? 1 : 0);
     }
     const { schema, diagnostics } = extractSchema(project);