toolroll 0.9.42 → 0.9.44

package/dist/operate.js

@@ -84,7 +84,7 @@ import { homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { releaseStalledUpdate, waitingUpdate } from "./toolroll-update.js";
 import { openStore, openStoreNoMigrate, CONCURRENT_WRITER_WAIT_MS, isDatabaseBusy, databasePath, BUILT_IN, DEFAULT_ACTOR, parseCapabilityKey, verifiedAuthor, contestantProfileOf, isDigestTime, RESULT_SCREENSHOTS, } from "./store.js";
-import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomInt, randomUUID } from "node:crypto";
 import { authorizePlanUnderMode } from "./plan-auto.js";
 import { ghDispatchAdapter, mirrorTaskId, syncPass } from "./sync.js";
 import { sweepLiveLogs } from "./live.js";
@@ -150,10 +150,12 @@ import { daemonLaunchCommand, daemonStatus, installReplacingLegacy, installedLeg
 import { bridgePass, clearBotToken, createTransport, followBridge, hashPairingCode, loadBotToken, mintPairingCode, networkFence, networkFenceLine, redactToken, saveBotToken, PAIRING_TTL_MS, TOKEN_ENV, telegramHookSecret, telegramPushUrl, } from "./telegram.js";
 import { scanRepo } from "./capscan.js";
 import { computeGaps, describeCapability } from "./gaps.js";
-import { ask, askHidden, confirm, interactive, underAgent } from "./prompt.js";
+import { ask as promptAsk, askHidden as promptHidden, confirm as promptConfirm, interactive as promptInteractive, underAgent } from "./prompt.js";
 import { runMateCli, answerContextLines } from "./mate-cli.js";
 import { confirmCoordinatorProposal, dismissCoordinatorProposal } from "./mate-doors.js";
-import { verifyApproverByPassword } from "./principal.js";
+import { verifyApproverByPassword as approverByPassword } from "./principal.js";
+import { activeRemote, REMOTE_MESSAGES, REMOTE_REFUSED_FLAGS, REMOTE_SCOPES, RemoteRefusal, remoteAllows, remoteProjectOf, remoteRowOf, remoteSecret, reproveRemote, withRemote } from "./operate-remote.js";
+import { projectAuthority } from "./project-access.js";
 import { authorizedProject, canonicalProject, projectName, resolveCeiling } from "./project.js";
 import { tally, spendLine } from "./summary.js";
 import { bodyHashOf, describePublicationGrant, observeChecks, publicationBody, publishPass, sweepMerges, } from "./publish.js";
@@ -169,7 +171,7 @@ import { register, authenticate, heartbeat as heartbeatRunner, isAlive, recoverD
 import { mintCoordinator, revokeCoordinator, listCoordinators } from "./coordinator.js";
 import { serveMcp } from "./mcp.js";
 import { createInterface } from "node:readline";
-import { propose, approve, addApprover, authenticateAccount, authenticateApprover, describeScope, approvalOf, hashToken as hashApproverToken, profileFromJson, fileAndSealUnderMode, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha } from "./scope.js";
+import { propose, approve, addApprover, authenticateAccount, authenticateApprover as passwordApprover, describeScope, approvalOf, hashToken as hashApproverToken, profileFromJson, fileAndSealUnderMode, modeFilingCoverage, acceptanceLinesToInput, parseAcceptanceCriteria, splitAcceptanceRubric, rubricIsPlaceholder, isCommitSha } from "./scope.js";
 import { presetTerms, modeTermsJson, modeDigestOf, modeTermsFromJson, modeWords, MODE_MAX_DAYS } from "./modes.js";
 import { WorktreePool } from "./worktree.js";
 import { requestTaskStop, resumeTaskStop, taskControlOf } from "./task-control.js";
@@ -204,6 +206,7 @@ import { readPulls } from "./pulls.js";
 import { startMaintenance } from "./maintenance.js";
 import { livePin, modelWatchPass } from "./model-catalog.js";
 import { runModelsCommand } from "./models-cli.js";
+import { ALL_PROJECTS, chatApprovalSettings, chatApprovalWords, setChatApproval } from "./chat-approval.js";
 import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
 import { beads } from "./beads.js";
 import { githubIssues } from "./issues.js";
@@ -470,6 +473,8 @@ Flows — processes cards move through; the console's rules
   toolroll flows script save --repo <path> --name <name> (--file <path in project> | --body <file>)
       --about "<one line>" [--language shell|python|node] [--timeout-minutes <n>]
   toolroll flows card add <id> --title <t> [--description <d>] [--zone <zone>]
+  toolroll flows card approve <id> <card> [--option <words|number>]
+  toolroll flows card send-back <id> <card> --note <text>
   toolroll flows archive <id>
       writes take --as <you> --token <t> (or the remembered login); create,
       edit, archive and trigger add preview until --yes
@@ -639,7 +644,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "max", "cap", "probe", "kind", "expires", "cmd", "since", "repair-model",
     "choose", "note", "max-open-decisions", "max-held-sessions", "name", "days", "publication", "auto-approve", "review-auto", "entries", "port", "host", "allow-host",
     "for", "tick-every", "bridge-every", "reconcile-every", "incarnation",
-    "say", "ceiling-usd",
+    "say", "ceiling-usd", "cap-usd",
     "token-file", "bin", "poll", "github", "remote", "head-prefix", "password",
     // v102: project rules.
     "not-requester", "protect", "protect-paths",
@@ -658,7 +663,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     // onboard: the starter flows to switch on.
     "starter",
     // flows: templates, steps, scripts and cards.
-    "template", "steps", "about", "language", "timeout-minutes", "body", "description", "zone",
+    "template", "steps", "about", "language", "timeout-minutes", "body", "description", "zone", "option",
     "token-env", "after", "repair-max-attempts", "consumer", "batch", "feedback", "source", "view", "cursor", "why", "supersedes", "decision", "sessions", "timeout",
     // pings follow responsibility: replacements.
     "replaced-by", "replaces",
@@ -671,7 +676,7 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
-    "self-heal", "plan-auto", "chat-approve", "repair-auto", "review-retry-auto", "no-local",
+    "self-heal", "plan-auto", "chat-approve", "full-access", "repair-auto", "review-retry-auto", "no-local",
     "html", "csv", "alerts-only",
     // v105: the full export.
     "zip",
@@ -820,6 +825,20 @@ export async function runOperate(command, argv, write, options = {}) {
             flags.delete("token");
         actor = { account: lead.owner, lead: true };
     }
+    try {
+        return await dispatchOn(command, positional, flags, parsed.repoList, { store, write, json, file, now, ...(actor === null ? {} : { leadToken: presented }) }, options, run => LEAD_COMMANDS.has(command) ? withActor(actor, run) : run());
+    }
+    finally {
+        store.close();
+    }
+}
+/**
+ * Run one command against an open store: the dispatcher both roads share. The caller owns the store (runOperate
+ * opens and closes its own; runOperateAs uses the server's and leaves it open) and says what the command runs
+ * inside (`enter`: the actor, and for a remote run its person and project).
+ */
+async function dispatchOn(command, positional, flags, repoList, base, options, enter) {
+    const { store, write, json, file, now } = base;
     // v105: a Claude turn anywhere in this command says its plan's usage windows; keep the latest.
     const dropLimitSink = pushLimitSink(reading => store.recordProviderLimits(reading, new Date()));
     // Filed tasks are sized by the owner's own fast classifier (never in tests, the demo, or with NO_TASK_CLASSIFIER).
@@ -832,11 +851,11 @@ export async function runOperate(command, argv, write, options = {}) {
     const clock = options.now === undefined ? () => new Date() : () => now;
     try {
         const run = () => dispatch(command, positional, flags, {
-            ...(actor === null ? {} : { leadToken: presented }),
+            ...(base.leadToken === undefined ? {} : { leadToken: base.leadToken }),
             store,
             write,
             json,
-            repoList: parsed.repoList,
+            repoList,
             now,
             clock,
             // Evidence lives beside the database for the same reason the database
@@ -870,10 +889,13 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.installBin === undefined ? {} : { installBin: options.installBin }),
             ...(options.onboardSeams === undefined ? {} : { onboardSeams: options.onboardSeams }),
             ...(options.upSeams === undefined ? {} : { upSeams: options.upSeams }),
+            ...(activeRemote() === null ? {} : { principal: activeRemote() }),
         });
-        return await (LEAD_COMMANDS.has(command) ? withActor(actor, run) : run());
+        return await enter(run);
     }
     catch (error) {
+        if (error instanceof RemoteRefusal)
+            return fail(write, json, command, error.reason, error.message, EXIT.refused);
         if (isDatabaseBusy(error))
             return databaseFailure(write, json, command, file, error);
         return fail(write, json, command, "failed", describe(error), EXIT.failed);
@@ -883,9 +905,95 @@ export async function runOperate(command, argv, write, options = {}) {
         await settleSizings();
         dropSizer();
         dropLimitSink();
-        store.close();
     }
 }
+/**
+ * Run one command on this server for a person who signed in with their own API token (the transport and MCP
+ * gateway prove the `so_` token and refuse browser origins; this is everything after). The command's row in the
+ * machine contract decides first: "no" and "step-up" rows, and commands with no row, are refused before any
+ * command code runs. The principal is re-proved against the store, a read token runs only reads, and the project
+ * the command touches must be one the person may use, named by --repo where a local run would use the working
+ * directory. The command then runs as that person: every credential check resolves to them, nothing prompts, and
+ * this machine's saved login and lead token are never read. Files are only those sent in `files`, keyed by the
+ * argument that names them. Every call is in the action history as the person, from source `api` (or `mcp`),
+ * with the token's name. The store is the caller's and stays open.
+ */
+export async function runOperateAs(argv, opts) {
+    const { principal, store, write } = opts;
+    const source = opts.source === "mcp" ? "mcp" : "api";
+    const options = opts.options ?? {};
+    const now = options.now ?? new Date();
+    const [root = "", ...rest] = argv;
+    const json = rest.includes("--json");
+    let invocation = root;
+    let tokenName = null;
+    const record = (outcome, repo, taskId, why) => {
+        store.recordAction({ at: (options.now ?? new Date()).toISOString(), actor: principal.account, repo, taskId, runId: null,
+            action: `remote command: ${invocation === "" ? "(none)" : invocation}`.slice(0, 200), outcome, source,
+            detail: `token ${tokenName ?? principal.tokenId}${why === null ? "" : ` · ${why}`}` });
+    };
+    const refuse = (reason, message, repo = null, taskId = null) => {
+        record("refused", repo, taskId, reason);
+        return fail(write, json, invocation === "" ? "remote" : invocation, reason, message, EXIT.refused);
+    };
+    const proved = reproveRemote(store, principal, now);
+    if (!proved.ok)
+        return refuse("unauthenticated", REMOTE_MESSAGES.stale);
+    tokenName = proved.tokenName;
+    // The row first, from the words before any flag: a refused command is refused whatever its flags say.
+    const firstFlag = rest.findIndex(one => one.startsWith("-"));
+    const row = remoteRowOf(root, firstFlag === -1 ? rest : rest.slice(0, firstFlag));
+    if (row === null)
+        return refuse("not-remote", REMOTE_MESSAGES.unknown);
+    invocation = row.invocation;
+    if (row.remote === "step-up")
+        return refuse("step-up", REMOTE_MESSAGES["step-up"]);
+    const scope = REMOTE_SCOPES.get(row.invocation);
+    if (row.remote !== "yes" || scope === undefined)
+        return refuse("not-remote", REMOTE_MESSAGES.no);
+    const parsed = parseOperateArgs(rest, root === "flows" ? FLOWS_VALUE_FLAGS : undefined);
+    if ("error" in parsed)
+        return refuse("usage", parsed.error);
+    // The parser's positionals must spell the same row (a value flag can't hide a subcommand).
+    if (remoteRowOf(root, parsed.positional)?.invocation !== row.invocation)
+        return refuse("not-remote", REMOTE_MESSAGES.unknown);
+    if (proved.scope === "read" && row.mutation !== "none")
+        return refuse("read-only", REMOTE_MESSAGES.read);
+    if ([...parsed.flags.keys()].some(name => REMOTE_REFUSED_FLAGS.has(name)))
+        return refuse("usage", REMOTE_MESSAGES.credential);
+    const allows = (repo) => remoteAllows(store, principal, repo);
+    const project = remoteProjectOf(store, { allows }, scope, parsed.positional, parsed.repoList, row.invocation, parsed.flags, opts.files ?? {});
+    if (!project.ok)
+        return refuse(project.reason, project.message);
+    // The local mutation cache has a global key namespace. A token must not use a chosen key to read
+    // another person's/project's cached result. Revision keys already bind the actor and result in
+    // task-outcome-cli.ts, which also validates their public 32-hex format; leave those intact.
+    const key = text(parsed.flags, "key");
+    if (key !== undefined && row.invocation !== "task revise") {
+        parsed.flags.set("key", `remote:${createHash("sha256").update(JSON.stringify([principal.account, row.invocation, project.repo, project.taskId, key])).digest("hex")}`);
+    }
+    const file = store.databaseFile() ?? options.databaseFile;
+    if (file === undefined)
+        return refuse("failed", "The server's database has no file.", project.repo, project.taskId);
+    const run = Object.freeze({ account: principal.account, scope: proved.scope, tokenName: proved.tokenName, source, secret: remoteSecret(), allows, files: Object.freeze({ ...(opts.files ?? {}) }) });
+    record("requested", project.repo, project.taskId, null);
+    let code;
+    try {
+        code = await withRemote(run, () => dispatchOn(root, parsed.positional, parsed.flags, parsed.repoList, { store, write, json, file, now }, options, go => withActor({ account: principal.account, lead: false }, () => projectAuthority.run({ actor: principal.account, repo: project.repo }, go))));
+    }
+    catch (error) {
+        record("failed", project.repo, project.taskId, null);
+        throw error;
+    }
+    record(code === EXIT.ok ? "done" : code === EXIT.refused ? "refused" : code === EXIT.usage ? "usage" : "failed", project.repo, project.taskId, null);
+    return code;
+}
+/** A file a remote caller sent with the request, by the argument that names it; never a path on this machine. */
+function remoteFile(remote, path) {
+    if (Object.prototype.hasOwnProperty.call(remote.files, path))
+        return remote.files[path];
+    throw new RemoteRefusal("usage", REMOTE_MESSAGES.files);
+}
 /** The short commands a lead token works for, and where whoever signs in is recorded as the actor. */
 const LEAD_COMMANDS = new Set(["task", "assignment", "status", "ready", "brief", "peek", "check-progress", "notifications", "lead"]);
 /**
@@ -1088,6 +1196,8 @@ async function dispatch(command, positional, flags, context) {
             return proposalsCommand(positional, flags, context);
         case "mode":
             return modeCommand(positional, flags, context);
+        case "chat-approval":
+            return chatApprovalCommand(positional, flags, context);
         case "people":
             return peopleCommand(positional, flags, context);
         case "keys":
@@ -1153,6 +1263,9 @@ function openBackend(name, store, repo) {
 }
 /** The repository a backend command applies to, normalised like the grant is. */
 function repoFrom(flags) {
+    // The server's working directory is nobody's project: a remote caller names theirs.
+    if (activeRemote() !== null && text(flags, "repo") === undefined)
+        throw new RemoteRefusal("unknown-project", REMOTE_MESSAGES.project);
     return resolve(text(flags, "repo") ?? process.cwd());
 }
 // ---- the dispatch loop ----------------------------------------------------
@@ -5755,6 +5868,51 @@ async function peopleCommand(positional, flags, context) {
     ]);
 }
 const MODE_ACTIONS = ["set", "show", "revoke"];
+/** `chat-approval show | on | off [--repo <path>]`: the person's lasting choice to approve plans and merges from their
+ * paired chat (chat-approval.ts), for all their projects or one. On (or wider limits) previews until --yes and takes
+ * the password, like Settings; off is one step. Either way a ledger line. */
+async function chatApprovalCommand(positional, flags, context) {
+    const { store, write, json, clock } = context;
+    const action = positional[0] ?? "show";
+    const command = `chat-approval ${action}`;
+    if (!["show", "on", "off"].includes(action))
+        return fail(write, json, "chat-approval", "usage", "Use chat-approval show | on | off [--repo <path>] [--full-access] [--cap-usd <n>] [--yes].", EXIT.usage);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "unauthenticated", "Approving from chat is your own setting: pass --as <you> --token <your password> (or sign in once with toolroll up).", EXIT.refused);
+    const authed = authenticateApprover(store, acting.name, acting.token);
+    if (!authed.ok)
+        return fail(write, json, command, "unauthenticated", "That name and password aren't an approver's. Nothing was changed.", EXIT.refused);
+    const given = text(flags, "repo");
+    const scope = given === undefined ? ALL_PROJECTS : canonicalProject(given) ?? resolve(given);
+    if (scope !== ALL_PROJECTS && !store.accountCanAccess(acting.name, scope))
+        return fail(write, json, command, "unknown-project", "That isn't one of your projects.", EXIT.refused);
+    const where = scope === ALL_PROJECTS ? "all your projects" : projectName(scope);
+    if (action === "show") {
+        const rows = chatApprovalSettings(store, acting.name).map(one => ({ scope: one.scope === ALL_PROJECTS ? "all" : one.scope, enabled: one.enabled, fullAccess: one.fullAccess, capMicrousd: one.capMicrousd, updatedAt: one.updatedAt }));
+        return succeed(write, json, command, { settings: rows }, () => rows.length === 0 ? ["Approving from chat is off everywhere. Turn it on: toolroll chat-approval on [--repo <path>]"]
+            : rows.map(one => `${one.scope === "all" ? "All projects" : projectName(one.scope)}: ${one.enabled ? `on · ${chatApprovalWords(one)}` : "off"}`));
+    }
+    const now = clock();
+    if (action === "off") {
+        const saved = setChatApproval(store, { approver: acting.name, scope, enabled: false, via: "the command line" }, now);
+        return saved.ok ? succeed(write, json, command, { applied: true, scope: scope === ALL_PROJECTS ? "all" : scope }, () => [saved.said]) : fail(write, json, command, "refused", saved.message, EXIT.refused);
+    }
+    const usd = text(flags, "cap-usd");
+    const cap = usd === undefined ? null : Number(usd);
+    if (cap !== null && !(Number.isFinite(cap) && cap >= 0 && cap <= 10_000))
+        return fail(write, json, command, "usage", "Give --cap-usd in dollars, like 5.", EXIT.usage);
+    const limits = { fullAccess: flag(flags, "full-access"), capMicrousd: cap === null ? null : Math.round(cap * 1_000_000) };
+    const terms = [
+        `Your own taps in your paired chat approve plans and merges in ${where}, until you turn it off: it doesn't expire.`,
+        `Limits: ${chatApprovalWords(limits)}.`,
+        "Plans written for you, protected paths, two-person rules and your organisation's policy still open in Toolroll.",
+    ];
+    if (!flag(flags, "yes"))
+        return succeed(write, json, command, { applied: false, scope: scope === ALL_PROJECTS ? "all" : scope, terms }, () => [`Turn on approving from chat for ${where}`, ...terms.map(one => `  ${one}`), "", "Nothing has changed. Add --yes to make this change."]);
+    const saved = setChatApproval(store, { approver: acting.name, scope, enabled: true, limits, via: "the command line" }, now);
+    return saved.ok ? succeed(write, json, command, { applied: true, scope: scope === ALL_PROJECTS ? "all" : scope, terms }, () => [saved.said]) : fail(write, json, command, "refused", saved.message, EXIT.refused);
+}
 async function modeCommand(positional, flags, context) {
     const { store, write, json, clock } = context;
     const [action] = positional;
@@ -8166,6 +8324,9 @@ export function writeLoginFileDurably(path, name, password) {
     }
 }
 function readLoginFile(path) {
+    // The owner's saved login is never anyone else's: a remote run that reaches here is a bug, and ends refused.
+    if (activeRemote() !== null)
+        throw new RemoteRefusal("unauthenticated", REMOTE_MESSAGES.credential);
     try {
         const raw = readFileSync(path, "utf8").trim();
         const cut = raw.indexOf(" ");
@@ -10233,7 +10394,8 @@ async function addTask(positional, flags, context) {
             ...(mirrored === null ? [] : [`Mirrored locally as ${mirrored} — scope and approve it, and this plane builds it.`]),
         ]);
     }
-    const id = text(flags, "id") ?? slug(title, now);
+    // Remote creation cannot probe global IDs, including predictable title/time collisions.
+    const id = text(flags, "id") ?? (activeRemote() === null ? slug(title, now) : `task-${randomBytes(16).toString("hex")}`);
     // Re-filing: the new task replaces an earlier one, which is cancelled and reads "Replaced by <id>".
     const replaces = text(flags, "replaces");
     if (replaces !== undefined && (replaces === id || store.getTask(replaces) === null)) {
@@ -10256,12 +10418,21 @@ async function addTask(positional, flags, context) {
     if (!outcome.ok) {
         return fail(write, json, "task add", "exists", `\`${id}\` already exists`, EXIT.refused);
     }
-    store.stampFiledVia(store.refFor(BUILT_IN, id).id, "cli");
+    const filedId = outcome.task.id;
+    const remote = activeRemote();
+    if (remote !== null && filedId !== id) {
+        // Re-prove a replayed creation too: it may have been moved since the original filing.
+        const saved = store.lookupRef(filedId);
+        if (saved === null || saved.repo !== text(flags, "repo") || !remote.allows(saved.repo)) {
+            throw new RemoteRefusal("not-found", "Not found.");
+        }
+    }
+    store.stampFiledVia(store.refFor(BUILT_IN, filedId).id, "cli");
     // Placement is explicit, never inferred from where the command happened to
     // run: a task filed from the wrong directory would silently bind to it.
     const placedIn = text(flags, "repo");
     if (placedIn !== undefined) {
-        const placed = store.placeTask(store.refFor(BUILT_IN, id).id, canonicalProject(placedIn) ?? resolve(placedIn));
+        const placed = store.placeTask(store.refFor(BUILT_IN, filedId).id, canonicalProject(placedIn) ?? resolve(placedIn));
         if (typeof placed === "object" && !placed.ok) {
             return fail(write, json, "task add", "scoped", "this task already has a scope — placement is immutable once somebody could have approved it", EXIT.refused);
         }
@@ -11970,6 +12141,10 @@ async function chatCommand(flags, context) {
  * win, and a different --as than the remembered name is not answered.
  */
 function credentialsFrom(flags, context) {
+    // A remote run is its token's person, whatever the flags or this machine's saved login say.
+    const remote = activeRemote();
+    if (remote !== null)
+        return { name: remote.account, token: remote.secret };
     // The lead signs in as its owner with its own token, never the owner's password.
     const lead = currentActor();
     if (context.leadToken !== undefined && lead?.lead === true)
@@ -11995,16 +12170,55 @@ async function askCredentials(flags, context) {
         return null;
     return { name, token };
 }
+/*
+ * Credential checks in this file. Locally they are the password checks in scope.ts and principal.ts. Inside a
+ * remote run (`runOperateAs`) the only credential is the one credentialsFrom handed out for the token's person,
+ * which scope.ts's authenticateAccount takes as that person (a viewer for a read token) and never checks as a
+ * password; these add the token's own project limit.
+ */
+function authenticateApprover(store, by, token, repo) {
+    const remote = activeRemote();
+    if (remote !== null && repo !== undefined && !remote.allows(repo))
+        return { ok: false, reason: "not-an-approver" };
+    return passwordApprover(store, by, token, repo);
+}
+function verifyApproverByPassword(store, name, token, repos) {
+    const remote = activeRemote();
+    return approverByPassword(store, name, token, remote === null ? repos : repos.filter(repo => remote.allows(repo)));
+}
+/** Prompts: never inside a remote run — there is nobody at this machine's terminal to answer for the person. */
+function interactive() {
+    return activeRemote() === null && promptInteractive();
+}
+function refusePrompt() {
+    if (activeRemote() !== null)
+        throw new RemoteRefusal("unauthenticated", REMOTE_MESSAGES.credential);
+}
+async function ask(question) {
+    refusePrompt();
+    return promptAsk(question);
+}
+async function askHidden(question) {
+    refusePrompt();
+    return promptHidden(question);
+}
+async function confirm(question) {
+    refusePrompt();
+    return promptConfirm(question);
+}
 /** `flows …`: the console's flow rules from a terminal. Writes are an approver's (--as/--token or the remembered login). */
 async function flowsCommand(positional, flags, context) {
     const { store } = context;
     const registered = await loadRepos(registryPathOf(context)).catch(() => ({ error: "unreadable" }));
-    const projects = [...new Set([...store.knownRepos(), ...store.listProjects().map(one => one.path), ...("error" in registered ? [] : registered.repos)])];
+    const remote = activeRemote();
+    // A remote person sees and changes flows only in their own projects, and sends any flow file with the request.
+    const projects = [...new Set([...store.knownRepos(), ...store.listProjects().map(one => one.path), ...("error" in registered ? [] : registered.repos)])].filter(one => remote === null || remote.allows(one));
     const writes = positional[0] !== undefined && positional[0] !== "list" && positional[0] !== "show" && positional[0] !== "export";
     const acting = writes && !flags.has("help") ? await askCredentials(flags, context) : null;
     const dir = dirname(context.databaseFile);
     return runFlowsCommand(positional, flags, {
         store, write: context.write, json: context.json, clock: context.clock, credentials: acting, projects, configDir: dir, evidenceRoot: context.evidenceRoot,
+        ...(remote === null ? {} : { readInput: (path) => remoteFile(remote, path) }),
         ...(context.flowFetch === undefined ? {} : { fetchFlow: context.flowFetch }),
         // "Check now": the same io the worker's pass checks triggers with.
         triggerIo: { gh: context.flowTriggerIo?.gh ?? run, fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dir,

package/dist/process-recovery-eligibility.d.ts

@@ -50,7 +50,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
             digest: string;
             approvedAt: string;
             approvedBy: string;
-            approvalBasis: "mode" | "password";
+            approvalBasis: "chat" | "mode" | "password";
             modeDigest: string | null;
         };
         readonly command: {

package/dist/remote-command.d.ts

@@ -0,0 +1,45 @@
+import { type CommandFlag } from './surface.js';
+export type RemoteMode = 'yes' | 'no' | 'step-up';
+export type RemoteCommand = {
+    invocation: string;
+    mode: RemoteMode;
+    mutation: string;
+    flags?: readonly Pick<CommandFlag, 'name' | 'takesValue'>[];
+};
+export type RemoteCommandLookup = (argv: readonly string[]) => RemoteCommand | null;
+export declare const STEP_UP_MESSAGE = "approve in the console or chat";
+type PathPolicy = 'inline' | 'refuse';
+export type RemotePathArgument = {
+    invocation: string;
+    argument: {
+        flag: string;
+    } | {
+        position: number;
+        name: string;
+        rest?: true;
+    };
+    policy: PathPolicy;
+    literal?: 'json' | 'url';
+};
+/**
+ * Filesystem arguments audited against operate.ts, flows-cli.ts and cli.ts's local dispatchers.
+ * Keep this inventory command-specific: --file runs a project executable for scripts, but is a
+ * boolean for template apply; --to is a directory for link and a date for ledger export.
+ * Project selectors (--repo), scope globs (--touches/--paths) and saved IDs are not input files;
+ * their authority belongs to runOperateAs. Local installers' explicit destinations are refused.
+ * '*' is reserved for the credentials/database and cli.ts's output redirection, on every command.
+ */
+export declare const REMOTE_PATH_ARGUMENTS: readonly RemotePathArgument[];
+type FileProblem = {
+    problem: string;
+    code: 'local-only-flag' | 'server-path' | 'missing-file' | 'invalid-arguments';
+};
+/**
+ * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a
+ * file positional. Unknown arity fails closed. File keys and argv stay exactly as typed.
+ * All failures describe the argument slot, never a supplied path, credential or other value.
+ */
+export declare function fileArguments(argv: readonly string[], row: RemoteCommand): string[] | FileProblem;
+/** The longest declared invocation named by the leading words. Missing remote metadata means local only. */
+export declare const contractRow: RemoteCommandLookup;
+export {};

package/dist/remote-command.js

@@ -0,0 +1,124 @@
+import { COMMAND_GUIDE } from './surface.js';
+export const STEP_UP_MESSAGE = 'approve in the console or chat';
+/**
+ * Filesystem arguments audited against operate.ts, flows-cli.ts and cli.ts's local dispatchers.
+ * Keep this inventory command-specific: --file runs a project executable for scripts, but is a
+ * boolean for template apply; --to is a directory for link and a date for ledger export.
+ * Project selectors (--repo), scope globs (--touches/--paths) and saved IDs are not input files;
+ * their authority belongs to runOperateAs. Local installers' explicit destinations are refused.
+ * '*' is reserved for the credentials/database and cli.ts's output redirection, on every command.
+ */
+export const REMOTE_PATH_ARGUMENTS = [
+    ...['--token', '--token-file', '--token-env', '--db', '-o', '--output'].map(flag => ({ invocation: '*', argument: { flag }, policy: 'refuse' })),
+    { invocation: 'flows create', argument: { flag: '--steps' }, policy: 'inline', literal: 'json' },
+    { invocation: 'flows edit', argument: { flag: '--steps' }, policy: 'inline', literal: 'json' },
+    { invocation: 'flows script save', argument: { flag: '--body' }, policy: 'inline' },
+    { invocation: 'flows script save', argument: { flag: '--file' }, policy: 'refuse' },
+    { invocation: 'flows export', argument: { flag: '--out' }, policy: 'refuse' },
+    // Import stats the original path before readInput. Inlining alone cannot prevent that server read.
+    { invocation: 'flows import', argument: { position: 0, name: 'file' }, policy: 'refuse', literal: 'url' },
+    { invocation: 'flows trigger add', argument: { position: 1, name: 'trigger' }, policy: 'inline', literal: 'json' },
+    { invocation: 'task evidence', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'ledger export', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'export', argument: { flag: '--out' }, policy: 'refuse' },
+    { invocation: 'restore', argument: { position: 0, name: 'backup file' }, policy: 'refuse' },
+    { invocation: 'storage discard', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
+    { invocation: 'keys set', argument: { flag: '--key-file' }, policy: 'refuse' },
+    { invocation: 'daemon', argument: { flag: '--bin' }, policy: 'refuse' },
+    ...['build', 'tick', 'reconcile', 'watch', 'serve', 'up', 'daemon', 'task resume'].map(invocation => ({ invocation, argument: { flag: '--pool' }, policy: 'refuse' })),
+    ...['serve', 'up'].map(invocation => ({ invocation, argument: { flag: '--project-root' }, policy: 'refuse' })),
+    { invocation: 'skills install', argument: { flag: '--dir' }, policy: 'refuse' },
+    { invocation: 'skills install', argument: { flag: '--repo' }, policy: 'refuse' },
+    { invocation: 'onboard', argument: { flag: '--repo' }, policy: 'refuse' },
+    { invocation: 'repos add-from-github', argument: { flag: '--root' }, policy: 'refuse' },
+    ...['link', 'unlink'].map(invocation => ({ invocation, argument: { flag: '--to' }, policy: 'refuse' })),
+    ...['repos add', 'repos remove', 'pulls', 'graph', ''].map(invocation => ({ invocation, argument: { position: 0, name: 'path', rest: true }, policy: 'refuse' })),
+    { invocation: 'project use', argument: { position: 0, name: 'checkout path' }, policy: 'refuse' },
+    // These local HTTP clients read prompts themselves; they do not consume runOperateAs's files map.
+    ...['session start', 'session send'].map(invocation => ({ invocation, argument: { flag: '--file' }, policy: 'refuse' })),
+];
+/**
+ * Parse once using declared arity, so a flag's value cannot be mistaken for another flag or a
+ * file positional. Unknown arity fails closed. File keys and argv stay exactly as typed.
+ * All failures describe the argument slot, never a supplied path, credential or other value.
+ */
+export function fileArguments(argv, row) {
+    const paths = [];
+    const rules = REMOTE_PATH_ARGUMENTS.filter(one => one.invocation === '*' || one.invocation === row.invocation);
+    const words = row.invocation === '' ? [] : row.invocation.split(' ');
+    if (!words.every((word, index) => argv[index] === word))
+        return { problem: 'The command arguments do not match its invocation.', code: 'invalid-arguments' };
+    const inspect = (rule, value) => {
+        const label = 'flag' in rule.argument ? rule.argument.flag : `${row.invocation} ${rule.argument.name} argument`;
+        if (rule.invocation === '*' && 'flag' in rule.argument && rule.argument.flag !== '-o' && rule.argument.flag !== '--output') {
+            return { problem: `${label} cannot be used remotely. Sign in with your saved API token.`, code: 'local-only-flag' };
+        }
+        if (value !== undefined && (rule.literal === 'json' && /^[{[]/.test(value.trim()) || rule.literal === 'url' && /^[a-z][a-z0-9+.-]*:\/\//i.test(value)))
+            return;
+        if (rule.policy === 'refuse')
+            return { problem: `${label} cannot use a server path remotely. Use --local to run it here.`, code: 'server-path' };
+        if (value === undefined || value === '')
+            return { problem: `${label} needs a file path.`, code: 'missing-file' };
+        // '-' would otherwise read the server's stdin (or a client file literally named '-'). Never prompt.
+        if (value === '-')
+            return { problem: `${label} needs a file instead of stdin for a remote command.`, code: 'server-path' };
+        paths.push(value);
+    };
+    let position = 0;
+    for (let index = words.length; index < argv.length; index++) {
+        const argument = argv[index], equals = argument.indexOf('=');
+        const name = equals < 0 ? argument : argument.slice(0, equals);
+        if (argument.startsWith('--') || name === '-o' || name === '-h') {
+            const rule = rules.find(one => 'flag' in one.argument && one.argument.flag === name);
+            const takesValue = rule !== undefined ? true : name === '-h' || name === '--help' || name === '--json' ? false : row.flags?.find(flag => `--${flag.name}` === name)?.takesValue;
+            if (takesValue === undefined)
+                return { problem: 'This option is not declared for remote use. Use --local to run it here.', code: 'invalid-arguments' };
+            if (!takesValue) {
+                if (equals >= 0)
+                    return { problem: 'This command switch does not take a value.', code: 'invalid-arguments' };
+                continue;
+            }
+            const next = equals < 0 ? argv[index + 1] : argument.slice(equals + 1);
+            const value = equals < 0 && next?.startsWith('--') ? undefined : next;
+            if (rule !== undefined) {
+                const problem = inspect(rule, value);
+                if (problem !== undefined)
+                    return problem;
+            }
+            if (value === undefined)
+                return { problem: 'A command option needs a value.', code: 'invalid-arguments' };
+            if (equals < 0)
+                index++;
+        }
+        else {
+            const rule = rules.find(one => 'position' in one.argument && (one.argument.position === position || one.argument.rest && position >= one.argument.position));
+            if (rule !== undefined) {
+                const problem = inspect(rule, argument);
+                if (problem !== undefined)
+                    return problem;
+            }
+            position++;
+        }
+    }
+    return paths;
+}
+/** The longest declared invocation named by the leading words. Missing remote metadata means local only. */
+export const contractRow = argv => {
+    const words = [];
+    for (const one of argv) {
+        if (one.startsWith('-'))
+            break;
+        words.push(one);
+    }
+    let best = null;
+    for (const row of COMMAND_GUIDE) {
+        const parts = row.invocation.split(' ');
+        if (parts.length > words.length || !parts.every((part, index) => words[index] === part))
+            continue;
+        if (best !== null && best.invocation.split(' ').length >= parts.length)
+            continue;
+        const remote = row.remote;
+        best = { invocation: row.invocation, mode: remote === 'yes' || remote === 'step-up' ? remote : 'no', mutation: row.mutation, flags: row.flags ?? [] };
+    }
+    return best;
+};

package/dist/remote-exec.d.ts

@@ -0,0 +1,18 @@
+import { type TeamCliOptions } from './team-cli.js';
+import { type RemoteCommandLookup } from './remote-command.js';
+export { contractRow, STEP_UP_MESSAGE, type RemoteMode } from './remote-command.js';
+export type RemoteExecOptions = TeamCliOptions & {
+    cwd?: string;
+    /** Raw output streams; remote bytes are written exactly as the server returned them. */
+    stdout?: (chunk: string) => void;
+    stderr?: (chunk: string) => void;
+    /** Injected by tests: the contract row lookup (default: COMMAND_GUIDE's `remote` field). */
+    modeOf?: RemoteCommandLookup;
+};
+/**
+ * null: run locally with argv unchanged. `{ local }`: run locally with this argv (`--local` removed).
+ * A number: the command ran remotely (or was refused before sending) and this is its exit code.
+ */
+export declare function maybeRunRemoteCommand(argv: readonly string[], options?: RemoteExecOptions): Promise<number | {
+    local: string[];
+} | null>;